# RELKIT

> Build TypeScript backends with guided examples, module documentation, and API reference.

# Introducing Relkit
Source: https://relkit.dev/blog/introducing-relkit

I’ve spent years building products end to end: backends, web and mobile frontends, and sometimes even the designs in Sketch and Figma. And every new project started the same way. Before writing a single line of business logic, I was wiring up auth, a database, Redis, a job queue, API docs, a typed client for the frontend team, logging…

I always wanted something that would take care of all of that, every setup and every decision, and just let me focus on the product.

## Relkit

I built Relkit from a developer-experience perspective. That was 99% of my focus while working on the first implementation with my coding agents :)

Just to be clear from the start: Relkit is a **backend** framework. It doesn’t care what’s on the other side. React, Vue, Svelte, a mobile app or even another server can all talk to it: every route is plain REST with an OpenAPI spec, and TypeScript callers get a generated typed client on top.

Relkit covers almost everything your application might need:

- Authentication
- Database
- Realtime channels
- Streaming
- Events (pub/sub)
- Caching
- Storage
- Background jobs
- AI agents, graphs, nodes and MCP
- A generated typed client for your frontend (your frontend teammate will never ask you about an endpoint again)
- OpenAPI out of the box, with an optional Scalar API reference UI
- Observability done under the hood
- Docker support for local providers (Redis, MinIO, Inngest and friends)
- An Inspector that lets you visualize every piece of your application without reading a single line of code

And you won’t wire any of this by hand. Relkit ships with a CLI that does the heavy lifting, from creating the project to scaffolding every piece you’ll see in this article:

```bash
bunx create-relkit@latest my-app
cd my-app
bun run dev
```

From there, `bun run relkit add …` creates functions, routes, services, caches, buckets, jobs, agents and more, and installs whatever each piece needs. You’ll see it at the start of almost every section below.

## Inspector

This is my favorite feature so far. Every piece of your code is presented in a clean UI that you can visualize and test. It’s very useful when you join an existing project, and just as useful when your agents are doing a lot of stuff and you want to keep up from a high-level perspective.

In the Inspector you can see your application graph and how the pieces connect. You can see your agents, tools, functions, caches, database tables, jobs and storage files, plus the observability stuff like logs, traces and environments.

![The Relkit Inspector showing the Routes page for the active workspace](/blog/introducing-relkit/inspector-routes.png)

It’s an optional companion, so you turn it on when you want it:

```bash
bun run relkit add inspector
bun run relkit inspector   # opens on http://localhost:3210
```

Throughout this article we’ll build one small thing: an **orders** backend. Every section adds one piece to it, so by the end you’ll have seen the whole kit working together.

## Functions

Functions are the heartbeat of Relkit. Every function is one piece of your system, responsible for one small, clear job. Keeping them that small helps in a lot of ways: testing gets easy, and you can compose little pieces to achieve a bigger task.

To create a function, start with the Relkit CLI:

```bash
bun run relkit add function create-order
```

The CLI is interactive, so it simply asks you for anything it needs (like which service the function belongs to). Every command also has flags for scripts and CI, but you won’t need them to get started.

This generates a file you then fill in, something like this:

```ts
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
const createOrder = defineFunction({
  input: z.object({}),
  output: z.object({}),
  publishes: ["orders.created"],
  handler: async (input, context) => {
    const order = {};
    await context.events["orders.created"].publish(order);
    return order;
  },
});
export default createOrder;
```

Fill `input` and `output` with your own schemas; they're validated on every call, and `publishes` is how a function declares, up front, which events it's allowed to send. No surprise side effects.

You can use the same function in different places:

- Inside its own domain, call it directly: `createOrder.invoke({ ... })`
- From another domain, go through its service: `orders.createOrder.invoke({ ... })`
- From HTTP, give it to a route as a target: `defineRoute({ target: orders.createOrder })`

And since it’s just a function, testing it doesn’t need a server: `invokeFunction(orders.createOrder, { ... })` from `@relkit/testing` and you're done.

Functions aren’t locked inside handlers either. A function is just a module you import, so any backend code in your app can call it, and it still goes through the same validation, timeouts and tracing as an HTTP request:

```ts
import orders from "@app/services/orders/service.js";
const order = await orders.createOrder.invoke({});
```

The same goes for other pieces: start a job with `orders.exportOrders.trigger(input)` or push a live update with `orderStatus.trigger(...)`, straight from a route or any other backend code. The one thing that stays inside a function is resource access. Caches, buckets and the database reach you through the function’s `context`, so every access is declared and shows up in the graph.

## Routes

Routes are inspired by the Next.js style: they follow your directory structure, and the location of the file decides the endpoint. If you have a route at `src/routes/orders/[orderId]/route.ts`, you get an endpoint at `/orders/:orderId`.

To create one with the CLI, just give it the URL (it will ask which service function each HTTP method should call):

```bash
bun run relkit add route /orders/:orderId
```

This generates:

```ts
import { defineServiceRoutes } from "@relkit/app/routes";
import orders from "@app/services/orders/service.js";
export const { GET } = defineServiceRoutes(orders, {
  GET: "getOrder",
});
```

Need just one method? `defineRoute` is the single version:

```ts
// src/routes/orders/route.ts → POST /orders
export const POST = defineRoute({
  target: orders.createOrder,
  successStatus: 201,
});
```

Notice the route has no business logic. It only says “this URL calls that function”, and the `orderId` from the path is mapped into the function's input for you. As a bonus, every route lands in the generated OpenAPI spec at `/_relkit/v1/openapi.json`.

## Scalar

Reading an OpenAPI JSON file is nobody’s idea of fun. Turn on Scalar and you get a beautiful, interactive API reference for every route, where you can fill in inputs and send real requests to try things out:

```bash
bun add @scalar/hono-api-reference
```

```ts
// relkit.config.ts
server: { apiDocs: { ui: "scalar" } },
```

Restart the app and open `http://localhost:3000/_relkit/v1/api-reference`. Every route is listed with its parameters, request body, responses and validation errors, all generated from the same schemas your functions use. Change a schema and the docs change with it.

![The Scalar API reference sending a request to a Relkit route](/blog/introducing-relkit/scalar-api-reference.png)

Scalar is off in production by default, and turning it on there requires protecting the docs endpoints. Docs visibility isn’t access control.

## Services

You may have noticed that routes don’t import functions directly. They go through a **service**.

A service is the public front door of a domain. You organize your code by what your product does (orders, receipts, accounts), not by technology, and each domain gets its own folder:

```text
src/services/orders/
├── service.ts      ← the public front door
├── functions/      ← business operations
├── events/         ← facts this domain publishes
├── cache/
├── tools/
└── agents/
```

The `service.ts` file picks which functions the rest of the app is allowed to use:

```ts
import { defineService } from "@relkit/app/services";
import createOrder from "./functions/create-order.function.js";
import getOrder from "./functions/get-order.function.js";
import orderCreated from "./events/order-created.event.js";
import exportOrdersTask from "./tasks/export-orders.task.js";
import exportOrders from "./jobs/export-orders.job.js";
export default defineService({
  functions: { createOrder, getOrder }, // callable operations
  events: { orderCreated },             // event contracts other domains can use
  tasks: { exportOrdersTask },          // durable work
  jobs: { exportOrders },               // public job names for that work
});
```

What about caches, buckets, tools and agents? They live inside the domain folder and the compiler finds them on its own, so they don’t need to be listed here. A function just asks for them in its `dependencies` when it needs them.

Anything you leave out stays private to the domain. A helper doesn’t become public just because you exported it in TypeScript. There’s also no registration array to maintain: the compiler discovers the service from source.

To scaffold a new one: `bun run relkit add service`.

## Buckets

Every orders app eventually needs files: invoices, product images, receipts. A **bucket** gives your files a home, with rules built in.

```bash
bun run relkit add bucket invoices
```

Locally, that’s MinIO running in Docker. You don’t install anything by hand, and there are no S3 secrets to copy around. The config line looks like this:

```ts
// relkit.config.ts
bucket: { assets: docker(s3()) },
defaults: { bucket: "assets" },
```

Then you define the bucket with its rules:

```ts
import { defineBucket } from "@relkit/app/buckets";
export default defineBucket({
  id: "orders.invoices",
  profile: "assets",
  visibility: "private",
  maxObjectBytes: 5_000_000,
  allowedContentTypes: ["application/pdf"],
});
```

A function asks for the bucket in its `dependencies`, and then it's simply there on the context:

```ts
const saveInvoice = defineFunction({
  input: z.object({ orderId: z.string(), pdf: z.file({ maxBytes: 5_000_000, mediaTypes: ["application/pdf"] }) }),
  output: z.object({ key: z.string() }),
  dependencies: { buckets: { invoices } },
  handler: async ({ orderId, pdf }, context) => {
    const key = `invoices/${orderId}.pdf`;
    await context.buckets.invoices.put(key, new Uint8Array(await pdf.arrayBuffer()), {
      contentType: "application/pdf",
    });
    return { key };
  },
});
```

Reading files back is just as friendly: `get`, `head`, `exists`, `list`, `delete`, and `createReadUrl(key)` when you want a temporary download link.

## Events

Remember `publishes: ["orders.created"]` in our first function? Here's the other side of it.

An event says “something happened”, and other functions can react to it without the original operation waiting for them. Perfect for “send a confirmation email” or “record analytics” kinds of work.

First, define the event and what it carries:

```ts
import { defineEvent } from "@relkit/app/events";
import { z } from "@relkit/app/schema";
export default defineEvent({
  id: "orders.created",
  input: z.object({ orderId: z.string() }),
});
```

Then subscribe to it from anywhere:

```ts
import { defineEventFunction } from "@relkit/app/events";
export default defineEventFunction({
  id: "orders.confirmation",
  event: "orders.created",
  handler: async (order, context) => {
    context.log.info("order.confirmation.requested", { orderId: order.orderId });
  },
});
```

The fun part: want analytics too? Add a second event function. You don’t touch `createOrder` at all. And the Inspector shows every event with its **publishers** and **consumers**, so you never lose track of who's listening.

CLI shortcuts: `bun run relkit add event` and `bun run relkit add event-function`.

## Caching

Some lookups are expensive, and a slightly old answer is totally fine. Product prices are the classic example.

```bash
bun run relkit add cache prices
```

Define what the key and value look like, and how long values live:

```ts
import { defineCache } from "@relkit/app/cache";
import { z } from "@relkit/app/schema";
export default defineCache({
  id: "orders.prices",
  profile: "requests",
  key: z.object({ sku: z.string() }),
  value: z.number().int().nonnegative(),
  defaultTtlMs: 60_000, // one minute
});
```

Then use the one method you’ll reach for 90% of the time, `getOrSet`:

```ts
const getPrice = defineFunction({
  input: z.object({ sku: z.string().min(1) }),
  output: z.object({ sku: z.string(), unitPriceCents: z.number() }),
  dependencies: { cache: { prices } },
  handler: async ({ sku }, context) => {
    const unitPriceCents = await context.cache.prices.getOrSet({ sku }, async () => {
      // Only runs on a cache miss. Load from your database here.
      return 1_000;
    });
    return { sku, unitPriceCents };
  },
});
```

No Redis client, no key-string gymnastics, no `JSON.parse`. Keys and values are typed and validated. In the Inspector you can open the cache, see each key's remaining TTL, and peek at its value.

## Database

Relkit’s database service is built on Drizzle (MongoDB and Prisma integrations are on the way). One command sets it up:

```bash
bun run relkit add database
```

Pick SQLite, PostgreSQL or MySQL when it asks. Your tables are plain Drizzle:

```ts
// src/services/database/schema/index.ts
export const orders = sqliteTable("orders", {
  orderId: text().primaryKey(),
  sku: text().notNull(),
  quantity: integer().notNull(),
  totalCents: integer().notNull(),
  ownerId: text(),
});
```

And every function gets a typed `context.database`. No connection to open, no dependency to declare:

```ts
handler: async (input, context) => {
  const saved = await context.database.orders.insert({
    data: { ...input, totalCents, ownerId: null },
  });
  const found = await context.database.orders.findOne({
    where: { orderId: saved.orderId },
  });
  // ...
}
```

You get six portable operations (`findOne`, `findMany`, `insert`, `update`, `upsert`, `delete`), generated validation schemas for every table, transactions, and custom model methods for when you need the full power of Drizzle. Migrations stay in your hands: generate with `drizzle-kit`, apply with `bun run relkit db migrate`.

## Auth

Authentication is powered by Better Auth, and it reuses the database you already have:

```bash
bun run relkit add auth
```

That creates the auth service and mounts it at `/api/auth`. Protecting your routes is one option on that mount:

```ts
// the auth route created by the scaffold
export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/orders", "/orders/*"] },
});
```

Inside any function, the current user is one call away:

```ts
const session = await context.auth.getSession();
if (session === null) throw new Error("Authentication required");
await context.database.orders.insert({
  data: { ...input, totalCents, ownerId: session.user.id },
});
```

Notice the caller can’t choose the owner in the request body. Identity comes from the session, and that’s exactly how it should be.

## Generated Typed Client

This is the part frontend developers will love. Setting it up takes three small steps in your frontend project.

**1. Install the client**, plus the CLI as a dev dependency:

```bash
bun add @relkit/client @orpc/tanstack-query @tanstack/react-query @tanstack/query-core @opentelemetry/api
bun add -d @relkit/cli
```

**2. Pull your backend’s contract** while the backend is running:

```bash
bun run relkit client pull http://127.0.0.1:3000 --out .relkit/generated
```

This writes the typed contract into `.relkit/generated`. Add `.relkit/generated/**/*.ts` to your tsconfig `include`, and pull again whenever the API changes.

**3. Wrap your app in the provider:**

```tsx
import { RelkitClientProvider } from "@relkit/client/react";
export default function App() {
  return (
    <RelkitClientProvider>
      <Orders />
    </RelkitClientProvider>
  );
}
```

By default the provider talks to the same origin, which works nicely with a Vite or Next.js dev proxy. If your backend lives on another origin, pass `baseUrl` to the provider. For production builds, add `relkit()` to your Vite config or `withRelkit()` to your Next.js config so the frontend knows exactly which backend version it was built for.

That’s it. Every route, job, agent and channel is now typed, with autocomplete on the route names:

```tsx
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";
export function Orders() {
  const { status } = useRelkitClient();
  const order = useRoute("GET /orders/:orderId", { input: { orderId: "order-1" } });
  const create = useRouteMutation("POST /orders");
  if (order.isPending) return <p>Loading…</p>;
  return (
    <button
      disabled={status !== "ready"}
      onClick={() => create.mutate({ orderId: crypto.randomUUID(), sku: "book", quantity: 1 })}
    >
      Order again
    </button>
  );
}
```

Inputs, outputs and errors all come from your backend’s schemas. Change a field on the backend and TypeScript tells the frontend right away. And `relkit client check` in CI catches any drift before you ship. No more "hey, what does this endpoint return?" messages :)

Not using React? The same typed client works without it: `createClient` from `@relkit/client` runs in any TypeScript app, in the browser or on another server (on Bun, `createServerClient` also forwards tracing). And because every route is plain REST described by OpenAPI, a mobile app or a service written in any language can call your backend too.

## Realtime

Want the order page to update the moment the order ships? That’s a **realtime channel**.

```ts
import { defineChannel } from "@relkit/app/realtime";
import { z } from "@relkit/app/schema";

export default defineChannel({
  id: "orders.status",
  params: z.object({ orderId: z.string() }),
  events: { updated: z.object({ status: z.string() }) },
  client: { public: true },
  replay: { retentionMs: 300_000, maxEvents: 1_000 },
});
```

The backend triggers an update:

```ts
await orderStatus.trigger({ orderId }, "updated", { status: "shipped" });
```

And the browser listens, with fully typed callbacks:

```ts
useChannel("orders.status", {
  params: { orderId },
  on: { updated: () => order.refetch() },
});
```

One little piece of wisdom from the docs that I love: the channel is **not** your database. Load the truth from a route, and use the channel to keep the page fresh. Reconnects and replay gaps then just mean “refetch”, so they stop being scary. (Want “who’s viewing this order”? Channels support presence too.)

## Streaming

Sometimes a response should arrive bit by bit instead of all at once: progress bars, long reports, AI output. Declare the output with `streamOf` and return an async generator:

```ts
import { defineFunction, streamOf } from "@relkit/app/functions";

const streamOrderReport = defineFunction({
  input: z.object({ reportId: z.string().min(1) }),
  output: streamOf(z.object({ completed: z.number().int(), total: z.number().int() })),
  handler: async function* (_input, context) {
    for (let completed = 1; completed <= 10; completed += 1) {
      if (context.signal.aborted) return;
      yield { completed, total: 10 };
    }
  },
});
```

Expose it as Server-Sent Events:

```ts
export const GET = defineRoute({
  target: orders.streamOrderReport,
  request: http.input({ reportId: http.path("reportId") }),
  client: { operation: "query" },
  stream: { format: "sse" },
});
```

And on the frontend, `useStream("GET /reports/:reportId")` gives you `start()`, `cancel()` and typed `items`. Every streamed item is validated against the schema. Even streams don't get to skip the rules.

## Jobs

Some work should outlive the request that started it: exporting orders, sending a batch of invoices, syncing with another system. That’s what jobs are for.

Relkit jobs are task-first. A **task** owns the work, and a **job** gives it a public name. Under the hood you choose the engine: Inngest, Trigger.dev or Effect MQ, all with local Docker recipes.

```bash
bun run relkit add task export-orders
bun run relkit add job export-orders
```

The task, with typed progress:

```ts
import { defineTask } from "@relkit/app/tasks";

export default defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int() }),
  progress: z.object({ completed: z.number().int(), total: z.number().int() }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = toCsv(orderIds); // your business logic
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});
```

The job:

```ts
import { defineJob } from "@relkit/app/jobs";
export default defineJob({
  name: "exportOrders",
  id: "orders.export-orders",
  task: exportOrders,
  client: {
    public: true,
    operations: ["trigger", "get", "list", "watch"],
    fields: ["status", "progress", "output"],
  },
});
```

Retries (three attempts with backoff by default), progress, schedules and cancellation come built in. From the frontend it’s `useJobTrigger("exportOrders")` plus `useJobRun(...)` to watch it live, and from the terminal you get `bun run relkit jobs runs list`, `jobs retry` and `jobs cancel`.

## Agents

Here’s where it gets really fun. An **agent** lets a model decide which steps to take, using your app’s own functions as its tools. Relkit runs agents on native LangChain and LangGraph, so you’re not locked into some custom wrapper.

```bash
bun run relkit add agent support
```

```ts
import { defineAgent } from "@relkit/langchain";
import { z } from "@relkit/app/schema";
import { supportModel } from "@app/platform/model.js"; // any LangChain chat model
import lookupOrder from "@app/services/orders/tools/lookup-order.tool.js";

export default defineAgent({
  id: "orders.support",
  input: z.object({ message: z.string().min(1) }),
  output: z.object({ answer: z.string() }),
  model: supportModel,
  instructions: "Help customers with their orders. Look the order up before answering.",
  tools: [lookupOrder],
  client: { public: true },
  chat: { input: "message", output: "answer" },
  limits: { maxSteps: 4, maxToolCalls: 4, timeoutMs: 10_000 },
});
```

My favorite detail is `limits`. An agent can never run forever or burn through a hundred tool calls by accident. (Bonus: the scaffold starts you with an offline fake model, so you can build and test with no API key at all.)

From React:

```ts
const assistant = useAgent("orders.support");

await assistant.send("Where is my order?", { threadId });
```

Threads are durable, so a refresh or a reconnect picks up right where the conversation left off.

## Tools

So what’s `lookupOrder`? It's just our existing `getOrder` function, wearing a tool costume:

```ts
import getOrder from "@app/services/orders/functions/get-order.function.js";

export default getOrder.asTool({
  id: "orders.lookup-order",
  description: "Look up one of the customer's orders by its ID",
  sideEffect: "read",
  approval: "never",
  timeoutMs: 2_000,
});
```

No duplicated schemas and no separate “AI layer”. The tool has the same input, the same output, the same validation and the same auth checks as the function. You only add what the AI needs to know: a description, a side-effect class (`read`, `write`, `external`) and an approval policy for the risky ones.

## Graphs

When you already know the steps, and you want branches, loops or a human in the loop, a free-thinking agent isn’t the right fit. Reach for a **graph** instead. It’s native LangGraph, with Relkit validating the state at each node.

```ts
// trimmed from the docs' order-review example
const orderReview = defineGraph({
  state,
  input: z.object({ orderId: z.string() }),
  output: z.object({ result: z.string() }),
  nodes: [inventory, risk, review, finish],
  edges: (edge) =>
    edge
      .addEdge(START, "load-inventory")
      .addEdge(START, "assess-risk")
      .addEdge(["load-inventory", "assess-risk"], "review")
      .addEdge("finish", END),
  limits: { maxSteps: 10, maxToolCalls: 1, timeoutMs: 20_000 },
  client: { public: true },
});
```

Inventory and risk checks run in parallel, then `review` pauses and waits for a human to approve. The frontend answers on the same thread:

```ts
await review.run(true, { threadId, resume: true }); // approved!
```

Each node is defined with `defineGraphNode` and has its own input and output schemas. And edges only accept node IDs that actually exist, so a typo in a node name fails at compile time, not in production.

## MCP

Want Claude, Cursor or any other MCP client to use your app’s tools? You don’t need to write an MCP server. Relkit already has one; you just switch it on:

```bash
bun add @modelcontextprotocol/server
```

```ts
// relkit.config.ts
server: { port: 3000, mcp: true },
```

That’s it. Your tools are now served at `http://localhost:3000/mcp` (Streamable HTTP). The `lookupOrder` tool we wrote for the agent is the exact same one the MCP client sees.

Want to keep a tool internal? Add `mcp: false` to it. And before you put this on the internet, protect `/mcp` like any other endpoint. Hiding a tool from an agent isn't access control.

## Observability

Here’s the “done under the hood” promise in action. Relkit automatically creates spans for routes, functions, jobs, events, tools and agents, all correlated together. You just log:

```ts
context.log.info("order.created", { orderId });
```

When you want more detail on a specific piece of work, wrap it in a span:

```ts
const price = await context.trace.span("pricing.calculate", () =>
  context.cache.prices.getOrSet({ sku }, loadPrice),
);
```

Local logs and traces need no account, no exporter and no extra setup. When you’re ready for production, plug in exporters. Sentry and OTLP are both supported, and they run independently, so if one goes down it never blocks your app or the other:

```ts
telemetry: {
  redaction: { mode: "development-redacted", maxBytes: 65_536 },
  exportSampling: { traceRate: 0.25, minimumLogLevel: "info" },
  exporters: {
    errors: sentry({
      dsn: binding.secret("SENTRY_DSN"),
      environment: binding.string("SENTRY_ENVIRONMENT"),
    }),
    traces: otlp({
      endpoint: binding.url("OTLP_ENDPOINT"),
      serviceName: "orders-api",
    }),
  },
},
```

Secrets and request bodies are redacted **before** anything is stored or exported. And then, back to where we started: open the Inspector, click a request, and follow it from the route through every function, cache hit and event it touched.

## Deployment

So you’ve built the orders app. Time to ship it! The best part: the app you ran locally is exactly the app you deploy. Nothing gets rewritten for production.

**1. Check and build.** One sequence, and none of it touches the cloud:

```bash
bun run check
bun run typecheck
bun run test
bun run build
```

The build lands in `.relkit/build`: the bundled server, its graph and manifests, and a ready-made Dockerfile.

**2. Run it anywhere that runs Docker.**

```bash
docker build -t orders-api .relkit/build
docker run -p 3000:3000 -e PORT=3000 orders-api
```

That image runs on Railway, Fly.io, Kubernetes or a plain VM. Secrets come from the host’s environment at runtime, and nothing from your `.env` is baked into the build. (Prefer no container? Install the build’s production manifest and start `.relkit/build/server/index.js` with Bun.)

**3. Swap local providers for real ones.** Remember `docker(redis())` and `docker(s3())`? Docker is a development-only choice. For production, you give the same adapters real connection values:

```ts
// relkit.config.ts
// docker() is only used by bun run dev;
// in production these bindings come from the env
cache: {
  requests: docker(redis({ url: binding.secret("REQUESTS_REDIS_URL") })),
},
bucket: {
  assets: docker(s3({
    endpoint: binding.url("ASSETS_S3_ENDPOINT"),
    bucketName: binding.string("ASSETS_S3_BUCKET"),
    region: binding.string("ASSETS_S3_REGION"),
    credentials: {
      accessKeyId: binding.secret("ASSETS_S3_ACCESS_KEY_ID"),
      secretAccessKey: binding.secret("ASSETS_S3_SECRET_ACCESS_KEY"),
    },
  })),
},
```

Locally, Docker still fills in those values for you. In production, they come from the environment. Profile names and descriptor IDs stay the same, so not a single function changes. Your database works the same way: point it at your production Postgres and run `bun run relkit db migrate` once before rollout.

**4. Want AWS? Let Pulumi do the heavy lifting.** Install `@relkit/aws` and `@relkit/pulumi` as dev dependencies, then pick a host and an engine:

```ts
// relkit.config.ts
deployment: { engine: "pulumi", host: "aws" },
```

```bash
bun run relkit deploy init --stack production
bun run relkit deploy preview --stack production
bun run relkit deploy up --stack production
```

Full setup for the engine and host (roles, stacks and state backends): [Deploy to AWS with Pulumi](/docs/modules/deployment/aws).

Relkit generates the Pulumi program straight from your application graph: ECS/Fargate, networking, a load balancer and CloudWatch logs. Preview always comes first, so you see every create, update and delete before anything gets billed. AWS is the first built-in cloud host, and the Docker image covers everywhere else.

Want AWS to own the resources too, not just host the app? Wrap them in `aws(...)`, like `aws(s3(...))` or `aws(redis(...))`, and the stack creates and manages them for you. Leave them unwrapped and Relkit simply connects to resources you already run elsewhere. More in [Configure production providers](/docs/modules/deployment/providers).

## Big thanks

Relkit stands on the shoulders of giants. A huge thank you to the people behind the core projects that make it possible:

- **Effect**, the backbone of the runtime, schemas and CLI
- **Bun**, for making TypeScript tooling fast and fun
- **Hono**, powering the HTTP layer
- **oRPC**, behind the typed client and RPC
- **TanStack Query**, for the React hooks
- **Drizzle ORM** and **Drizzle Kit**, for the database and migrations
- **Better Auth**, for authentication
- **LangChain**, **LangGraph** and **DeepAgents**, for agents and graphs
- **Model Context Protocol**, for opening our tools to every AI client
- **Inngest**, **Trigger.dev** and **Effect MQ**, for durable jobs
- **Scalar**, for the gorgeous API reference
- **OpenTelemetry** and **Sentry**, for observability
- **Redis**, **MinIO** and **Docker**, for a local setup that just works
- **Pulumi**, for deployments

Open source is magic, and none of this would exist without you.

Finally, this framework is still under development, but the foundation is in place, and all the upcoming work will go into enhancements and making it stable enough for production apps.

If you want to try it, the docs are at [relkit.dev/docs](/docs). Start with the “Learn” tutorial, which builds exactly the orders app we walked through here.

---

# One migration history, run by RELKIT
Source: https://relkit.dev/blog/one-migration-history

A migration applies a reviewed schema change to a database. RELKIT has always generated those migrations from your TypeScript tables with Drizzle Kit. What changed is where the history lives and who runs it.

## Migrations beside their service

Generated SQL and its metadata now stay in `src/services/database/migrations`, next to the service and schema that own them. Auth tables and business tables share that one ordered history. The `.relkit/` folder only holds ignored runtime and build output, never migration source.

## One command to apply them

Shared migration execution moved into installed RELKIT tooling:

```sh title="Terminal"
bun --bun drizzle-kit generate --name=initial
bun run db:migrate
```

`db:migrate` runs `relkit db migrate`. SQLite uses the Bun-native driver with no copied runner, while PostgreSQL and MySQL delegate to the Drizzle Kit your application already installs.

`check`, `build`, and `dev` still never apply migrations for you. Migrate first, then start code that depends on the new shape.

**[Migrations](/docs/modules/database/migrations)**

Configure Drizzle Kit, then generate, review, and apply.

**[Define a database](/docs/modules/database/define)**

Add a database service to an application.

---

# The Inspector is now a standalone tool
Source: https://relkit.dev/blog/standalone-inspector

The Inspector lets you browse a running application's routes, resources, traces, and request history. Until now it shipped alongside the rest of the toolkit. Starting with this release it lives in its own package, `@relkit/inspector`, and every backend installation leaves it out unless you ask for it.

## Why we split it out

Most of the time a backend only needs its runtime. The Inspector carries a UI and a diagnostic history worker, and those pulled Node.js and a web toolchain into installs that never opened them. Moving it out keeps the default installation lean: the backend-only development workflow needs no Node.js at all.

## Adding it to a project

One command enables the application bridge and installs the tool as a project dev dependency:

```sh title="Terminal"
bun run relkit add inspector --project-root .
```

It sets `inspector: { enabled: true }` in `relkit.config.ts`, adds `@relkit/inspector` to `devDependencies`, and adds an `inspector` script that runs `relkit inspector`. Nothing is installed globally, and an `inspector.enabled: false` you wrote yourself is reported as a conflict instead of being overwritten.

The bridge listens on `127.0.0.1` with an ephemeral port by default, separate from the Inspector UI, which defaults to port 3210.

## What stays the same

`relkit jobs` still reads and controls live provider state on the backend, with or without the Inspector. Logs, request history, and traces belong to the Inspector, and since this release dev reloads pick up Inspector config changes without a restart.

**[Inspector](/docs/modules/operations/inspector)**

Set up the bridge and follow a request end to end.

**[Observability](/docs/modules/operations/observability)**

Logs, traces, and diagnostics for running apps.

---

# RELKIT documentation
Source: https://relkit.dev/docs

<div className="docs-home">

<DocsHero>

<p className="docs-hero-eyebrow">RELKIT documentation</p>

# Build your first TypeScript API.

<span id="why-relkit-exists"></span>

Build TypeScript backends with RELKIT. Start with a working HTTP endpoint, then add data, sign-in, and tests as you need them.

<span id="the-recommended-sequence"></span>

<div className="docs-hero-actions">
  <a href="/docs/learn/create-an-app">Start building</a>
  <a href="/docs/modules">Explore modules</a>
</div>

</DocsHero>

Create an application and send your first request. Continue with the same Orders application through persistence, authentication, testing, and production builds.

## Find what you need

<span id="choose-a-path"></span>
<span id="what-you-can-build"></span>

**[Learn](/docs/learn)**

Follow a continuous tutorial. New terms appear alongside the code that uses them.

**[Modules](/docs/modules)**

Understand a capability, configure its providers, and learn its limits.

**[Guides](/guides)**

Complete a specific task, such as uploading product images or caching prices.

**[Reference](/docs/api)**

Look up exact API signatures, types, options, and CLI commands.

You'll need basic TypeScript and Bun 1.3.10 or later for the first tutorial. Each later chapter names any additional requirements.

<div className="docs-home-details">

## Already have an application?

Choose a [module](/docs/modules) to configure, or a [guide](/guides) for the task you want to complete. For example, [Buckets](/docs/modules/storage) explains storage configuration, while [Upload product images](/guides/storage/upload-product-images) builds an HTTP upload endpoint.

The [Inspector](/docs/modules/operations/inspector) is an optional, separately installed tool. You can complete the tutorial and verify responses from your terminal.

For terminal workflows, start with the [CLI module](/docs/modules/cli). It connects project creation, scaffolding, development, and production builds to the [command reference](/docs/api/cli).

## Documentation and source [#documentation-and-source-of-truth]

Examples come from maintained repository sources. API reference comes from TypeScript, and CLI reference comes from the command's help model.

If a step doesn't work, [report the command and its diagnostic](https://github.com/rel-kit/relkit/issues), together with your package versions and a small reproduction.

</div>
</div>

---

# Reference
Source: https://relkit.dev/docs/api

Use this section when you know which API or command you need. Package pages contain signatures, types, source links, and checked examples. The CLI page comes from the same command model as terminal help.

## Application configuration

- [defineApp](/docs/api/app#defineapp) connects your environment, server settings, and providers in `relkit.config.ts`. This is RELKIT's current application configuration API; `defineConfig` is no longer exported.
- [defineEnv](/docs/api/config#defineenv) declares typed environment values. Use the [env builders](/docs/api/config#env) to select their types, defaults, and secret handling.

For a walkthrough, read [Application configuration](/docs/learn/concepts/application) and [Environment contracts](/docs/learn/concepts/environment).

## API reference

Browse [all public APIs and import paths](/docs/api/public), including React hooks, testing helpers,
provider authoring, integration runtimes, and CLI automation. Each package has an **All exported APIs**
table linking values, types, and aliases to their complete contracts.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

### Core packages

| Reference                                      | Package                       | Common APIs                                                                                                                                                                      |
| ---------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Application](/docs/api/app)                   | `@relkit/app`                 | [defineApp](/docs/api/app#defineapp)                                                                                                                                             |
| [Configuration](/docs/api/config)              | `@relkit/config`              | [defineEnv](/docs/api/config#defineenv)                                                                                                                                          |
| [Provider authoring](/docs/api/provider)       | `@relkit/provider`            | See package reference                                                                                                                                                            |
| [Local providers](/docs/api/providers-local)   | `@relkit/providers-local`     | See package reference                                                                                                                                                            |
| [Local history](/docs/api/observability-local) | `@relkit/observability-local` | See package reference                                                                                                                                                            |
| [CLI automation](/docs/api/cli-api)            | `@relkit/cli`                 | See package reference                                                                                                                                                            |
| [Project generator](/docs/api/create-relkit)   | `create-relkit`               | See package reference                                                                                                                                                            |
| [CLI launcher](/docs/api/relkit)               | `relkit`                      | See package reference                                                                                                                                                            |
| [Schema](/docs/api/schema)                     | `@relkit/schema`              | [z](/docs/api/schema#z), [validate](/docs/api/schema#validate)                                                                                                                   |
| [Functions](/docs/api/functions)               | `@relkit/functions`           | [defineFunction](/docs/api/functions#definefunction), [defineError](/docs/api/functions#defineerror)                                                                             |
| [Services](/docs/api/services)                 | `@relkit/services`            | [defineService](/docs/api/services#defineservice)                                                                                                                                |
| [Drizzle](/docs/api/drizzle)                   | `@relkit/drizzle`             | [defineDrizzleService](/docs/api/drizzle#definedrizzleservice), [defineModel](/docs/api/drizzle#definemodel), [activateDrizzleService](/docs/api/drizzle#activatedrizzleservice) |
| [Better Auth](/docs/api/better-auth)           | `@relkit/better-auth`         | [defineBetterAuthService](/docs/api/better-auth#definebetterauthservice)                                                                                                         |
| [Routes](/docs/api/routes)                     | `@relkit/routes`              | [defineRoute](/docs/api/routes#defineroute), [defineMiddleware](/docs/api/routes#definemiddleware)                                                                               |
| [Events](/docs/api/events)                     | `@relkit/events`              | [defineEvent](/docs/api/events#defineevent), [defineEventFunction](/docs/api/events#defineeventfunction)                                                                         |
| [Jobs](/docs/api/jobs)                         | `@relkit/jobs`                | [defineTask](/docs/api/jobs#definetask), [defineJob](/docs/api/jobs#definejob)                                                                                                   |
| [Buckets](/docs/api/buckets)                   | `@relkit/buckets`             | [defineBucket](/docs/api/buckets#definebucket)                                                                                                                                   |
| [Cache](/docs/api/cache)                       | `@relkit/cache`               | [defineCache](/docs/api/cache#definecache)                                                                                                                                       |
| [Tools](/docs/api/tools)                       | `@relkit/tools`               | [defineTool](/docs/api/tools#definetool)                                                                                                                                         |
| [Agents](/docs/api/agents)                     | `@relkit/agents`              | [approveApproval](/docs/api/agents#approveapproval), [denyApproval](/docs/api/agents#denyapproval), [defineAgent](/docs/api/agents#defineagent)                                  |
| [Client](/docs/api/client)                     | `@relkit/client`              | [createClient](/docs/api/client#createclient)                                                                                                                                    |
| [Realtime](/docs/api/realtime)                 | `@relkit/realtime`            | [defineChannel](/docs/api/realtime#definechannel)                                                                                                                                |
| [Testing](/docs/api/testing)                   | `@relkit/testing`             | [invokeFunction](/docs/api/testing#invokefunction), [createTestApplication](/docs/api/testing#createtestapplication)                                                             |
| [Standalone Inspector](/docs/api/inspector)    | `@relkit/inspector`           | See package reference                                                                                                                                                            |

### Integrations

| Reference                                             | Package                | Common APIs                                                                                              |
| ----------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| [LangChain](/docs/api/integrations/langchain)         | `@relkit/langchain`    | See package reference                                                                                    |
| [AWS](/docs/api/integrations/aws)                     | `@relkit/aws`          | [aws](/docs/api/integrations/aws#aws)                                                                    |
| [Integration catalog](/docs/api/integrations/catalog) | `@relkit/integrations` | See package reference                                                                                    |
| [Cloudflare](/docs/api/integrations/cloudflare)       | `@relkit/cloudflare`   | See package reference                                                                                    |
| [Docker](/docs/api/integrations/docker)               | `@relkit/docker`       | [docker](/docs/api/integrations/docker#docker)                                                           |
| [Local](/docs/api/integrations/local)                 | `@relkit/local`        | [localEvent](/docs/api/integrations/local#localevent), [localJob](/docs/api/integrations/local#localjob) |
| [OTLP](/docs/api/integrations/otlp)                   | `@relkit/otlp`         | See package reference                                                                                    |
| [Pulumi](/docs/api/integrations/pulumi)               | `@relkit/pulumi`       | See package reference                                                                                    |
| [Redis](/docs/api/integrations/redis)                 | `@relkit/redis`        | See package reference                                                                                    |
| [S3](/docs/api/integrations/s3)                       | `@relkit/s3`           | See package reference                                                                                    |
| [Sentry](/docs/api/integrations/sentry)               | `@relkit/sentry`       | See package reference                                                                                    |
| [Inngest](/docs/api/integrations/inngest)             | `@relkit/inngest`      | See package reference                                                                                    |
| [Trigger.dev](/docs/api/integrations/trigger)         | `@relkit/trigger`      | See package reference                                                                                    |
| [Effect MQ](/docs/api/integrations/effect-mq)         | `@relkit/effect-mq`    | See package reference                                                                                    |

## CLI reference

Look up commands, arguments, options, and examples in the [CLI reference](/docs/api/cli).

New to the commands? Start with the [CLI module](/docs/modules/cli) and its [create-to-build walkthrough](/guides/cli/create-and-build-an-api).

For configuration and explanations, choose a [module](/docs/modules). For a complete workflow, choose a [guide](/guides).

---

# Agents API
Source: https://relkit.dev/docs/api/agents

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [approveApproval](/docs/api/agents#approveapproval)
- [denyApproval](/docs/api/agents#denyapproval)
- [defineAgent](/docs/api/agents#defineagent)

For configuration and examples, read [approvals](/docs/modules/ai/approvals), [agents](/docs/modules/ai/agents), [organization](/docs/modules/service/organization).

For a complete workflow, follow [build an offline agent](/guides/ai/build-an-offline-agent).

## Frontend usage

[Observe an agent and send controls](/docs/modules/ai/streaming#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/agents` — 182 exports
- `@relkit/agents/client-events` — 5 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                             | Kind  | Import from                                      | Example                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| [AcceptControlRequest](/docs/api/app#acceptcontrolrequest-interface)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AcceptRunReceipt](/docs/api/app#acceptrunreceipt-interface)                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AcceptRunRequest](/docs/api/app#acceptrunrequest-interface)                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AdmitContinuationRequest](/docs/api/app#admitcontinuationrequest-type-alias)                   | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AGENT_OBSERVABILITY_PROTOCOL](/docs/api/agents#agent_observability_protocol)                   | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AGENT_OBSERVABILITY_VERSION](/docs/api/agents#agent_observability_version)                     | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentApprovalHandler](/docs/api/agents#agentapprovalhandler-type-alias)                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentCapturePolicy](/docs/api/agents#agentcapturepolicy-interface)                             | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentcapturepolicy-interface)                                                                      |
| [AgentCapturePolicyError](/docs/api/agents#agentcapturepolicyerror-class)                       | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentCaptureRecord](/docs/api/agents#agentcapturerecord-interface)                             | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentcapturerecord-interface)                                                                      |
| [AgentChatMapping](/docs/api/agents#agentchatmapping-interface)                                 | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentchatmapping-interface)                                                                        |
| [AgentClientEvent](/docs/api/app#agentclientevent-type-alias)                                   | Type  | `@relkit/agents`, `@relkit/agents/client-events` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L174)  |
| [agentClientEvents](/docs/api/agents#agentclientevents-1)                                       | Value | `@relkit/agents`, `@relkit/agents/client-events` | [API example](/docs/api/agents#agentclientevents-1)                                                                               |
| [AgentClientEvents](/docs/api/agents#agentclientevents-type-alias)                              | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentclientevents-type-alias)                                                                      |
| [agentClientEventsEffect](/docs/api/agents#agentclienteventseffect)                             | Value | `@relkit/agents`, `@relkit/agents/client-events` | [API example](/docs/api/agents#agentclienteventseffect)                                                                           |
| [AgentClientPolicy](/docs/api/agents#agentclientpolicy-type-alias)                              | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentclientpolicy-type-alias)                                                                      |
| [AgentClientPolicyError](/docs/api/agents#agentclientpolicyerror-class)                         | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentContentSink](/docs/api/agents#agentcontentsink-interface)                                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentControl](/docs/api/agents#agentcontrol-type-alias)                                        | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentcontrol-type-alias)                                                                           |
| [AgentConversationMessage](/docs/api/agents#agentconversationmessage-interface)                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentDescriptor](/docs/api/agents#agentdescriptor-interface)                                   | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentEdgeRelationship](/docs/api/agents#agentedgerelationship-type-alias)                      | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentedgerelationship-type-alias)                                                                  |
| [AgentExecutionEvent](/docs/api/app#agentexecutionevent-interface)                              | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L236)  |
| [AgentExecutionSnapshot](/docs/api/app#agentexecutionsnapshot-interface)                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentInstructions](/docs/api/agents#agentinstructions-type-alias)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentLimits](/docs/api/agents#agentlimits-interface)                                           | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentObservabilitySink](/docs/api/agents#agentobservabilitysink-interface)                     | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentobservabilitysink-interface)                                                                  |
| [AgentObservation](/docs/api/app#agentobservation-type-alias)                                   | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observer.test.ts#L97)      |
| [AgentObservedEdge](/docs/api/agents#agentobservededge-interface)                               | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentobservededge-interface)                                                                       |
| [AgentOperation](/docs/api/agents#agentoperation-type-alias)                                    | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentoperation-type-alias)                                                                         |
| [AgentProgressEvent](/docs/api/app#agentprogressevent-type-alias)                               | Type  | `@relkit/agents`, `@relkit/agents/client-events` | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentProgressScope](/docs/api/app#agentprogressscope-type-alias)                               | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentRequestScope](/docs/api/app#agentrequestscope-interface)                                  | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L57)   |
| [AgentRuntimeHooks](/docs/api/agents#agentruntimehooks-interface)                               | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentruntimehooks-interface)                                                                       |
| [AgentSpanCapture](/docs/api/agents#agentspancapture-interface)                                 | Type  | `@relkit/agents`                                 | [API example](/docs/api/agents#agentspancapture-interface)                                                                        |
| [AgentStateLimits](/docs/api/app#agentstatelimits-interface)                                    | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L21)   |
| [AgentStateProvider](/docs/api/app#agentstateprovider-interface)                                | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L57)           |
| [AgentSteeringSource](/docs/api/agents#agentsteeringsource-interface)                           | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentTelemetry](/docs/api/agents#agenttelemetry-class)                                         | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#agenttelemetry-class)                                                                              |
| [AgentTelemetryLive](/docs/api/agents#agenttelemetrylive)                                       | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#agenttelemetrylive)                                                                                |
| [AgentTelemetryService](/docs/api/agents#agenttelemetryservice-interface)                       | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentToolEvent](/docs/api/app#agenttoolevent-type-alias)                                       | Type  | `@relkit/agents`, `@relkit/agents/client-events` | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentToolReferences](/docs/api/agents#agenttoolreferences-type-alias)                          | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentTransitionError](/docs/api/app#agenttransitionerror-type-alias)                           | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentWaitingRequest](/docs/api/app#agentwaitingrequest-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AgentWaitingState](/docs/api/app#agentwaitingstate-interface)                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [AppendJournalRequest](/docs/api/app#appendjournalrequest-interface)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [APPROVAL_STATES](/docs/api/agents#approval_states)                                             | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalDeniedError](/docs/api/agents#approvaldeniederror-class)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#approvaldeniederror-class)                                                                         |
| [ApprovalEffectError](/docs/api/agents#approvaleffecterror-class)                               | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalMetadata](/docs/api/agents#approvalmetadata-interface)                                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalOptions](/docs/api/agents#approvaloptions-interface)                                   | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalPolicy](/docs/api/agents#approvalpolicy-type-alias)                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalRecord](/docs/api/agents#approvalrecord-type-alias)                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalRequiredError](/docs/api/agents#approvalrequirederror-class)                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#approvalrequirederror-class)                                                                       |
| [ApprovalSideEffect](/docs/api/agents#approvalsideeffect-type-alias)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalState](/docs/api/agents#approvalstate-type-alias)                                      | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ApprovalStateError](/docs/api/agents#approvalstateerror-class)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#approvalstateerror-class)                                                                          |
| [approveApproval](/docs/api/agents#approveapproval)                                             | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#approveapproval)                                                                                   |
| [approveApprovalEffect](/docs/api/agents#approveapprovaleffect)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#approveapprovaleffect)                                                                             |
| [ApprovedApproval](/docs/api/agents#approvedapproval-interface)                                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [assertAgentDescriptor](/docs/api/agents#assertagentdescriptor)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#assertagentdescriptor)                                                                             |
| [assertApprovalGranted](/docs/api/agents#assertapprovalgranted)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#assertapprovalgranted)                                                                             |
| [assertApprovalGrantedEffect](/docs/api/agents#assertapprovalgrantedeffect)                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#assertapprovalgrantedeffect)                                                                       |
| [BrowserMessage](/docs/api/app#browsermessage-interface)                                        | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L23)   |
| [BrowserMessagePart](/docs/api/app#browsermessagepart-type-alias)                               | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [captureAgentContent](/docs/api/agents#captureagentcontent)                                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#captureagentcontent)                                                                               |
| [captureAgentContentEffect](/docs/api/agents#captureagentcontenteffect)                         | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#captureagentcontenteffect)                                                                         |
| [ClaimControlRequest](/docs/api/app#claimcontrolrequest-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ClaimRunRequest](/docs/api/app#claimrunrequest-interface)                                      | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [clientPolicyCount](/docs/api/agents#clientpolicycount)                                         | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [clientPolicyFailures](/docs/api/agents#clientpolicyfailures)                                   | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [CompleteRunRequest](/docs/api/app#completerunrequest-interface)                                | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [CompletionReceipt](/docs/api/app#completionreceipt-interface)                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ContinuationIdentity](/docs/api/app#continuationidentity-interface)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ContinuationReceipt](/docs/api/app#continuationreceipt-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ContinuationReceiptLookup](/docs/api/app#continuationreceiptlookup-type-alias)                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlClaim](/docs/api/app#controlclaim-interface)                                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlEffectOutcome](/docs/api/app#controleffectoutcome-type-alias)                           | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlLimits](/docs/api/app#controllimits-interface)                                          | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlPage](/docs/api/app#controlpage-interface)                                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlReceipt](/docs/api/app#controlreceipt-interface)                                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlReceiptLookup](/docs/api/app#controlreceiptlookup-type-alias)                           | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlRecord](/docs/api/app#controlrecord-interface)                                          | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ControlStatus](/docs/api/app#controlstatus-type-alias)                                         | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [copyAgentChat](/docs/api/agents#copyagentchat)                                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentchat)                                                                                     |
| [copyAgentChatEffect](/docs/api/agents#copyagentchateffect)                                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentchateffect)                                                                               |
| [copyAgentClientPolicy](/docs/api/agents#copyagentclientpolicy)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentclientpolicy)                                                                             |
| [copyAgentClientPolicyEffect](/docs/api/agents#copyagentclientpolicyeffect)                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentclientpolicyeffect)                                                                       |
| [copyAgentControls](/docs/api/agents#copyagentcontrols)                                         | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentcontrols)                                                                                 |
| [copyAgentControlsEffect](/docs/api/agents#copyagentcontrolseffect)                             | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentcontrolseffect)                                                                           |
| [copyAgentLimits](/docs/api/agents#copyagentlimits)                                             | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentlimits)                                                                                   |
| [copyAgentLimitsEffect](/docs/api/agents#copyagentlimitseffect)                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#copyagentlimitseffect)                                                                             |
| [createAgentCapturePolicy](/docs/api/agents#createagentcapturepolicy)                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createagentcapturepolicy)                                                                          |
| [createAgentCapturePolicyEffect](/docs/api/agents#createagentcapturepolicyeffect)               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createagentcapturepolicyeffect)                                                                    |
| [createAgentSpanCapture](/docs/api/agents#createagentspancapture)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createagentspancapture)                                                                            |
| [createAgentSpanCaptureEffect](/docs/api/agents#createagentspancaptureeffect)                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createagentspancaptureeffect)                                                                      |
| [createApproval](/docs/api/agents#createapproval)                                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createapproval)                                                                                    |
| [createApprovalEffect](/docs/api/agents#createapprovaleffect)                                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#createapprovaleffect)                                                                              |
| [createGeneratedAgentFunction](/docs/api/agents#creategeneratedagentfunction)                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#creategeneratedagentfunction)                                                                      |
| [createGeneratedAgentFunctionEffect](/docs/api/agents#creategeneratedagentfunctioneffect)       | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#creategeneratedagentfunctioneffect)                                                                |
| [CreateThreadReceipt](/docs/api/app#createthreadreceipt-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [CreateThreadRequest](/docs/api/app#createthreadrequest-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [decideThreadTransition](/docs/api/agents#decidethreadtransition)                               | Value | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L20) |
| [decideThreadTransitionEffect](/docs/api/agents#decidethreadtransitioneffect)                   | Value | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L45) |
| [defineAgent](/docs/api/agents#defineagent)                                                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#defineagent)                                                                                       |
| [defineAgentEffect](/docs/api/agents#defineagenteffect)                                         | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [DefineAgentOptions](/docs/api/agents#defineagentoptions-interface)                             | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [DeniedApproval](/docs/api/agents#deniedapproval-interface)                                     | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [denyApproval](/docs/api/agents#denyapproval)                                                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#denyapproval)                                                                                      |
| [denyApprovalEffect](/docs/api/agents#denyapprovaleffect)                                       | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#denyapprovaleffect)                                                                                |
| [emitAgentEdge](/docs/api/agents#emitagentedge)                                                 | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#emitagentedge)                                                                                     |
| [emitAgentEdgeEffect](/docs/api/agents#emitagentedgeeffect)                                     | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#emitagentedgeeffect)                                                                               |
| [ExecutionClaim](/docs/api/app#executionclaim-interface)                                        | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L61)           |
| [GENERATED_AGENT_FUNCTION_PREFIX](/docs/api/agents#generated_agent_function_prefix)             | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [GENERATED_AGENT_FUNCTION_SUFFIX](/docs/api/agents#generated_agent_function_suffix)             | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [GeneratedAgentExecutor](/docs/api/agents#generatedagentexecutor-type-alias)                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [GeneratedAgentFunction](/docs/api/agents#generatedagentfunction-type-alias)                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [generatedAgentFunctionId](/docs/api/agents#generatedagentfunctionid)                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#generatedagentfunctionid)                                                                          |
| [generatedAgentFunctionIdEffect](/docs/api/agents#generatedagentfunctionideffect)               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#generatedagentfunctionideffect)                                                                    |
| [GeneratedAgentFunctionMarker](/docs/api/agents#generatedagentfunctionmarker-interface)         | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [GeneratedAgentFunctionUnboundError](/docs/api/agents#generatedagentfunctionunbounderror-class) | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [InterruptionReceipt](/docs/api/app#interruptionreceipt-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [InterruptOwnedRunRequest](/docs/api/app#interruptownedrunrequest-interface)                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [isAgentDescriptor](/docs/api/agents#isagentdescriptor)                                         | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#isagentdescriptor)                                                                                 |
| [isApprovalRecord](/docs/api/agents#isapprovalrecord)                                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#isapprovalrecord)                                                                                  |
| [isApprovalRecordEffect](/docs/api/agents#isapprovalrecordeffect)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#isapprovalrecordeffect)                                                                            |
| [isGeneratedAgentFunction](/docs/api/agents#isgeneratedagentfunction)                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#isgeneratedagentfunction)                                                                          |
| [isGeneratedAgentFunctionEffect](/docs/api/agents#isgeneratedagentfunctioneffect)               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#isgeneratedagentfunctioneffect)                                                                    |
| [JournalCheckpoint](/docs/api/app#journalcheckpoint-interface)                                  | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L13)   |
| [JournalPage](/docs/api/app#journalpage-interface)                                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [JournalReceipt](/docs/api/app#journalreceipt-interface)                                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [JournalRecord](/docs/api/app#journalrecord-interface)                                          | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L100)                    |
| [ListThreadsRequest](/docs/api/app#listthreadsrequest-interface)                                | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [LoadThreadRequest](/docs/api/app#loadthreadrequest-interface)                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [LookupContinuationReceiptRequest](/docs/api/app#lookupcontinuationreceiptrequest-interface)    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [LookupControlReceiptRequest](/docs/api/app#lookupcontrolreceiptrequest-interface)              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [LookupRunReceiptRequest](/docs/api/app#lookuprunreceiptrequest-interface)                      | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [MarkControlEffectStartedRequest](/docs/api/app#markcontroleffectstartedrequest-interface)      | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ModelProviderConfiguration](/docs/api/agents#modelproviderconfiguration-interface)             | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ModelSelectionEffectError](/docs/api/agents#modelselectioneffecterror-class)                   | Value | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ModelSelectionError](/docs/api/agents#modelselectionerror-class)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#modelselectionerror-class)                                                                         |
| [ModelSelectionErrorCode](/docs/api/agents#modelselectionerrorcode-type-alias)                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [normalizeModelSelector](/docs/api/agents#normalizemodelselector)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#normalizemodelselector)                                                                            |
| [normalizeModelSelectorEffect](/docs/api/agents#normalizemodelselectoreffect)                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#normalizemodelselectoreffect)                                                                      |
| [observeAgent](/docs/api/agents#observeagent)                                                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#observeagent)                                                                                      |
| [parseModelProviderConfiguration](/docs/api/agents#parsemodelproviderconfiguration)             | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#parsemodelproviderconfiguration)                                                                   |
| [parseModelProviderConfigurationEffect](/docs/api/agents#parsemodelproviderconfigurationeffect) | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#parsemodelproviderconfigurationeffect)                                                             |
| [PendingApproval](/docs/api/agents#pendingapproval-interface)                                   | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/agent-approval.fixture.ts#L40)           |
| [PromptInstructions](/docs/api/agents#promptinstructions-interface)                             | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [PromptTemplate](/docs/api/agents#prompttemplate-interface)                                     | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ReadControlsRequest](/docs/api/app#readcontrolsrequest-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ReadJournalRequest](/docs/api/app#readjournalrequest-interface)                                | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ReadSnapshotHistoryRequest](/docs/api/app#readsnapshothistoryrequest-interface)                | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [RecoverAbandonedControlRequest](/docs/api/app#recoverabandonedcontrolrequest-interface)        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [RenewControlClaimRequest](/docs/api/app#renewcontrolclaimrequest-interface)                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [RenewRunClaimRequest](/docs/api/app#renewrunclaimrequest-interface)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [requiresApproval](/docs/api/agents#requiresapproval)                                           | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#requiresapproval)                                                                                  |
| [requiresApprovalEffect](/docs/api/agents#requiresapprovaleffect)                               | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#requiresapprovaleffect)                                                                            |
| [ResolvedModelSelection](/docs/api/agents#resolvedmodelselection-interface)                     | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [resolveModelSelector](/docs/api/agents#resolvemodelselector)                                   | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#resolvemodelselector)                                                                              |
| [resolveModelSelectorEffect](/docs/api/agents#resolvemodelselectoreffect)                       | Value | `@relkit/agents`                                 | [API example](/docs/api/agents#resolvemodelselectoreffect)                                                                        |
| [RunOwner](/docs/api/app#runowner-interface)                                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [RunReceiptLookup](/docs/api/app#runreceiptlookup-type-alias)                                   | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [RunStatus](/docs/api/app#runstatus-type-alias)                                                 | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [SettleControlRequest](/docs/api/app#settlecontrolrequest-interface)                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [SnapshotHistoryPage](/docs/api/app#snapshothistorypage-interface)                              | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [StoredApproval](/docs/api/app#storedapproval-interface)                                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [StoredRun](/docs/api/app#storedrun-interface)                                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [StoredRunRouting](/docs/api/app#storedrunrouting-interface)                                    | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [StoredThread](/docs/api/app#storedthread-interface)                                            | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [SuspendRunRequest](/docs/api/app#suspendrunrequest-interface)                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [SuspensionReceipt](/docs/api/app#suspensionreceipt-interface)                                  | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ThreadAction](/docs/api/app#threadaction-type-alias)                                           | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L15) |
| [ThreadList](/docs/api/app#threadlist-interface)                                                | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ThreadListItem](/docs/api/app#threadlistitem-interface)                                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ThreadSnapshot](/docs/api/app#threadsnapshot-interface)                                        | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L127) |
| [ThreadStatus](/docs/api/app#threadstatus-type-alias)                                           | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L8)  |
| [ThreadTransition](/docs/api/app#threadtransition-type-alias)                                   | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [ToolPartState](/docs/api/app#toolpartstate-type-alias)                                         | Type  | `@relkit/agents`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L12)                     |
| [WaitForControlsRequest](/docs/api/app#waitforcontrolsrequest-interface)                        | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |
| [WaitForJournalRequest](/docs/api/app#waitforjournalrequest-interface)                          | Type  | `@relkit/agents`                                 | [Module example](/docs/modules/ai/approvals)                                                                                      |

## `agent-client-chat.ts`

### copyAgentChat

Copies a chat mapping for synchronous descriptor callers.

**Throws**

TypeError for a noncanonical mapping.

**Example**

```ts
import { copyAgentChat } from "@relkit/agents";

const chat = copyAgentChat({ input: "message", output: "answer" });
void chat;
```

**Signature**

```ts
declare const copyAgentChat: (value: unknown) => AgentChatMapping | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-chat.ts#L64)

### copyAgentChatEffect

Validates the fixed chat input and output mapping.

**Example**

```ts
import { Effect } from "effect";
import { copyAgentChatEffect } from "@relkit/agents";

const chat = Effect.runSync(copyAgentChatEffect({ input: "message", output: "answer" }));
void chat;
```

**Signature**

```ts
declare const copyAgentChatEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ input: "message"; output: "answer" }> | undefined,
  AgentClientPolicyError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-chat.ts#L24)

## `agent-client-controls.ts`

### copyAgentControls

Copies client controls for synchronous descriptor callers.

**Throws**

TypeError when an unsupported or duplicate control is present.

**Example**

```ts
import { copyAgentControls } from "@relkit/agents";

const controls = copyAgentControls(["stop"]);
void controls;
```

**Signature**

```ts
declare const copyAgentControls: (value: unknown) => readonly AgentControl[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-controls.ts#L76)

### copyAgentControlsEffect

Validates and freezes client control capabilities.

**Example**

```ts
import { Effect } from "effect";
import { copyAgentControlsEffect } from "@relkit/agents";

const controls = Effect.runSync(copyAgentControlsEffect(["stop"]));
void controls;
```

**Signature**

```ts
declare const copyAgentControlsEffect: (
  value: unknown,
) => Effect.Effect<ReadonlyArray<AgentControl> | undefined, AgentClientPolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-controls.ts#L26)

## `agent-client-error.ts`

### AgentClientPolicyError (class)

Expected client configuration failure in the Effect error channel.

**Signature**

```ts
declare class AgentClientPolicyError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-error.ts#L4)

### clientPolicyCount

**Signature**

```ts
declare const clientPolicyCount: Metric.Counter<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-error.ts#L9)

### clientPolicyFailures

**Signature**

```ts
declare const clientPolicyFailures: Metric.Counter<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-error.ts#L10)

## `agent-client-policy.ts`

### copyAgentClientPolicy

Copies a client policy for synchronous descriptor callers.

**Throws**

TypeError for malformed access, state, or event declarations.

**Example**

```ts
import { copyAgentClientPolicy } from "@relkit/agents";

const policy = copyAgentClientPolicy({ public: true }, new Set<string>());
void policy;
```

**Signature**

```ts
declare const copyAgentClientPolicy: <StateKey extends string>(
  value: unknown,
  allowedStateKeys?: ReadonlySet<StateKey>,
) => AgentClientPolicy<(...args: any[]) => unknown, StateKey> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-policy.ts#L71)

### copyAgentClientPolicyEffect

Validates and freezes client access, state keys, and event schemas.

**Example**

```ts
import { Effect } from "effect";
import { copyAgentClientPolicyEffect } from "@relkit/agents";

const policy = Effect.runSync(copyAgentClientPolicyEffect({ public: true }, new Set<string>()));
void policy;
```

**Signature**

```ts
declare const copyAgentClientPolicyEffect: <StateKey extends string>(
  value: unknown,
  allowedStateKeys?: ReadonlySet<StateKey> | undefined,
) => Effect.Effect<
  | Readonly<{
      events?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
      state?: ReadonlyArray<StateKey>;
      public: true;
    }>
  | Readonly<{
      events?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
      state?: ReadonlyArray<StateKey>;
      authorize: (...args: any[]) => unknown;
    }>
  | undefined,
  AgentClientPolicyError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client-policy.ts#L26)

## `agent-client.ts`

### "./agent-client-chat.js" (namespace export)

Re-exports all named exports from the "./agent-client-chat.js" module.

**Signature**

```ts
export * from "./agent-client-chat.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L3)

### "./agent-client-controls.js" (namespace export)

Re-exports all named exports from the "./agent-client-controls.js" module.

**Signature**

```ts
export * from "./agent-client-controls.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L2)

### "./agent-client-error.js" (namespace export)

Re-exports all named exports from the "./agent-client-error.js" module.

**Signature**

```ts
export * from "./agent-client-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L4)

### "./agent-client-policy.js" (namespace export)

Re-exports all named exports from the "./agent-client-policy.js" module.

**Signature**

```ts
export * from "./agent-client-policy.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L1)

### AgentChatMapping

**Signature**

```ts
declare const AgentChatMapping: AgentChatMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L9)

### AgentClientEvents

**Signature**

```ts
declare const AgentClientEvents: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L7)

### AgentClientPolicy

**Signature**

```ts
declare const AgentClientPolicy: AgentClientPolicy<Guard, StateKey, Events>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L8)

### AgentControl

**Signature**

```ts
declare const AgentControl: AgentControl;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.ts#L6)

## `agent-client.types.ts`

### AgentChatMapping (interface)

Fixed input and output field mapping for an agent chat client.

**Example**

```ts
const chat: AgentChatMapping = { input: "message", output: "answer" };
```

**Signature**

```ts
export interface AgentChatMapping {
  readonly input: "message";
  readonly output: "answer";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.types.ts#L43)

### AgentClientEvents (type alias)

Named public events and their Standard Schema validators.
Names must be nonempty before the policy is published.

**Example**

```ts
import { z } from "@relkit/schema";
const events: AgentClientEvents = { completed: z.string() };
```

**Signature**

```ts
type AgentClientEvents = Readonly<Record<string, StandardSchemaV1>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.types.ts#L19)

### AgentClientPolicy (type alias)

Client visibility, selected state, and public event schemas.
Exactly one of public access and an authorization guard must be supplied.

**Example**

```ts
const policy: AgentClientPolicy = { public: true, state: ["answer"] };
```

**Signature**

```ts
type AgentClientPolicy<
  Guard = (...args: any[]) => unknown,
  StateKey extends string = string,
  Events extends AgentClientEvents = AgentClientEvents,
> = (
  | { readonly public: true; readonly authorize?: never }
  | { readonly authorize: Guard; readonly public?: never }
) & {
  readonly state?: readonly StateKey[];
  readonly events?: Events;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.types.ts#L28)

### AgentControl (type alias)

Durable control capabilities that may be exposed to an agent client.

**Example**

```ts
const control: AgentControl = "stop";
```

**Signature**

```ts
type AgentControl = "steer" | "follow-up" | "stop" | "approve";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-client.types.ts#L9)

## `agent-telemetry.ts`

### AgentOperation

**Signature**

```ts
declare const AgentOperation: AgentOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.ts#L4)

### AgentTelemetry (class)

Injectable telemetry boundary for agent operations.

**Example**

```ts
Effect.provide(observeAgent("capture.policy", Effect.void), AgentTelemetryLive);
```

**Signature**

```ts
declare class AgentTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.ts#L9)

### AgentTelemetryLive

Live metric observer for traced agent operations.

**Example**

```ts
Effect.runSync(Effect.provide(observeAgent("capture.policy", Effect.void), AgentTelemetryLive));
```

**Signature**

```ts
declare const AgentTelemetryLive: Layer.Layer<AgentTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.ts#L16)

### AgentTelemetryService

**Signature**

```ts
declare const AgentTelemetryService: AgentTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.ts#L4)

### observeAgent

Records a call, duration, and failure with a fixed operation label.

**Example**

```ts
observeAgent("capture.policy", Effect.succeed({ mode: "off" }));
```

**Signature**

```ts
declare const observeAgent: <A, E, R>(
  operation: AgentOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.ts#L30)

## `agent-telemetry.types.ts`

### AgentOperation (type alias)

Fixed operation labels for agent telemetry; no user value is a label.

**Example**

```ts
const operation: AgentOperation = "runtime.invoke-tool";
```

**Signature**

```ts
type AgentOperation =
  | "client.controls"
  | "client.chat"
  | "client.copy"
  | "validation.schema"
  | "validation.is-schema"
  | "validation.positive-integer"
  | "validation.is-positive-integer"
  | "validation.is-record"
  | "capture.policy"
  | "capture.content"
  | "capture.span"
  | "client-schema.merge"
  | "client-schema.select"
  | "client-schema.project"
  | "client-events.project"
  | "graph-state.select"
  | "graph-interruption.response"
  | "graph-interruption.requests"
  | "graph-interruption.is-error"
  | "thread-transition.decide"
  | "runtime.invoke"
  | "runtime.create"
  | "approval.requires"
  | "approval.create"
  | "approval.approve"
  | "approval.deny"
  | "approval.assert-granted"
  | "approval.is-record"
  | "model-selector.normalize"
  | "model-selector.parse"
  | "model-selector.resolve"
  | "persistence.release"
  | "persistence.resolve-graph"
  | "persistence.resolve-agent"
  | "bucket.list"
  | "bucket.delete"
  | "bucket.glob"
  | "bucket.grep"
  | "bucket.read-data"
  | "bucket.write-data"
  | "bucket.scoped-keys"
  | "bucket.info"
  | "bucket.read-raw"
  | "bucket.read"
  | "bucket.write"
  | "bucket.edit"
  | "bucket.upload"
  | "bucket.download"
  | "bucket.create"
  | "bucket.thread"
  | "definition.copy-instructions"
  | "definition.is-instructions"
  | "definition.is-descriptor"
  | "definition.assert-descriptor"
  | "definition.normalize-model"
  | "definition.copy-deep"
  | "definition.has-deep"
  | "definition.is-model"
  | "definition.copy-middleware"
  | "definition.state-keys"
  | "definition.copy-tools"
  | "definition.tool-refs"
  | "graph.validate-resume"
  | "graph.waiting"
  | "graph.config"
  | "graph.resume-command"
  | "graph-node.destinations"
  | "graph-node.copy-ends"
  | "graph-node.result"
  | "graph-node.input"
  | "graph-node.handle"
  | "graph-node.define"
  | "graph-node.is-descriptor"
  | "definition.copy-limits"
  | "definition.define"
  | "generated.id"
  | "generated.create"
  | "generated.is-function"
  | "persistence.is-resource"
  | "persistence.assert-protocol"
  | "persistence.define-checkpointer"
  | "persistence.define-memory"
  | "runtime.resolve-model"
  | "runtime.content-limits"
  | "graph.invoke"
  | "graph.workflow"
  | "graph.requires-persistence"
  | "graph.define"
  | "graph.execution"
  | "graph.is-descriptor"
  | "graph.subgraph-create"
  | "graph.subgraph-is-node"
  | "graph.subgraph-source"
  | "native-hitl.response-schema"
  | "native-hitl.is-request"
  | "native-hitl.public-request"
  | "native-hitl.is-decision"
  | "native-hitl.is-record"
  | "native-hitl.resume-command"
  | "native-hitl.waiting"
  | "native-hitl.validate-reply"
  | "graph.compile"
  | "graph.route"
  | "graph.edge-builder"
  | "graph.add-edge"
  | "graph.add-conditional-edge"
  | "graph.destination"
  | "graph.validate-route"
  | "graph.prepare-definition"
  | "runtime.validate-value"
  | "runtime.json-value"
  | "runtime.model-failure"
  | "runtime.selected-state-schemas"
  | "graph-node.validate-destinations"
  | "graph-node.command-update"
  | "graph-node.validated-update"
  | "graph-node.validated-value"
  | "bucket.context"
  | "bucket.virtual-path"
  | "bucket.key"
  | "bucket.file-path"
  | "bucket.page"
  | "bucket.control-failure"
  | "bucket.error-message"
  | "bucket.text-mime-type"
  | "runtime.collect-native-events"
  | "runtime.emit-native-tool-event"
  | "runtime.selected-state"
  | "runtime.select-state-fields"
  | "runtime.native-public-event"
  | "runtime.public-event-value"
  | "runtime.public-tool-value"
  | "runtime.message-update"
  | "runtime.native-limits"
  | "runtime.model-limit"
  | "runtime.tool-limit"
  | "runtime.combine-native-tools"
  | "runtime.native-instructions"
  | "runtime.load-deepagents"
  | "runtime.assert-dependencies"
  | "runtime.model-tool-name"
  | "runtime.find-model-tool"
  | "runtime.find-tool"
  | "runtime.run-tool"
  | "runtime.emit-tool"
  | "runtime.resolve-approval"
  | "runtime.create-tool-dispatcher"
  | "runtime.invoke-tool"
  | "graph.stream-compiled"
  | "graph.run-compiled"
  | "observability.emit-edge"
  | "runtime.create-native-tools"
  | "runtime.create-agent-tools"
  | "runtime.response-format"
  | "runtime.child-model"
  | "runtime.create-subagents"
  | "runtime.create-native-agent"
  | "runtime.native-messages"
  | "runtime.response-value"
  | "runtime.unwrap-native-cause"
  | "runtime.run-loop"
  | "signal.failure"
  | "signal.create"
  | "signal.acquire"
  | "signal.with-signal"
  | "client.agent-metadata"
  | "client.graph-metadata";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.types.ts#L6)

### AgentTelemetryService (interface)

Replaceable observer used by Effect operations and deterministic tests.

**Signature**

```ts
export interface AgentTelemetryService {
  /** Records an operation without changing its Effect channels.
   * @param operation - Fixed agent operation name.
   * @param effect - Work to instrument.
   * @returns The same success, error, and dependency channels.
   * @example telemetry.observe("capture.policy", Effect.succeed({ mode: "off" }));
   */
  readonly observe: <A, E, R>(
    operation: AgentOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-telemetry.types.ts#L176)

## `agent-validation-error.ts`

### AgentValidationError (class)

Typed validation failure raised by an Effect agent-authoring operation.

**Example**

```ts
const error = new AgentValidationError({
  operation: "positiveInteger",
  message: "limit must be positive",
});
```

**Signature**

```ts
declare class AgentValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-error.ts#L9)

### validationCount

**Signature**

```ts
declare const validationCount: Metric.Counter<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-error.ts#L14)

### validationFailures

**Signature**

```ts
declare const validationFailures: Metric.Counter<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-error.ts#L15)

## `agent-validation-schema.ts`

### assertAgentSchema

Throws for an invalid schema in existing synchronous authoring calls.

**Throws**

TypeError when the value is not a Standard Schema v1 validator.

**Example**

```ts
assertAgentSchema(z.string(), "input");
```

**Signature**

```ts
declare const assertAgentSchema: (
  value: unknown,
  name: string,
) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-schema.ts#L46)

### assertAgentSchemaEffect

Validates that a value implements the Standard Schema v1 protocol.

**Example**

```ts
const schema = Effect.runSync(assertAgentSchemaEffect(z.string(), "input"));
```

**Signature**

```ts
declare const assertAgentSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<StandardSchemaV1<unknown, unknown>, AgentValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-schema.ts#L19)

### isAgentSchema

Checks whether a candidate implements Standard Schema v1.

**Example**

```ts
if (isAgentSchema(value)) value["~standard"].validate(input);
```

**Signature**

```ts
declare const isAgentSchema: (value: unknown) => value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-schema.ts#L83)

### isAgentSchemaEffect

Checks the Standard Schema v1 protocol without throwing.

**Example**

```ts
const valid = Effect.runSync(isAgentSchemaEffect(z.string()));
```

**Signature**

```ts
declare const isAgentSchemaEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-schema.ts#L66)

## `agent-validation-value.ts`

### isPositiveInteger

Checks a finite positive integer for existing synchronous callers.

**Example**

```ts
if (isPositiveInteger(value)) console.log(value + 1);
```

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L82)

### isPositiveIntegerEffect

Checks for a finite positive integer without throwing.

**Example**

```ts
const valid = Effect.runSync(isPositiveIntegerEffect(3));
```

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L65)

### isRecord

Checks a record for existing synchronous callers.

**Example**

```ts
if (isRecord(value)) console.log(value.id);
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L111)

### isRecordEffect

Checks a non-null, non-array record through an Effect operation.

**Example**

```ts
const valid = Effect.runSync(isRecordEffect({ id: "one" }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L94)

### positiveInteger

Validates a finite positive integer for existing synchronous callers.

**Throws**

TypeError when the value is not a finite positive integer.

**Example**

```ts
const limit = positiveInteger(3, "maxSteps");
```

**Signature**

```ts
declare const positiveInteger: (value: unknown, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L45)

### positiveIntegerEffect

Validates a finite positive integer with a typed Effect failure.

**Example**

```ts
const limit = Effect.runSync(positiveIntegerEffect(3, "maxSteps"));
```

**Signature**

```ts
declare const positiveIntegerEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<number, AgentValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation-value.ts#L18)

## `agent-validation.ts`

### "./agent-validation-error.js" (namespace export)

Re-exports all named exports from the "./agent-validation-error.js" module.

**Signature**

```ts
export * from "./agent-validation-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation.ts#L1)

### "./agent-validation-schema.js" (namespace export)

Re-exports all named exports from the "./agent-validation-schema.js" module.

**Signature**

```ts
export * from "./agent-validation-schema.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation.ts#L2)

### "./agent-validation-value.js" (namespace export)

Re-exports all named exports from the "./agent-validation-value.js" module.

**Signature**

```ts
export * from "./agent-validation-value.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/agent-validation.ts#L3)

## `approval-core.ts`

### APPROVAL_STATES

**Signature**

```ts
declare const APPROVAL_STATES: readonly ["pending", "approved", "denied"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L18)

### approveApprovalValue

Grants a pending approval.

**Throws**

ApprovalStateError for an invalid transition.

**Example**

```ts
approveApprovalValue(pending);
```

**Signature**

```ts
declare const approveApprovalValue: (approval: ApprovalRecord) => ApprovedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L55)

### assertApprovalGrantedValue

Checks whether execution is approved.

**Throws**

ApprovalRequiredError, ApprovalDeniedError, or ApprovalStateError.

**Example**

```ts
assertApprovalGrantedValue(approved);
```

**Signature**

```ts
declare const assertApprovalGrantedValue: (
  approval: ApprovalRecord,
) => asserts approval is ApprovedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L77)

### createApprovalValue

Constructs a canonical approval record.

**Throws**

TypeError or ApprovalStateError for invalid metadata.

**Example**

```ts
createApprovalValue(options);
```

**Signature**

```ts
declare const createApprovalValue: (options: ApprovalOptions) => ApprovalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L44)

### denyApprovalValue

Denies a pending approval.

**Throws**

ApprovalStateError for an invalid transition.

**Example**

```ts
denyApprovalValue(pending);
```

**Signature**

```ts
declare const denyApprovalValue: (approval: ApprovalRecord) => DeniedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L66)

### isApprovalRecordValue

Recognizes canonical approval records.

**Example**

```ts
isApprovalRecordValue(value);
```

**Signature**

```ts
declare const isApprovalRecordValue: (value: unknown) => value is ApprovalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L90)

### requiresApprovalValue

Computes whether a policy requires approval.

**Throws**

TypeError for invalid inputs.

**Example**

```ts
requiresApprovalValue("always", "read");
```

**Signature**

```ts
declare const requiresApprovalValue: (
  policy: ApprovalPolicy,
  sideEffect: ApprovalSideEffect,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-core.ts#L27)

## `approval-effect-error.ts`

### ApprovalEffectError (class)

Tagged failure for an invalid approval or denied execution.

**Signature**

```ts
declare class ApprovalEffectError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-effect-error.ts#L9)

### approvalEffectError

Preserves an approval error for typed Effect recovery and compatibility adapters.

**Example**

```ts
approvalEffectError(new ApprovalStateError("invalid state"));
```

**Signature**

```ts
declare const approvalEffectError: (cause: unknown) => ApprovalEffectError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-effect-error.ts#L19)

## `approval-error.ts`

### ApprovalDeniedError (class)

Execution was attempted after an approval was denied.

**Example**

```ts
throw new ApprovalDeniedError(denied);
```

**Signature**

```ts
declare class ApprovalDeniedError { constructor(readonly approval: DeniedApproval) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L28)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_APPROVAL_DENIED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L29)

### ApprovalRequiredError (class)

Execution was attempted while an approval remains pending.

**Example**

```ts
throw new ApprovalRequiredError(pending);
```

**Signature**

```ts
declare class ApprovalRequiredError { constructor(readonly approval: PendingApproval) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L17)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_APPROVAL_REQUIRED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L18)

### ApprovalStateError (class)

A malformed approval or invalid state transition.

**Example**

```ts
throw new ApprovalStateError("Cannot transition approved approval");
```

**Signature**

```ts
declare class ApprovalStateError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L6)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_APPROVAL_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval-error.ts#L7)

## `approval.ts`

### approveApproval

Moves a pending approval to the approved state.

**Throws**

ApprovalStateError for a malformed or final decision.

**Example**

```ts
import { approveApproval, createApproval } from "@relkit/app/agents";

const pending = createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});
const approved = approveApproval(pending);
void approved;
```

**Signature**

```ts
declare const approveApproval: (approval: ApprovalRecord) => ApprovedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L106)

Since v0.4.0

### denyApproval

Moves a pending approval to the denied state.

**Throws**

ApprovalStateError for a malformed or final decision.

**Example**

```ts
import { createApproval, denyApproval } from "@relkit/app/agents";

const pending = createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});
const denied = denyApproval(pending);
void denied;
```

**Signature**

```ts
declare const denyApproval: (approval: ApprovalRecord) => DeniedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L139)

Since v0.4.0

### "./approval.types.js" (namespace export)

Re-exports all named exports from the "./approval.types.js" module.

**Signature**

```ts
export * from "./approval.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L28)

### APPROVAL_STATES

**Signature**

```ts
declare const APPROVAL_STATES: readonly ["pending", "approved", "denied"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L21)

### ApprovalDeniedError

**Signature**

```ts
declare const ApprovalDeniedError: typeof ApprovalDeniedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L23)

### ApprovalEffectError

**Signature**

```ts
declare const ApprovalEffectError: typeof ApprovalEffectError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L27)

### ApprovalRequiredError

**Signature**

```ts
declare const ApprovalRequiredError: typeof ApprovalRequiredError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L24)

### ApprovalStateError

**Signature**

```ts
declare const ApprovalStateError: typeof ApprovalStateError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L25)

### approveApprovalEffect

Moves a pending approval to the approved state.

**Example**

```ts
Effect.runSync(approveApprovalEffect(pending));
```

**Signature**

```ts
declare const approveApprovalEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<ApprovedApproval, ApprovalEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L82)

### assertApprovalGranted

Rejects execution unless the record is approved.

**Throws**

ApprovalRequiredError, ApprovalDeniedError, or ApprovalStateError.

**Example**

```ts
assertApprovalGranted(approved);
```

**Signature**

```ts
declare const assertApprovalGranted: (
  approval: ApprovalRecord,
) => asserts approval is ApprovedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L160)

### assertApprovalGrantedEffect

Fails unless the record was approved.

**Example**

```ts
Effect.runSync(assertApprovalGrantedEffect(approved));
```

**Signature**

```ts
declare const assertApprovalGrantedEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<void, ApprovalEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L148)

### createApproval

Creates an immutable pending or policy-approved record.

**Throws**

TypeError or ApprovalStateError for invalid metadata.

**Example**

```ts
createApproval({
  invocationId: "run",
  toolCallId: "call",
  toolId: "send",
  sideEffect: "write",
  policy: "always",
});
```

**Signature**

```ts
declare const createApproval: (options: ApprovalOptions) => ApprovalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L73)

### createApprovalEffect

Creates an immutable pending or policy-approved record.

**Example**

```ts
Effect.runSync(createApprovalEffect(options));
```

**Signature**

```ts
declare const createApprovalEffect: (
  options: ApprovalOptions,
) => Effect.Effect<ApprovalRecord, ApprovalEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L61)

### denyApprovalEffect

Moves a pending approval to the denied state.

**Example**

```ts
Effect.runSync(denyApprovalEffect(pending));
```

**Signature**

```ts
declare const denyApprovalEffect: (
  approval: ApprovalRecord,
) => Effect.Effect<DeniedApproval, ApprovalEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L115)

### isApprovalRecord

Checks whether a value is a canonical approval record.

**Example**

```ts
if (isApprovalRecord(value)) console.log(value.state);
```

**Signature**

```ts
declare const isApprovalRecord: (value: unknown) => value is ApprovalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L181)

### isApprovalRecordEffect

Checks whether a value is a canonical approval record.

**Example**

```ts
Effect.runSync(isApprovalRecordEffect(value));
```

**Signature**

```ts
declare const isApprovalRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L171)

### requiresApproval

Tests whether a tool call needs an explicit approval decision.

**Throws**

TypeError for an invalid policy or side effect.

**Example**

```ts
requiresApproval("on-write", "write");
```

**Signature**

```ts
declare const requiresApproval: (policy: ApprovalPolicy, sideEffect: ApprovalSideEffect) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L52)

### requiresApprovalEffect

Tests whether a tool call needs an explicit approval decision.

**Example**

```ts
Effect.runSync(requiresApprovalEffect("on-write", "write"));
```

**Signature**

```ts
declare const requiresApprovalEffect: (
  policy: FunctionToolApproval,
  sideEffect: FunctionToolSideEffect,
) => Effect.Effect<boolean, ApprovalEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.ts#L36)

## `approval.types.ts`

### ApprovalMetadata (interface)

Argument-free metadata for one invocation and tool-call decision.

**Signature**

```ts
export interface ApprovalMetadata extends ApprovalOptions {
  readonly required: boolean;
  readonly state: ApprovalState;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L20)

### ApprovalOptions (interface)

Inputs used to create an approval record.

**Signature**

```ts
export interface ApprovalOptions {
  readonly invocationId: string;
  readonly toolCallId: string;
  readonly toolId: string;
  readonly sideEffect: ApprovalSideEffect;
  readonly policy: ApprovalPolicy;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L11)

### ApprovalPolicy (type alias)

Policy controlling which tool calls require approval.

**Signature**

```ts
type ApprovalPolicy = ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L6)

### ApprovalRecord (type alias)

Canonical approval record in any valid state.

**Signature**

```ts
type ApprovalRecord = PendingApproval | ApprovedApproval | DeniedApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L41)

### ApprovalSideEffect (type alias)

Declared side effect of a tool call.

**Signature**

```ts
type ApprovalSideEffect = ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L8)

### ApprovalState (type alias)

One canonical approval state.

**Signature**

```ts
type ApprovalState = "pending" | "approved" | "denied";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L4)

### ApprovedApproval (interface)

Approval granted by policy or an explicit decision.

**Signature**

```ts
export interface ApprovedApproval extends ApprovalMetadata {
  readonly state: "approved";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L31)

### DeniedApproval (interface)

Approval explicitly denied.

**Signature**

```ts
export interface DeniedApproval extends ApprovalMetadata {
  readonly state: "denied";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L36)

### PendingApproval (interface)

Approval that must receive a decision before execution.

**Signature**

```ts
export interface PendingApproval extends ApprovalMetadata {
  readonly state: "pending";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/approval.types.ts#L26)

## `capture-content.ts`

### captureAgentContent

Captures redacted content for synchronous runtime callers.

**Example**

```ts
const record = captureAgentContent({ token: "secret" }, policy);
```

**Signature**

```ts
declare const captureAgentContent: (
  value: unknown,
  policy: AgentCapturePolicy,
) => AgentCaptureRecord | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-content.ts#L55)

### captureAgentContentEffect

Redacts and bounds a JSON-compatible agent value.

**Example**

```ts
const record = Effect.runSync(captureAgentContentEffect({ token: "secret" }, policy));
```

**Signature**

```ts
declare const captureAgentContentEffect: (
  value: unknown,
  policy: AgentCapturePolicy,
) => Effect.Effect<AgentCaptureRecord | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-content.ts#L18)

## `capture-policy.ts`

### AgentCapturePolicyError (class)

Invalid capture configuration in the Effect error channel.

**Signature**

```ts
declare class AgentCapturePolicyError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-policy.ts#L19)

### createAgentCapturePolicy

Creates a capture policy for synchronous descriptor callers.

**Throws**

TypeError when mode, size, or redaction keys are invalid.

**Example**

```ts
const policy = createAgentCapturePolicy({ mode: "development-redacted", maxBytes: 1024 });
```

**Signature**

```ts
declare const createAgentCapturePolicy: (
  value: AgentCapturePolicy | undefined,
) => AgentCapturePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-policy.ts#L89)

### createAgentCapturePolicyEffect

Validates and freezes a content capture policy.

**Example**

```ts
const policy = Effect.runSync(createAgentCapturePolicyEffect({ mode: "off" }));
```

**Signature**

```ts
declare const createAgentCapturePolicyEffect: (
  value: AgentCapturePolicy | undefined,
) => Effect.Effect<AgentCapturePolicy, AgentCapturePolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-policy.ts#L32)

## `capture-span.ts`

### createAgentSpanCapture

Combines captured input and output for synchronous runtime callers.

**Example**

```ts
const capture = createAgentSpanCapture(input, output);
```

**Signature**

```ts
declare const createAgentSpanCapture: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => AgentSpanCapture | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-span.ts#L37)

### createAgentSpanCaptureEffect

Combines optional captured input and output for an agent span.

**Example**

```ts
const capture = Effect.runSync(createAgentSpanCaptureEffect(input, output));
```

**Signature**

```ts
declare const createAgentSpanCaptureEffect: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => Effect.Effect<
  Readonly<{ output?: AgentCaptureRecord; input?: AgentCaptureRecord }> | undefined,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture-span.ts#L16)

## `capture.ts`

### "./capture-content.js" (namespace export)

Re-exports all named exports from the "./capture-content.js" module.

**Signature**

```ts
export * from "./capture-content.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L2)

### "./capture-policy.js" (namespace export)

Re-exports all named exports from the "./capture-policy.js" module.

**Signature**

```ts
export * from "./capture-policy.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L1)

### "./capture-span.js" (namespace export)

Re-exports all named exports from the "./capture-span.js" module.

**Signature**

```ts
export * from "./capture-span.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L3)

### AgentCapturePolicy

**Signature**

```ts
declare const AgentCapturePolicy: AgentCapturePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L4)

### AgentCaptureRecord

**Signature**

```ts
declare const AgentCaptureRecord: AgentCaptureRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L4)

### AgentSpanCapture

**Signature**

```ts
declare const AgentSpanCapture: AgentSpanCapture;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.ts#L4)

## `capture.types.ts`

### AgentCapturePolicy (interface)

Controls whether an agent may retain redacted content in its spans.
Development capture requires a positive byte limit; off ignores the other fields.

**Example**

```ts
const policy: AgentCapturePolicy = { mode: "development-redacted", maxBytes: 1024 };
```

**Signature**

```ts
export interface AgentCapturePolicy {
  readonly mode: "off" | "development-redacted";
  readonly maxBytes?: number;
  readonly redactKeys?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.types.ts#L10)

### AgentCaptureRecord (interface)

Captured JSON and its encoded size, or a marker when capture was truncated.
The content property is absent whenever truncated is true.

**Example**

```ts
const record: AgentCaptureRecord = { mode: "development-redacted", bytes: 0, truncated: true };
```

**Signature**

```ts
export interface AgentCaptureRecord {
  readonly mode: "development-redacted";
  readonly bytes: number;
  readonly truncated: boolean;
  readonly content?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.types.ts#L23)

### AgentSpanCapture (interface)

Optional input and output captures attached to one agent span.
Absent fields were disabled or unavailable at capture time.

**Example**

```ts
const capture: AgentSpanCapture = {
  input: { mode: "development-redacted", bytes: 0, truncated: true },
};
```

**Signature**

```ts
export interface AgentSpanCapture {
  readonly input?: AgentCaptureRecord;
  readonly output?: AgentCaptureRecord;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/capture.types.ts#L39)

## `client-contract-metadata.ts`

Projects generic RELKIT tool references and public event schemas into client metadata.
Native middleware, graph state and SDK schema projection remain in @relkit/langchain.

### "./client-contract-metadata.types.js" (namespace export)

Re-exports all named exports from the "./client-contract-metadata.types.js" module.

**Signature**

```ts
export * from "./client-contract-metadata.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.ts#L16)

### agentClientContractMetadata

Projects generic metadata for synchronous authoring.

**Throws**

The original metadata projection error.

**Signature**

```ts
declare const agentClientContractMetadata: (
  options: AgentClientMetadataOptions,
) => AgentClientContractMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.ts#L51)

### agentClientContractMetadataEffect

Projects an ordinary agent's public contract without evaluating native schemas.

**Signature**

```ts
declare const agentClientContractMetadataEffect: (
  options: AgentClientMetadataOptions,
) => Effect.Effect<AgentClientContractMetadata, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.ts#L22)

## `client-contract-metadata.types.ts`

Declares serializable agent client contract metadata shared by SDK-free authoring, graph normalization and runtime client projections. This companion contains the shared planning contracts without executing work.

### AgentClientContractMetadata (interface)

Complete metadata needed to generate an agent client contract.

**Signature**

```ts
export interface AgentClientContractMetadata {
  readonly tools: readonly ClientToolMetadata[];
  readonly state: readonly ClientTypeField[];
  readonly events: readonly ClientEventMetadata[];
  readonly scopes: readonly ClientScopeMetadata[];
  readonly waiting: readonly ClientWaitingMetadata[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L32)

### AgentClientMetadataOptions (interface)

Inputs for native agent client metadata.

**Signature**

```ts
export interface AgentClientMetadataOptions {
  readonly id: string;
  readonly tools: readonly ToolRefAny[];
  readonly middleware?: readonly [];
  readonly client?: AgentClientPolicy;
  readonly subagents?: readonly SubagentMetadataSource[];
  readonly interruptOn?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L47)

### ClientEventMetadata (type alias)

Client visible event schema or dynamic event marker.

**Signature**

```ts
type ClientEventMetadata = ClientTypeField | { readonly kind: "dynamic" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L8)

### ClientScopeMetadata (interface)

Client visible agent, subagent, or graph node scope.

**Signature**

```ts
export interface ClientScopeMetadata {
  readonly kind: "agent" | "subagent" | "node" | "dynamic";
  readonly id?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L20)

### ClientToolMetadata (type alias)

Client visible tool schema or dynamic tool marker.

**Signature**

```ts
type ClientToolMetadata =
  | {
      readonly id: string;
      readonly input: ClientSchemaMetadata;
      readonly output: ClientSchemaMetadata;
    }
  | { readonly kind: "dynamic" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L11)

### ClientWaitingMetadata (interface)

Client visible continuation response schema.

**Signature**

```ts
export interface ClientWaitingMetadata {
  readonly scope: ClientScopeMetadata;
  readonly response: ClientSchemaMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L26)

### SubagentMetadataSource (interface)

Source of nested subagent scope identities.

**Signature**

```ts
export interface SubagentMetadataSource {
  readonly id: string;
  readonly subagents?: readonly SubagentMetadataSource[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-metadata.types.ts#L41)

## `client-contract-schema.ts`

Describes Standard Schema input and output contracts for generic agent clients without importing a native model or graph SDK.

### ClientSchemaMetadata

**Signature**

```ts
declare const ClientSchemaMetadata: ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L10)

### ClientTypeField

**Signature**

```ts
declare const ClientTypeField: ClientTypeField;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L10)

### clientSchemaMetadata

Synchronously projects schema metadata for existing descriptor callers.

**Example**

```ts
const metadata = clientSchemaMetadata({ type: "string" });
```

**Signature**

```ts
declare const clientSchemaMetadata: (value: unknown) => ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L143)

### clientSchemaMetadataEffect

Projects a schema-like value to safe client metadata.

**Example**

```ts
const metadata = Effect.runSync(clientSchemaMetadataEffect({ type: "string" }));
```

**Signature**

```ts
declare const clientSchemaMetadataEffect: (
  value: unknown,
) => Effect.Effect<ClientSchemaMetadata, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L115)

### dynamicClientSchema

Marker for a schema that cannot be represented in the client contract.

**Signature**

```ts
declare const dynamicClientSchema: Readonly<{ kind: "dynamic" }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L13)

### mergeClientSchemas

Synchronously merges client schemas for existing descriptor callers.

**Example**

```ts
const schema = mergeClientSchemas([{ type: "object" }]);
```

**Signature**

```ts
declare const mergeClientSchemas: (values: readonly unknown[]) => ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L53)

### mergeClientSchemasEffect

Merges projected object schemas while preserving input order.

**Example**

```ts
const schema = Effect.runSync(mergeClientSchemasEffect([{ type: "object" }]));
```

**Signature**

```ts
declare const mergeClientSchemasEffect: (
  values: ReadonlyArray<unknown>,
) => Effect.Effect<JsonValue, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L27)

### selectedClientFields

Synchronously selects client fields for existing descriptor callers.

**Example**

```ts
const fields = selectedClientFields({ type: "object" }, ["name"]);
```

**Signature**

```ts
declare const selectedClientFields: (
  schema: ClientSchemaMetadata,
  keys?: readonly string[],
) => readonly ClientTypeField[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L100)

### selectedClientFieldsEffect

Selects named client state fields from a projected object schema.

**Example**

```ts
const fields = Effect.runSync(selectedClientFieldsEffect({ type: "object" }, ["name"]));
```

**Signature**

```ts
declare const selectedClientFieldsEffect: (
  schema: ClientSchemaMetadata,
  keys?: ReadonlyArray<string> | undefined,
) => Effect.Effect<ReadonlyArray<ClientTypeField>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.ts#L66)

## `client-contract-schema.types.ts`

### ClientSchemaMetadata (type alias)

A projected JSON Schema fragment or an intentionally dynamic field.

**Signature**

```ts
type ClientSchemaMetadata = JsonValue | { readonly kind: "dynamic" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.types.ts#L4)

### ClientTypeField (interface)

One client-visible state field with its projected schema.

**Signature**

```ts
export interface ClientTypeField {
  readonly name: string;
  readonly schema: ClientSchemaMetadata;
  readonly optional?: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-contract-schema.types.ts#L7)

## `client-events.ts`

Projects durable agent journal records into bounded client lifecycle events while preserving tool identity and declared public values.

### AgentClientEvent

**Signature**

```ts
declare const AgentClientEvent: AgentClientEvent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-events.ts#L12)

### AgentProgressEvent

**Signature**

```ts
declare const AgentProgressEvent: AgentProgressEvent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-events.ts#L12)

### AgentToolEvent

**Signature**

```ts
declare const AgentToolEvent: AgentToolEvent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-events.ts#L12)

### agentClientEvents

Projects a journal record for existing synchronous client callers.

**Example**

```ts
const events = agentClientEvents(record);
```

**Signature**

```ts
declare const agentClientEvents: (record: JournalRecord) => readonly AgentClientEvent[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-events.ts#L40)

### agentClientEventsEffect

Projects one journal record into ordered, public client events.

**Example**

```ts
const events = Effect.runSync(agentClientEventsEffect(record));
```

**Signature**

```ts
declare const agentClientEventsEffect: (
  record: JournalRecord,
) => Effect.Effect<ReadonlyArray<AgentClientEvent>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-events.ts#L24)

## `client-tool-events.ts`

Projects tool message parts into stable public event identities in authored order.

### toolClientEvents

**Signature**

```ts
declare const toolClientEvents: (
  base: ClientEventBase,
  message: BrowserMessage,
) => readonly AgentClientEvent[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/client-tool-events.ts#L6)

## `define-agent-build.ts`

Validates generic authoring inputs before binding a descriptor identity.
Native fields are rejected with their integration import so no capability is silently ignored.

### prepareAgentDescriptor

Prepares immutable generic metadata before applying its stable identity.

**Throws**

TypeError for unsupported native fields or invalid generic inputs.

**Signature**

```ts
declare const prepareAgentDescriptor: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Tools extends readonly ToolRefAny[],
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Tools>,
) => (
  id: Id,
) => AgentDescriptor<
  Id,
  InferInput<InputSchema>,
  InferOutput<OutputSchema>,
  InputSchema,
  OutputSchema,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-build.ts#L25)

## `define-agent-error.ts`

### AgentDefinitionFailure (class)

Tagged validation failure while copying an agent definition.

**Signature**

```ts
declare class AgentDefinitionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-error.ts#L4)

### agentDefinitionFailure

Preserves the original authoring error in a tagged Effect failure.

**Example**

```ts
agentDefinitionFailure(new TypeError("invalid"));
```

**Signature**

```ts
declare const agentDefinitionFailure: (cause: unknown) => AgentDefinitionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-error.ts#L14)

## `define-agent-limits.ts`

### copyAgentLimits

Copies limits for existing synchronous authoring callers.

**Throws**

The original invalid limits TypeError.

**Example**

```ts
const limits = copyAgentLimits({ maxSteps: 3, maxToolCalls: 2, timeoutMs: 1000 });
```

**Signature**

```ts
declare const copyAgentLimits: (value: unknown) => AgentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-limits.ts#L38)

### copyAgentLimitsEffect

Validates and freezes an agent's execution limits.

**Example**

```ts
Effect.runSync(copyAgentLimitsEffect({ maxSteps: 3, maxToolCalls: 2, timeoutMs: 1000 }));
```

**Signature**

```ts
declare const copyAgentLimitsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ maxSteps: number; maxToolCalls: number; timeoutMs: number }>,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-limits.ts#L12)

## `define-agent-support.ts`

### copyAgentInstructions

Copies instructions for existing synchronous authoring callers.

**Throws**

The original invalid instruction error.

**Example**

```ts
const instructions = copyAgentInstructions("Answer clearly");
```

**Signature**

```ts
declare const copyAgentInstructions: (value: unknown) => AgentInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-support.ts#L31)

### copyAgentInstructionsEffect

Validates and freezes agent instructions.

**Example**

```ts
Effect.runSync(copyAgentInstructionsEffect("Answer clearly"));
```

**Signature**

```ts
declare const copyAgentInstructionsEffect: (
  value: unknown,
) => Effect.Effect<AgentInstructions, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-support.ts#L16)

### isAgentInstructions

Checks instructions for existing synchronous authoring callers.

**Example**

```ts
if (isAgentInstructions(value)) use(value);
```

**Signature**

```ts
declare const isAgentInstructions: (value: unknown) => value is AgentInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-support.ts#L63)

### isAgentInstructionsEffect

Checks whether a value is an agent instruction descriptor.

**Example**

```ts
Effect.runSync(isAgentInstructionsEffect("Answer clearly"));
```

**Signature**

```ts
declare const isAgentInstructionsEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-support.ts#L53)

## `define-agent-validation.ts`

Validates generic agent descriptors and selector models before assembly, rejecting native execution options with an explicit integration import diagnostic.

### assertAgentDescriptor

Requires a descriptor for existing synchronous authoring callers.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
assertAgentDescriptor(candidate);
```

**Signature**

```ts
declare const assertAgentDescriptor: (value: unknown) => asserts value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L75)

### assertAgentDescriptorEffect

Requires a valid agent descriptor.

**Example**

```ts
Effect.runSync(assertAgentDescriptorEffect(agent));
```

**Signature**

```ts
declare const assertAgentDescriptorEffect: (
  value: unknown,
) => Effect.Effect<void, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L58)

### isAgentDescriptor

Checks a descriptor for existing synchronous authoring callers.

**Example**

```ts
if (isAgentDescriptor(candidate)) use(candidate);
```

**Signature**

```ts
declare const isAgentDescriptor: (value: unknown) => value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L29)

### isAgentDescriptorEffect

Checks the complete runtime shape of an agent descriptor.

**Example**

```ts
Effect.runSync(isAgentDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isAgentDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L19)

### normalizeAgentModel

Normalizes a model for existing synchronous authoring callers.

**Throws**

The original invalid selector error.

**Example**

```ts
const model = normalizeAgentModel("openai:gpt");
```

**Signature**

```ts
declare const normalizeAgentModel: (value: string | undefined) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L104)

### normalizeAgentModelEffect

Normalizes the selector of a string model definition.

**Example**

```ts
Effect.runSync(normalizeAgentModelEffect("openai:gpt"));
```

**Signature**

```ts
declare const normalizeAgentModelEffect: (
  value: string | undefined,
) => Effect.Effect<string | undefined, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent-validation.ts#L88)

## `define-agent.ts`

Builds plain agent descriptors without loading an execution SDK.
The compiler selects native execution when an application actually declares agents.

### defineAgent

Defines an SDK-independent agent using validated schemas and RELKIT tool references.

**Throws**

The original authoring validation or identity error.

**Example**

```ts
import { defineAgent } from "@relkit/app/agents";
import { z } from "@relkit/app/schema";

const support = defineAgent({
  id: "support",
  input: z.object({ message: z.string() }),
  output: z.object({ answer: z.string() }),
  instructions: "Reply briefly.",
  tools: [],
  limits: { maxSteps: 4, maxToolCalls: 2, timeoutMs: 30_000 },
});
void support;
```

**Signature**

```ts
declare const defineAgent: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Tools extends readonly ToolRefAny[],
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Tools>,
) => AgentDescriptor<
  Id,
  InferInput<InputSchema>,
  InferOutput<OutputSchema>,
  InputSchema,
  OutputSchema,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L82)

Since v0.4.0

#### Backend and frontend example

This SDK-independent factory describes the client contract. The runnable example below uses `defineAgent` from `@relkit/langchain` to supply native execution; see [agent setup](/docs/modules/ai/agents) for the required integration and runtime bindings.

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="templates/default/v1/agent/src/services/hello/agents/assistant.agent.ts"
/** Runs an offline greeting agent with RELKIT/native tools, todo middleware and public state observation. */
import { defineAgent } from "@relkit/langchain";
import { z } from "@relkit/app/schema";
import { FakeToolCallingModel, todoListMiddleware, tool } from "langchain";
import lookup from "@app/services/hello/tools/lookup.tool.js";

export const uppercase = tool(async ({ text }: { readonly text: string }) => text.toUpperCase(), {
  name: "uppercase",
  description: "Uppercase text without leaving the process",
  schema: z.object({ text: z.string() }),
});

export default defineAgent({
  id: "hello.assistant",

  input: z.object({ message: z.string().min(1) }),
  output: z.object({ answer: z.string() }),

  model: new FakeToolCallingModel({
    toolCalls: [
      [
        {
          name: "write_todos",
          args: { todos: [{ content: "Answer the greeting", status: "completed" }] },
          id: "todo-1",
        },
      ],
      [
        {
          name: "relkit_output",
          args: { value: { answer: "Hello from the offline LangChain model." } },
          id: "output-1",
        },
      ],
    ],
  }),
  instructions: "Answer greeting questions with the available tools.",
  tools: [lookup, uppercase],
  middleware: [todoListMiddleware()],
  stateProfile: "default",
  client: {
    public: true,
    state: ["todos"],
    events: { notice: z.object({ message: z.string() }) },
  },
  chat: { input: "message", output: "answer" },
  controls: ["stop"],

  limits: {
    maxSteps: 4,
    maxToolCalls: 4,
    timeoutMs: 10_000,
  },
});
```

**Frontend**

After [frontend setup and pulling the greeting agent's contract](/guides/frontend/connect-react),
render this component under the provider. Supply a stable business `threadId` owned by your
application, such as the ID of the conversation the user opened:

```tsx title="src/Assistant.tsx"
"use client";

/** Sends one greeting to the documented hello.assistant agent and observes its typed answer. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Keeps the application-owned thread identity stable across rendering and observation.
 * @param props - Authorized conversation identity retained by the application.
 * @returns A greeting action, the observed answer, and explicit submission failure. */
export function Assistant({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const assistant = useAgent("hello.assistant");
  const [failure, setFailure] = useState("");

  /** Submits once and preserves uncertain outcomes for explicit recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function sendGreeting() {
    try {
      await assistant.send("Hello, RELKIT!", { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || assistant.status !== "idle" || failure !== ""}
        onClick={sendGreeting}
      >
        Say hello
      </button>
      <p role="status">{assistant.output?.answer ?? assistant.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

This is the same `hello.assistant` declaration: `client.public` exposes it, `chat.input: "message"`
makes `send` accept a string, and `chat.output: "answer"` selects its typed answer. Mounting
`useAgent` does not start a run. The backend owns models, credentials, tools, and authorization.

Reference: [`useAgent`](/docs/api/client#useagent).
Continue with [streaming and controls](/docs/modules/ai/streaming) or
[thread recovery](/docs/modules/ai/threads-recovery).

### "./define-agent.types.js" (namespace export)

Re-exports all named exports from the "./define-agent.types.js" module.

**Signature**

```ts
export * from "./define-agent.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L17)

### AgentChatMapping

**Signature**

```ts
declare const AgentChatMapping: AgentChatMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L18)

### AgentClientPolicy

**Signature**

```ts
declare const AgentClientPolicy: AgentClientPolicy<Guard, StateKey, Events>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L18)

### AgentControl

**Signature**

```ts
declare const AgentControl: AgentControl;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L18)

### assertAgentDescriptor

**Signature**

```ts
declare const assertAgentDescriptor: (value: unknown) => asserts value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L15)

### copyAgentLimits

**Signature**

```ts
declare const copyAgentLimits: (value: unknown) => AgentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L16)

### copyAgentLimitsEffect

**Signature**

```ts
declare const copyAgentLimitsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ maxSteps: number; maxToolCalls: number; timeoutMs: number }>,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L16)

### defineAgentEffect

Validates plain authoring inputs and preserves source identity generation.

**Signature**

```ts
declare const defineAgentEffect: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Tools extends readonly ToolRefAny[],
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Tools>,
) => Effect.Effect<
  AgentDescriptor<
    Id,
    InferInput<InputSchema>,
    InferOutput<OutputSchema>,
    InputSchema,
    OutputSchema,
    Tools
  >,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L24)

### isAgentDescriptor

**Signature**

```ts
declare const isAgentDescriptor: (value: unknown) => value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.ts#L15)

## `define-agent.types.ts`

Defines the SDK-independent agent contract used by generic application authoring.
Native model, middleware, graph and persistence APIs are owned by @relkit/langchain.

### AgentDescriptor (interface)

Plain agent metadata; no execution SDK is evaluated by this declaration.

**Signature**

```ts
export interface AgentDescriptor<
  Id extends string,
  Input,
  Output,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  Tools extends readonly ToolRefAny[] = readonly ToolRefAny[],
>
  extends DescriptorBase<"agent", Id>, AgentRef<Id, InputSchema, OutputSchema> {
  readonly model?: string;
  readonly instructions: AgentInstructions;
  readonly tools: AgentToolReferences<Tools>;
  readonly middleware: readonly [];
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<NonNullable<AgentClientPolicy["authorize"]>, never>;
  readonly chat?: AgentChatMapping;
  readonly controls?: readonly AgentControl[];
  readonly clientContract: AgentClientContractMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L39)

### AgentInstructions (type alias)

**Signature**

```ts
type AgentInstructions = string | PromptTemplate | PromptInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L24)

### AgentLimits (interface)

Limits retained by the selected execution integration.

**Signature**

```ts
export interface AgentLimits {
  readonly maxSteps: number;
  readonly maxToolCalls: number;
  readonly timeoutMs: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L27)

### AgentToolReferences (type alias)

Handler-free tool identities retaining each authored literal reference.

**Signature**

```ts
type AgentToolReferences<Tools extends readonly ToolRefAny[]> = {
  readonly [Index in keyof Tools]: Pick<Tools[Index], "ref">;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L34)

### DefineAgentOptions (interface)

Generic agent inputs; native capabilities use the explicit integration facade.

**Signature**

```ts
export interface DefineAgentOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Tools extends readonly ToolRefAny[],
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly model?: string;
  readonly instructions: AgentInstructions;
  readonly tools: Tools;
  readonly middleware?: readonly [];
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<NonNullable<AgentClientPolicy["authorize"]>, never>;
  readonly chat?: AgentChatMapping;
  readonly controls?: readonly AgentControl[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L61)

### PromptInstructions (interface)

**Signature**

```ts
export interface PromptInstructions {
  readonly kind: "prompt";
  readonly id: string;
  readonly ref: { readonly kind: "prompt"; readonly id: string };
  readonly value: string | readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L17)

### PromptTemplate (interface)

**Signature**

```ts
export interface PromptTemplate {
  readonly template: string;
  readonly variables?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/define-agent.types.ts#L12)

## `generated-function-error.ts`

### GeneratedAgentFunctionFailure (class)

Tagged invalid generated function identity or executor.

**Signature**

```ts
declare class GeneratedAgentFunctionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function-error.ts#L4)

### generatedAgentFunctionFailure

Preserves an invalid generated function error for Effect callers.

**Example**

```ts
generatedAgentFunctionFailure(new TypeError("invalid"));
```

**Signature**

```ts
declare const generatedAgentFunctionFailure: (cause: unknown) => GeneratedAgentFunctionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function-error.ts#L14)

## `generated-function.ts`

### "./generated-function.types.js" (namespace export)

Re-exports all named exports from the "./generated-function.types.js" module.

**Signature**

```ts
export * from "./generated-function.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L11)

### GENERATED_AGENT_FUNCTION_PREFIX

**Signature**

```ts
declare const GENERATED_AGENT_FUNCTION_PREFIX: "relkit.agent.";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L13)

### GENERATED_AGENT_FUNCTION_SUFFIX

**Signature**

```ts
declare const GENERATED_AGENT_FUNCTION_SUFFIX: ".invoke";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L14)

### GeneratedAgentFunctionUnboundError (class)

Raised when a generated identity is registered before the agent runtime binds an executor.

**Signature**

```ts
declare class GeneratedAgentFunctionUnboundError {
  constructor(functionId: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L17)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_GENERATED_FUNCTION_UNBOUND"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L18)

### createGeneratedAgentFunction

Creates a marked handler for existing synchronous callers.

**Throws**

The original invalid identity or executor error.

**Example**

```ts
createGeneratedAgentFunction("support", executor);
```

**Signature**

```ts
declare const createGeneratedAgentFunction: (
  agentId: unknown,
  executor?: GeneratedAgentExecutor,
) => GeneratedAgentFunction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L80)

### createGeneratedAgentFunctionEffect

Creates a marked function handler for a compiler-generated agent identity.

**Example**

```ts
Effect.runSync(createGeneratedAgentFunctionEffect("support", executor));
```

**Signature**

```ts
declare const createGeneratedAgentFunctionEffect: (
  agentId: unknown,
  executor?: GeneratedAgentExecutor | undefined,
) => Effect.Effect<GeneratedAgentFunction, GeneratedAgentFunctionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L64)

### generatedAgentFunctionId

Derives the generated function ID for existing synchronous callers.

**Throws**

The original invalid identity error.

**Example**

```ts
generatedAgentFunctionId("support");
```

**Signature**

```ts
declare const generatedAgentFunctionId: (agentId: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L46)

### generatedAgentFunctionIdEffect

Derives the stable generated function ID without using the source path.

**Example**

```ts
Effect.runSync(generatedAgentFunctionIdEffect("support"));
```

**Signature**

```ts
declare const generatedAgentFunctionIdEffect: (
  agentId: unknown,
) => Effect.Effect<string, GeneratedAgentFunctionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L31)

### isGeneratedAgentFunction

Checks a generated marker for existing synchronous callers.

**Example**

```ts
if (isGeneratedAgentFunction(candidate)) use(candidate);
```

**Signature**

```ts
declare const isGeneratedAgentFunction: (value: unknown) => value is GeneratedAgentFunction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L128)

### isGeneratedAgentFunctionEffect

Checks whether a callable has a valid generated agent marker.

**Example**

```ts
Effect.runSync(isGeneratedAgentFunctionEffect(candidate));
```

**Signature**

```ts
declare const isGeneratedAgentFunctionEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.ts#L118)

## `generated-function.types.ts`

### GeneratedAgentExecutor (type alias)

Optional executor bound when the generated function is registered.

**Signature**

```ts
type GeneratedAgentExecutor = (input: unknown, context: unknown) => MaybePromise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.types.ts#L12)

### GeneratedAgentFunction (type alias)

Callable handler with a compiler-visible agent identity marker.

**Signature**

```ts
type GeneratedAgentFunction = ((...arguments_: readonly unknown[]) => MaybePromise<unknown>) &
  GeneratedAgentFunctionMarker;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.types.ts#L15)

### GeneratedAgentFunctionMarker (interface)

Serializable identity attached to an agent-generated function.

**Signature**

```ts
export interface GeneratedAgentFunctionMarker {
  readonly generated: true;
  readonly generatedBy: "agent";
  readonly agentId: string;
  readonly functionId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/generated-function.types.ts#L4)

## `index.ts`

Exposes generic agent authoring, client events and state contracts.
Native models, graphs, middleware and execution are selected through @relkit/langchain.

### "./agent-client.js" (namespace export)

Re-exports all named exports from the "./agent-client.js" module.

**Signature**

```ts
export * from "./agent-client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L6)

### "./agent-telemetry.js" (namespace export)

Re-exports all named exports from the "./agent-telemetry.js" module.

**Signature**

```ts
export * from "./agent-telemetry.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L12)

### "./approval.js" (namespace export)

Re-exports all named exports from the "./approval.js" module.

**Signature**

```ts
export * from "./approval.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L8)

### "./client-events.js" (namespace export)

Re-exports all named exports from the "./client-events.js" module.

**Signature**

```ts
export * from "./client-events.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L7)

### "./define-agent.js" (namespace export)

Re-exports all named exports from the "./define-agent.js" module.

**Signature**

```ts
export * from "./define-agent.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L5)

### "./generated-function.js" (namespace export)

Re-exports all named exports from the "./generated-function.js" module.

**Signature**

```ts
export * from "./generated-function.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L9)

### "./model-selection.js" (namespace export)

Re-exports all named exports from the "./model-selection.js" module.

**Signature**

```ts
export * from "./model-selection.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L13)

### "./observability.js" (namespace export)

Re-exports all named exports from the "./observability.js" module.

**Signature**

```ts
export * from "./observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L11)

### "./runtime-contract.types.js" (namespace export)

Re-exports all named exports from the "./runtime-contract.types.js" module.

**Signature**

```ts
export * from "./runtime-contract.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L14)

### "./runtime-events.js" (namespace export)

Re-exports all named exports from the "./runtime-events.js" module.

**Signature**

```ts
export * from "./runtime-events.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L10)

### "./state-control-requests.types.js" (namespace export)

Re-exports all named exports from the "./state-control-requests.types.js" module.

**Signature**

```ts
export * from "./state-control-requests.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L15)

### "./state-provider.types.js" (namespace export)

Re-exports all named exports from the "./state-provider.types.js" module.

**Signature**

```ts
export * from "./state-provider.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L16)

### "./state-receipts.types.js" (namespace export)

Re-exports all named exports from the "./state-receipts.types.js" module.

**Signature**

```ts
export * from "./state-receipts.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L17)

### "./state-thread-requests.types.js" (namespace export)

Re-exports all named exports from the "./state-thread-requests.types.js" module.

**Signature**

```ts
export * from "./state-thread-requests.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L18)

### "./state.types.js" (namespace export)

Re-exports all named exports from the "./state.types.js" module.

**Signature**

```ts
export * from "./state.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L19)

### "./thread-transition.js" (namespace export)

Re-exports all named exports from the "./thread-transition.js" module.

**Signature**

```ts
export * from "./thread-transition.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/index.ts#L20)

## `model-selection-core.ts`

### normalizeModelSelectorValue

Canonicalizes a selector after validating its syntax.

**Throws**

ModelSelectionError for malformed selectors.

**Example**

```ts
normalizeModelSelectorValue("openai:gpt");
```

**Signature**

```ts
declare const normalizeModelSelectorValue: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-core.ts#L14)

### parseModelProviderConfigurationValue

Validates and freezes provider defaults.

**Throws**

ModelSelectionError for missing or malformed settings.

**Example**

```ts
parseModelProviderConfigurationValue(config);
```

**Signature**

```ts
declare const parseModelProviderConfigurationValue: (value: unknown) => ModelProviderConfiguration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-core.ts#L36)

### resolveModelSelectorValue

Selects a provider and model from validated configuration.

**Throws**

ModelSelectionError when a provider or model is unavailable.

**Example**

```ts
resolveModelSelectorValue("openai", config);
```

**Signature**

```ts
declare const resolveModelSelectorValue: (
  selector: unknown,
  configuration: ModelProviderConfiguration,
) => ResolvedModelSelection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-core.ts#L77)

## `model-selection-error.ts`

### ModelSelectionEffectError (class)

Recoverable Effect failure for invalid model selection.

**Signature**

```ts
declare class ModelSelectionEffectError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-error.ts#L19)

### ModelSelectionError (class)

Compatible synchronous error for invalid model selection.

**Example**

```ts
throw new ModelSelectionError("RELKIT_MODEL_SELECTOR_INVALID", "Invalid selector");
```

**Signature**

```ts
declare class ModelSelectionError { constructor(
    readonly code: ModelSelectionErrorCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-error.ts#L7)

### name (property)

**Signature**

```ts
readonly name: "ModelSelectionError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-error.ts#L8)

### modelSelectionEffectError

Captures a selector error for Effect recovery and public compatibility.

**Example**

```ts
modelSelectionEffectError(new ModelSelectionError("RELKIT_MODEL_SELECTOR_INVALID", "Invalid"));
```

**Signature**

```ts
declare const modelSelectionEffectError: (cause: unknown) => ModelSelectionEffectError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection-error.ts#L29)

## `model-selection.ts`

### "./model-selection.types.js" (namespace export)

Re-exports all named exports from the "./model-selection.types.js" module.

**Signature**

```ts
export * from "./model-selection.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L18)

### ModelSelectionEffectError

**Signature**

```ts
declare const ModelSelectionEffectError: typeof ModelSelectionEffectError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L17)

### ModelSelectionError

**Signature**

```ts
declare const ModelSelectionError: typeof ModelSelectionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L17)

### normalizeModelSelector

Normalizes an optional provider or provider:model selector.

**Throws**

ModelSelectionError for an invalid selector.

**Example**

```ts
normalizeModelSelector("openai:gpt");
```

**Signature**

```ts
declare const normalizeModelSelector: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L37)

### normalizeModelSelectorEffect

Normalizes an optional provider or provider:model selector.

**Example**

```ts
Effect.runSync(normalizeModelSelectorEffect("openai:gpt"));
```

**Signature**

```ts
declare const normalizeModelSelectorEffect: (
  value: unknown,
) => Effect.Effect<string | undefined, ModelSelectionEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L25)

### parseModelProviderConfiguration

Parses and validates configured model providers.

**Throws**

ModelSelectionError for missing or invalid settings.

**Example**

```ts
parseModelProviderConfiguration(config);
```

**Signature**

```ts
declare const parseModelProviderConfiguration: (value: unknown) => ModelProviderConfiguration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L61)

### parseModelProviderConfigurationEffect

Parses and validates configured model providers.

**Example**

```ts
Effect.runSync(parseModelProviderConfigurationEffect(config));
```

**Signature**

```ts
declare const parseModelProviderConfigurationEffect: (
  value: unknown,
) => Effect.Effect<ModelProviderConfiguration, ModelSelectionEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L46)

### resolveModelSelector

Resolves a selector against provider defaults.

**Throws**

ModelSelectionError for missing providers or defaults.

**Example**

```ts
resolveModelSelector("openai", config);
```

**Signature**

```ts
declare const resolveModelSelector: (
  selector: unknown,
  configuration: ModelProviderConfiguration,
) => ResolvedModelSelection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L87)

### resolveModelSelectorEffect

Resolves a selector against provider defaults.

**Example**

```ts
Effect.runSync(resolveModelSelectorEffect("openai", config));
```

**Signature**

```ts
declare const resolveModelSelectorEffect: (
  selector: unknown,
  configuration: ModelProviderConfiguration,
) => Effect.Effect<ResolvedModelSelection, ModelSelectionEffectError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.ts#L71)

## `model-selection.types.ts`

Stable error codes for model selector and provider configuration failures.

### ModelProviderConfiguration (interface)

Normalized provider defaults used to resolve a model selector.

**Signature**

```ts
export interface ModelProviderConfiguration {
  readonly defaultProvider: string;
  readonly defaultModel: string;
  readonly providers: Readonly<Record<string, { readonly defaultModel?: string }>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.types.ts#L9)

### ModelSelectionErrorCode (type alias)

Stable error codes for model selector and provider configuration failures.

**Signature**

```ts
type ModelSelectionErrorCode =
  | "RELKIT_MODEL_PROVIDER_CONFIGURATION_INVALID"
  | "RELKIT_MODEL_SELECTOR_INVALID"
  | "RELKIT_MODEL_PROVIDER_UNKNOWN"
  | "RELKIT_MODEL_PROVIDER_DEFAULT_MISSING";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.types.ts#L2)

### ResolvedModelSelection (interface)

Selected provider, model, and combined stable identifier.

**Signature**

```ts
export interface ResolvedModelSelection {
  readonly provider: string;
  readonly model: string;
  readonly id: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/model-selection.types.ts#L16)

## `observability.ts`

### "./observability.types.js" (namespace export)

Re-exports all named exports from the "./observability.types.js" module.

**Signature**

```ts
export * from "./observability.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L15)

### AGENT_OBSERVABILITY_PROTOCOL

**Signature**

```ts
declare const AGENT_OBSERVABILITY_PROTOCOL: "relkit.observability.hooks";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L17)

### AGENT_OBSERVABILITY_VERSION

**Signature**

```ts
declare const AGENT_OBSERVABILITY_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L18)

### AgentCapturePolicy

**Signature**

```ts
declare const AgentCapturePolicy: AgentCapturePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L14)

### AgentCapturePolicyError

**Signature**

```ts
declare const AgentCapturePolicyError: typeof AgentCapturePolicyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L12)

### AgentCaptureRecord

**Signature**

```ts
declare const AgentCaptureRecord: AgentCaptureRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L14)

### AgentSpanCapture

**Signature**

```ts
declare const AgentSpanCapture: AgentSpanCapture;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L14)

### captureAgentContent

**Signature**

```ts
declare const captureAgentContent: (
  value: unknown,
  policy: AgentCapturePolicy,
) => AgentCaptureRecord | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L6)

### captureAgentContentEffect

**Signature**

```ts
declare const captureAgentContentEffect: (
  value: unknown,
  policy: AgentCapturePolicy,
) => Effect.Effect<AgentCaptureRecord | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L7)

### createAgentCapturePolicy

**Signature**

```ts
declare const createAgentCapturePolicy: (
  value: AgentCapturePolicy | undefined,
) => AgentCapturePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L8)

### createAgentCapturePolicyEffect

**Signature**

```ts
declare const createAgentCapturePolicyEffect: (
  value: AgentCapturePolicy | undefined,
) => Effect.Effect<AgentCapturePolicy, AgentCapturePolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L9)

### createAgentSpanCapture

**Signature**

```ts
declare const createAgentSpanCapture: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => AgentSpanCapture | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L10)

### createAgentSpanCaptureEffect

**Signature**

```ts
declare const createAgentSpanCaptureEffect: (
  input: AgentCaptureRecord | undefined,
  output: AgentCaptureRecord | undefined,
) => Effect.Effect<
  Readonly<{ output?: AgentCaptureRecord; input?: AgentCaptureRecord }> | undefined,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L11)

### emitAgentEdge

Emits an observed relationship for existing synchronous tracing callers.

**Example**

```ts
emitAgentEdge(hooks, { relationship: "uses-tool", from: "agent", to: "tool" });
```

**Signature**

```ts
declare const emitAgentEdge: (
  hooks: AgentRuntimeHooks | undefined,
  edge: AgentObservedEdge,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L53)

### emitAgentEdgeEffect

Best-effort emission of an observed relationship.
The sink is intentionally detached because the caller's synchronous tracing path cannot await it.

**Example**

```ts
Effect.runSync(emitAgentEdgeEffect(hooks, edge));
```

**Signature**

```ts
declare const emitAgentEdgeEffect: (
  hooks: AgentRuntimeHooks | undefined,
  edge: AgentObservedEdge,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.ts#L27)

## `observability.types.ts`

### AgentEdgeRelationship (type alias)

Relationships reported by an agent's runtime hooks.

**Example**

```ts
const relationship: AgentEdgeRelationship = "uses-tool";
```

**Signature**

```ts
type AgentEdgeRelationship =
  | "targets-function"
  | "calls-function"
  | "enqueues-job"
  | "publishes-event"
  | "listens-to-event"
  | "uses-bucket"
  | "uses-cache"
  | "invokes-agent"
  | "exposes-as-tool"
  | "uses-tool"
  | "uses-provider-profile";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.types.ts#L7)

### AgentObservabilitySink (interface)

Optional external sink for observed agent relationships.

**Example**

```ts
const sink: AgentObservabilitySink = { emit: (event) => send(event) };
```

**Signature**

```ts
export interface AgentObservabilitySink {
  /** Accepts a public relationship event.
   * @param event - Versioned observed edge.
   * @returns Completion of best-effort sink delivery.
   * @example sink.emit({ protocol: "relkit.observability.hooks", version: 1, type: "edge.observed", edge });
   */
  readonly emit: (event: {
    readonly protocol: typeof AGENT_OBSERVABILITY_PROTOCOL;
    readonly version: typeof AGENT_OBSERVABILITY_VERSION;
    readonly type: "edge.observed";
    readonly edge: AgentObservedEdge;
  }) => MaybePromise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.types.ts#L32)

### AgentObservedEdge (interface)

Directed relationship between two stable descriptors.

**Example**

```ts
const edge: AgentObservedEdge = { relationship: "uses-tool", from: "agent", to: "tool" };
```

**Signature**

```ts
export interface AgentObservedEdge {
  readonly relationship: AgentEdgeRelationship;
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.types.ts#L23)

### AgentRuntimeHooks (interface)

Optional synchronous and asynchronous relationship observers.

**Example**

```ts
const hooks: AgentRuntimeHooks = { onObservedEdge: console.log };
```

**Signature**

```ts
export interface AgentRuntimeHooks {
  /** Receives one immutable edge synchronously.
   * @param edge - Observed relationship.
   * @returns Nothing.
   * @example hooks.onObservedEdge?.(edge);
   */
  readonly onObservedEdge?: (edge: AgentObservedEdge) => void;
  readonly observability?: AgentObservabilitySink;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/observability.types.ts#L49)

## `runtime-contract.types.ts`

Carries SDK-independent conversation, approval and content callbacks between
native execution and transports; callbacks retain the caller's signal ownership.

### AgentApprovalHandler (type alias)

Resolves a pending tool approval for an invocation.

**Signature**

```ts
type AgentApprovalHandler = (
  approval: import("./approval.js").PendingApproval,
) => MaybePromise<ApprovalDecision>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-contract.types.ts#L11)

### AgentContentSink (interface)

Sends agent output and events to the surrounding runtime.

**Signature**

```ts
export interface AgentContentSink {
  readonly emitOutput: (value: unknown, signal: AbortSignal) => MaybePromise<void>;
  readonly finishOutput?: (signal: AbortSignal) => MaybePromise<void>;
  readonly progressSinkForTool?: (tool: {
    readonly toolCallId: string;
    readonly toolId: string;
  }) => import("@relkit/invocation").ProgressSink;
  readonly emitTool?: (
    value: {
      readonly toolCallId: string;
      readonly toolId: string;
      readonly state: import("./state.types.js").ToolPartState;
      readonly value?: unknown;
    },
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitEvent?: (
    value: import("./runtime-events.js").AgentExecutionEvent,
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitMessage?: (
    value: import("@relkit/contracts").BrowserMessage,
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitWaiting?: (
    value: Omit<import("./state.types.js").AgentWaitingState, "revision" | "runId">,
    signal: AbortSignal,
  ) => MaybePromise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-contract.types.ts#L27)

### AgentConversationMessage (interface)

One user or assistant message in a native agent conversation.

**Signature**

```ts
export interface AgentConversationMessage {
  readonly role: "user" | "assistant";
  readonly content: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-contract.types.ts#L21)

### AgentSteeringSource (interface)

Supplies queued steering messages to a running agent.

**Signature**

```ts
export interface AgentSteeringSource {
  readonly drain: () => MaybePromise<readonly string[]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-contract.types.ts#L16)

## `runtime-events.ts`

### AgentExecutionEvent

**Signature**

```ts
declare const AgentExecutionEvent: AgentExecutionEvent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-events.ts#L1)

### AgentExecutionSnapshot

**Signature**

```ts
declare const AgentExecutionSnapshot: AgentExecutionSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/runtime-events.ts#L1)

## `state-control-requests.types.ts`

Shared state contracts live below execution and provider implementations.

### AcceptControlRequest

**Signature**

```ts
declare const AcceptControlRequest: AcceptControlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L4)

### AdmitContinuationRequest

**Signature**

```ts
declare const AdmitContinuationRequest: AdmitContinuationRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L15)

### ClaimControlRequest

**Signature**

```ts
declare const ClaimControlRequest: ClaimControlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L9)

### ContinuationIdentity

**Signature**

```ts
declare const ContinuationIdentity: ContinuationIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L14)

### ControlLimits

**Signature**

```ts
declare const ControlLimits: ControlLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L3)

### ControlPage

**Signature**

```ts
declare const ControlPage: ControlPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L7)

### LookupContinuationReceiptRequest

**Signature**

```ts
declare const LookupContinuationReceiptRequest: LookupContinuationReceiptRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L16)

### LookupControlReceiptRequest

**Signature**

```ts
declare const LookupControlReceiptRequest: LookupControlReceiptRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L5)

### MarkControlEffectStartedRequest

**Signature**

```ts
declare const MarkControlEffectStartedRequest: MarkControlEffectStartedRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L11)

### ReadControlsRequest

**Signature**

```ts
declare const ReadControlsRequest: ReadControlsRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L6)

### RecoverAbandonedControlRequest

**Signature**

```ts
declare const RecoverAbandonedControlRequest: RecoverAbandonedControlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L13)

### RenewControlClaimRequest

**Signature**

```ts
declare const RenewControlClaimRequest: RenewControlClaimRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L10)

### SettleControlRequest

**Signature**

```ts
declare const SettleControlRequest: SettleControlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L12)

### WaitForControlsRequest

**Signature**

```ts
declare const WaitForControlsRequest: WaitForControlsRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-control-requests.types.ts#L8)

## `state-provider.types.ts`

Shared state contracts live below execution and provider implementations.

### AgentStateProvider

**Signature**

```ts
declare const AgentStateProvider: AgentStateProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-provider.types.ts#L2)

## `state-receipts.types.ts`

Shared state contracts live below execution and provider implementations.

### AcceptRunReceipt

**Signature**

```ts
declare const AcceptRunReceipt: AcceptRunReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L4)

### CompletionReceipt

**Signature**

```ts
declare const CompletionReceipt: CompletionReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L6)

### ContinuationReceipt

**Signature**

```ts
declare const ContinuationReceipt: ContinuationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L10)

### ContinuationReceiptLookup

**Signature**

```ts
declare const ContinuationReceiptLookup: ContinuationReceiptLookup;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L13)

### ControlReceipt

**Signature**

```ts
declare const ControlReceipt: ControlReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L9)

### ControlReceiptLookup

**Signature**

```ts
declare const ControlReceiptLookup: ControlReceiptLookup;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L12)

### CreateThreadReceipt

**Signature**

```ts
declare const CreateThreadReceipt: CreateThreadReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L3)

### InterruptionReceipt

**Signature**

```ts
declare const InterruptionReceipt: InterruptionReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L7)

### JournalReceipt

**Signature**

```ts
declare const JournalReceipt: JournalReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L5)

### RunReceiptLookup

**Signature**

```ts
declare const RunReceiptLookup: RunReceiptLookup;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L11)

### SuspensionReceipt

**Signature**

```ts
declare const SuspensionReceipt: SuspensionReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-receipts.types.ts#L8)

## `state-thread-requests.types.ts`

Shared state contracts live below execution and provider implementations.

### AcceptRunRequest

**Signature**

```ts
declare const AcceptRunRequest: AcceptRunRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L10)

### AgentStateLimits

**Signature**

```ts
declare const AgentStateLimits: AgentStateLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L3)

### AppendJournalRequest

**Signature**

```ts
declare const AppendJournalRequest: AppendJournalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L17)

### ClaimRunRequest

**Signature**

```ts
declare const ClaimRunRequest: ClaimRunRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L15)

### CompleteRunRequest

**Signature**

```ts
declare const CompleteRunRequest: CompleteRunRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L18)

### CreateThreadRequest

**Signature**

```ts
declare const CreateThreadRequest: CreateThreadRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L4)

### InterruptOwnedRunRequest

**Signature**

```ts
declare const InterruptOwnedRunRequest: InterruptOwnedRunRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L20)

### JournalPage

**Signature**

```ts
declare const JournalPage: JournalPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L13)

### ListThreadsRequest

**Signature**

```ts
declare const ListThreadsRequest: ListThreadsRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L6)

### LoadThreadRequest

**Signature**

```ts
declare const LoadThreadRequest: LoadThreadRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L5)

### LookupRunReceiptRequest

**Signature**

```ts
declare const LookupRunReceiptRequest: LookupRunReceiptRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L11)

### ReadJournalRequest

**Signature**

```ts
declare const ReadJournalRequest: ReadJournalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L12)

### ReadSnapshotHistoryRequest

**Signature**

```ts
declare const ReadSnapshotHistoryRequest: ReadSnapshotHistoryRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L8)

### RenewRunClaimRequest

**Signature**

```ts
declare const RenewRunClaimRequest: RenewRunClaimRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L16)

### SnapshotHistoryPage

**Signature**

```ts
declare const SnapshotHistoryPage: SnapshotHistoryPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L9)

### SuspendRunRequest

**Signature**

```ts
declare const SuspendRunRequest: SuspendRunRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L19)

### ThreadList

**Signature**

```ts
declare const ThreadList: ThreadList;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L7)

### WaitForJournalRequest

**Signature**

```ts
declare const WaitForJournalRequest: WaitForJournalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state-thread-requests.types.ts#L14)

## `state.types.ts`

### AgentObservation

**Signature**

```ts
declare const AgentObservation: AgentObservation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L2)

### AgentProgressScope

**Signature**

```ts
declare const AgentProgressScope: AgentProgressScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L3)

### AgentRequestScope

**Signature**

```ts
declare const AgentRequestScope: AgentRequestScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L4)

### AgentWaitingRequest

**Signature**

```ts
declare const AgentWaitingRequest: AgentWaitingRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L5)

### AgentWaitingState

**Signature**

```ts
declare const AgentWaitingState: AgentWaitingState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L6)

### BrowserMessage

**Signature**

```ts
declare const BrowserMessage: BrowserMessage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L7)

### BrowserMessagePart

**Signature**

```ts
declare const BrowserMessagePart: BrowserMessagePart;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L8)

### ControlClaim

**Signature**

```ts
declare const ControlClaim: ControlClaim;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L9)

### ControlEffectOutcome

**Signature**

```ts
declare const ControlEffectOutcome: ControlEffectOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L10)

### ControlRecord

**Signature**

```ts
declare const ControlRecord: ControlRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L11)

### ControlStatus

**Signature**

```ts
declare const ControlStatus: ControlStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L12)

### ExecutionClaim

**Signature**

```ts
declare const ExecutionClaim: ExecutionClaim;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L13)

### JournalCheckpoint

**Signature**

```ts
declare const JournalCheckpoint: JournalCheckpoint;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L14)

### JournalRecord

**Signature**

```ts
declare const JournalRecord: JournalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L15)

### RunOwner

**Signature**

```ts
declare const RunOwner: RunOwner;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L16)

### RunStatus

**Signature**

```ts
declare const RunStatus: RunStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L17)

### StoredApproval

**Signature**

```ts
declare const StoredApproval: StoredApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L18)

### StoredRun

**Signature**

```ts
declare const StoredRun: StoredRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L19)

### StoredRunRouting

**Signature**

```ts
declare const StoredRunRouting: StoredRunRouting;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L20)

### StoredThread

**Signature**

```ts
declare const StoredThread: StoredThread;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L21)

### ThreadListItem

**Signature**

```ts
declare const ThreadListItem: ThreadListItem;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L22)

### ThreadSnapshot

**Signature**

```ts
declare const ThreadSnapshot: ThreadSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L23)

### ThreadStatus

**Signature**

```ts
declare const ThreadStatus: ThreadStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L24)

### ToolPartState

**Signature**

```ts
declare const ToolPartState: ToolPartState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/state.types.ts#L25)

## `thread-transition.ts`

Exposes the shared durable thread transition table through the existing agent
telemetry boundary; provider implementations call the lower contracts owner.

### AgentTransitionError

**Signature**

```ts
declare const AgentTransitionError: AgentTransitionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.ts#L10)

### ThreadAction

**Signature**

```ts
declare const ThreadAction: ThreadAction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.ts#L10)

### ThreadTransition

**Signature**

```ts
declare const ThreadTransition: ThreadTransition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.ts#L10)

### decideThreadTransition

Decides a thread action for synchronous framework callers.

**Signature**

```ts
declare const decideThreadTransition: (
  status: ThreadStatus,
  action: ThreadAction,
) => ThreadTransition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.ts#L26)

### decideThreadTransitionEffect

Observes a shared thread decision without duplicating its state machine.

**Signature**

```ts
declare const decideThreadTransitionEffect: (
  status: ThreadStatus,
  action: ThreadAction,
) => Effect.Effect<ThreadTransition, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.ts#L17)

## `thread-transition.types.ts`

Shared state contracts live below execution and provider implementations.

### AgentTransitionError

**Signature**

```ts
declare const AgentTransitionError: AgentTransitionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.types.ts#L2)

### ThreadAction

**Signature**

```ts
declare const ThreadAction: ThreadAction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.types.ts#L2)

### ThreadTransition

**Signature**

```ts
declare const ThreadTransition: ThreadTransition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/agents/src/thread-transition.types.ts#L2)

---

# Application API
Source: https://relkit.dev/docs/api/app

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineApp](/docs/api/app#defineapp)

For configuration and examples, read [Application configuration](/docs/learn/concepts/application), [Provider bindings](/docs/modules/integrations), [modules](/docs/modules).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/app` — 1200 exports
- `@relkit/app/schema` — 56 exports
- `@relkit/app/config` — 63 exports
- `@relkit/app/routes` — 91 exports
- `@relkit/app/functions` — 119 exports
- `@relkit/app/events` — 44 exports
- `@relkit/app/realtime` — 75 exports
- `@relkit/app/agents` — 182 exports
- `@relkit/app/jobs` — 414 exports
- `@relkit/app/jobs/legacy` — 33 exports
- `@relkit/app/tasks` — 45 exports
- `@relkit/app/cache` — 50 exports
- `@relkit/app/tools` — 55 exports
- `@relkit/app/buckets` — 48 exports
- `@relkit/app/services` — 45 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                  | Kind  | Import from                                                       | Example                                                                                                                           |
| ---------------------------------------------------------------------------------------------------- | ----- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [AcceptControlRequest](/docs/api/app#acceptcontrolrequest-interface)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AcceptRunReceipt](/docs/api/app#acceptrunreceipt-interface)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AcceptRunRequest](/docs/api/app#acceptrunrequest-interface)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AcquirePresenceLease](/docs/api/realtime#acquirepresencelease-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#acquirepresencelease-type-alias)                                                                 |
| [AdmitContinuationRequest](/docs/api/app#admitcontinuationrequest-type-alias)                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AGENT_OBSERVABILITY_PROTOCOL](/docs/api/agents#agent_observability_protocol)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AGENT_OBSERVABILITY_VERSION](/docs/api/agents#agent_observability_version)                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentApprovalHandler](/docs/api/agents#agentapprovalhandler-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentCapturePolicy](/docs/api/agents#agentcapturepolicy-interface)                                  | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentcapturepolicy-interface)                                                                      |
| [AgentCapturePolicyError](/docs/api/agents#agentcapturepolicyerror-class)                            | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentCaptureRecord](/docs/api/agents#agentcapturerecord-interface)                                  | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentcapturerecord-interface)                                                                      |
| [AgentChatMapping](/docs/api/agents#agentchatmapping-interface)                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentchatmapping-interface)                                                                        |
| [AgentClientEvent](/docs/api/app#agentclientevent-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L174)  |
| [agentClientEvents](/docs/api/agents#agentclientevents-1)                                            | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentclientevents-1)                                                                               |
| [AgentClientEvents](/docs/api/agents#agentclientevents-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentclientevents-type-alias)                                                                      |
| [agentClientEventsEffect](/docs/api/agents#agentclienteventseffect)                                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentclienteventseffect)                                                                           |
| [AgentClientFor](/docs/api/functions#agentclientfor-type-alias)                                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#agentclientfor-type-alias)                                                                      |
| [AgentClientPolicy](/docs/api/agents#agentclientpolicy-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentclientpolicy-type-alias)                                                                      |
| [AgentClientPolicyError](/docs/api/agents#agentclientpolicyerror-class)                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentClients](/docs/api/functions#agentclients-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#agentclients-type-alias)                                                                        |
| [AgentContentSink](/docs/api/agents#agentcontentsink-interface)                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentControl](/docs/api/agents#agentcontrol-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentcontrol-type-alias)                                                                           |
| [AgentConversationMessage](/docs/api/agents#agentconversationmessage-interface)                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentDescriptor](/docs/api/agents#agentdescriptor-interface)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentEdgeRelationship](/docs/api/agents#agentedgerelationship-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentedgerelationship-type-alias)                                                                  |
| [AgentExecutionEvent](/docs/api/app#agentexecutionevent-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L236)  |
| [AgentExecutionSnapshot](/docs/api/app#agentexecutionsnapshot-interface)                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentInstructions](/docs/api/agents#agentinstructions-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentLimits](/docs/api/agents#agentlimits-interface)                                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentObservabilitySink](/docs/api/agents#agentobservabilitysink-interface)                          | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentobservabilitysink-interface)                                                                  |
| [AgentObservation](/docs/api/app#agentobservation-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observer.test.ts#L97)      |
| [AgentObservedEdge](/docs/api/agents#agentobservededge-interface)                                    | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentobservededge-interface)                                                                       |
| [AgentOperation](/docs/api/agents#agentoperation-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentoperation-type-alias)                                                                         |
| [AgentProgressEvent](/docs/api/app#agentprogressevent-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentProgressScope](/docs/api/app#agentprogressscope-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentRef](/docs/api/functions#agentref-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#agentref-interface)                                                                             |
| [AgentRefAny](/docs/api/functions#agentrefany-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#agentrefany-type-alias)                                                                         |
| [AgentRequestScope](/docs/api/app#agentrequestscope-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L57)   |
| [AgentRuntimeHooks](/docs/api/agents#agentruntimehooks-interface)                                    | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentruntimehooks-interface)                                                                       |
| [AgentSpanCapture](/docs/api/agents#agentspancapture-interface)                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agentspancapture-interface)                                                                        |
| [AgentStateLimits](/docs/api/app#agentstatelimits-interface)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L21)   |
| [AgentStateProvider](/docs/api/app#agentstateprovider-interface)                                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L57)           |
| [AgentSteeringSource](/docs/api/agents#agentsteeringsource-interface)                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentTelemetry](/docs/api/agents#agenttelemetry-class)                                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agenttelemetry-class)                                                                              |
| [AgentTelemetryLive](/docs/api/agents#agenttelemetrylive)                                            | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#agenttelemetrylive)                                                                                |
| [AgentTelemetryService](/docs/api/agents#agenttelemetryservice-interface)                            | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentToolEvent](/docs/api/app#agenttoolevent-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentToolReferences](/docs/api/agents#agenttoolreferences-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentTransitionError](/docs/api/app#agenttransitionerror-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentWaitingRequest](/docs/api/app#agentwaitingrequest-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AgentWaitingState](/docs/api/app#agentwaitingstate-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApiDocsConfig](/docs/api/app#apidocsconfig-interface)                                               | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#apidocsconfig-interface)                                                                              |
| [APP_PROVIDER_CAPABILITIES](/docs/api/app#app_provider_capabilities)                                 | Value | `@relkit/app`, `@relkit/app/config`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AppCompatibilityConfig](/docs/api/app#appcompatibilityconfig-interface)                             | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appcompatibilityconfig-interface)                                                                     |
| [AppConstantRunner](/docs/api/app#appconstantrunner-class)                                           | Value | `@relkit/app`                                                     | [API example](/docs/api/app#appconstantrunner-class)                                                                              |
| [AppConstantRunnerLive](/docs/api/app#appconstantrunnerlive)                                         | Value | `@relkit/app`                                                     | [API example](/docs/api/app#appconstantrunnerlive)                                                                                |
| [AppDeploymentConfig](/docs/api/app#appdeploymentconfig-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appdeploymentconfig-type-alias)                                                                       |
| [AppendChannelEvent](/docs/api/realtime#appendchannelevent-interface)                                | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#appendchannelevent-interface)                                                                    |
| [AppendJournalRequest](/docs/api/app#appendjournalrequest-interface)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AppendReceiptLookup](/docs/api/realtime#appendreceiptlookup-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#appendreceiptlookup-type-alias)                                                                  |
| [ApplicationContextOptions](/docs/api/app#applicationcontextoptions-interface)                       | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#applicationcontextoptions-interface)                                                                  |
| [ApplicationContextResolver](/docs/api/app#applicationcontextresolver-interface)                     | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#applicationcontextresolver-interface)                                                                 |
| [ApplicationDescriptor](/docs/api/app#applicationdescriptor-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#applicationdescriptor-type-alias)                                                                     |
| [ApplicationResolveOptions](/docs/api/app#applicationresolveoptions-interface)                       | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#applicationresolveoptions-interface)                                                                  |
| [AppProviderCapability](/docs/api/app#appprovidercapability-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appprovidercapability-type-alias)                                                                     |
| [AppProviderDefaults](/docs/api/app#appproviderdefaults-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appproviderdefaults-type-alias)                                                                       |
| [AppProviderInputs](/docs/api/app#appproviderinputs-interface)                                       | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appproviderinputs-interface)                                                                          |
| [APPROVAL_STATES](/docs/api/agents#approval_states)                                                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalDeniedError](/docs/api/agents#approvaldeniederror-class)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#approvaldeniederror-class)                                                                         |
| [ApprovalEffectError](/docs/api/agents#approvaleffecterror-class)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalMetadata](/docs/api/agents#approvalmetadata-interface)                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalOptions](/docs/api/agents#approvaloptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalPolicy](/docs/api/agents#approvalpolicy-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalRecord](/docs/api/agents#approvalrecord-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalRequiredError](/docs/api/agents#approvalrequirederror-class)                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#approvalrequirederror-class)                                                                       |
| [ApprovalSideEffect](/docs/api/agents#approvalsideeffect-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalState](/docs/api/agents#approvalstate-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ApprovalStateError](/docs/api/agents#approvalstateerror-class)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#approvalstateerror-class)                                                                          |
| [approveApproval](/docs/api/agents#approveapproval)                                                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#approveapproval)                                                                                   |
| [approveApprovalEffect](/docs/api/agents#approveapprovaleffect)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#approveapprovaleffect)                                                                             |
| [ApprovedApproval](/docs/api/agents#approvedapproval-interface)                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [AppTelemetry](/docs/api/app#apptelemetry-class)                                                     | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#apptelemetry-class)                                                                                   |
| [AppTelemetryConfig](/docs/api/app#apptelemetryconfig-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#apptelemetryconfig-type-alias)                                                                        |
| [AppTelemetryLive](/docs/api/app#apptelemetrylive)                                                   | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#apptelemetrylive)                                                                                     |
| [AppValidationFailure](/docs/api/app#appvalidationfailure-class)                                     | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#appvalidationfailure-class)                                                                           |
| [asProvider](/docs/api/buckets#asprovider)                                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#asprovider)                                                                                       |
| [asProviderEffect](/docs/api/buckets#asprovidereffect)                                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#asprovidereffect)                                                                                 |
| [assertAdapterMethods](/docs/api/jobs#assertadaptermethods)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertadaptermethods)                                                                                |
| [assertAdapterMethodsEffect](/docs/api/jobs#assertadaptermethodseffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertadaptermethodseffect)                                                                          |
| [assertAgentDescriptor](/docs/api/agents#assertagentdescriptor)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#assertagentdescriptor)                                                                             |
| [assertApprovalGranted](/docs/api/agents#assertapprovalgranted)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#assertapprovalgranted)                                                                             |
| [assertApprovalGrantedEffect](/docs/api/agents#assertapprovalgrantedeffect)                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#assertapprovalgrantedeffect)                                                                       |
| [assertAuthorizedOperation](/docs/api/jobs#assertauthorizedoperation)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertauthorizedoperation)                                                                           |
| [assertAuthorizedOperationEffect](/docs/api/jobs#assertauthorizedoperationeffect)                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertauthorizedoperationeffect)                                                                     |
| [assertBoundedString](/docs/api/jobs#assertboundedstring)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertboundedstring)                                                                                 |
| [assertBoundedStringEffect](/docs/api/jobs#assertboundedstringeffect)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertboundedstringeffect)                                                                           |
| [assertBucketDescriptor](/docs/api/buckets#assertbucketdescriptor)                                   | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#assertbucketdescriptor)                                                                           |
| [assertBucketDescriptorEffect](/docs/api/buckets#assertbucketdescriptoreffect)                       | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#assertbucketdescriptoreffect)                                                                     |
| [assertCacheDescriptor](/docs/api/cache#assertcachedescriptor)                                       | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#assertcachedescriptor)                                                                              |
| [assertCacheDescriptorEffect](/docs/api/cache#assertcachedescriptoreffect)                           | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#assertcachedescriptoreffect)                                                                        |
| [assertCanonicalScalarKey](/docs/api/jobs#assertcanonicalscalarkey)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertcanonicalscalarkey)                                                                            |
| [assertCanonicalScalarKeyEffect](/docs/api/jobs#assertcanonicalscalarkeyeffect)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertcanonicalscalarkeyeffect)                                                                      |
| [assertEventDescriptor](/docs/api/events#asserteventdescriptor)                                      | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#asserteventdescriptor)                                                                             |
| [assertExclusiveAlias](/docs/api/app#assertexclusivealias)                                           | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#assertexclusivealias)                                                                                 |
| [assertExclusiveAliasEffect](/docs/api/app#assertexclusivealiaseffect)                               | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#assertexclusivealiaseffect)                                                                           |
| [assertFieldName](/docs/api/jobs#assertfieldname)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertfieldname)                                                                                     |
| [assertFieldNameEffect](/docs/api/jobs#assertfieldnameeffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertfieldnameeffect)                                                                               |
| [assertJobDescriptor](/docs/api/jobs#assertjobdescriptor)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobdescriptor)                                                                                 |
| [assertJobDescriptorEffect](/docs/api/jobs#assertjobdescriptoreffect)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobdescriptoreffect)                                                                           |
| [assertJobGrant](/docs/api/jobs#assertjobgrant)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobgrant)                                                                                      |
| [assertJobGrantEffect](/docs/api/jobs#assertjobgranteffect)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobgranteffect)                                                                                |
| [assertJobName](/docs/api/jobs#assertjobname-1)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobname-1)                                                                                     |
| [assertJobNameEffect](/docs/api/jobs#assertjobnameeffect-1)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobnameeffect-1)                                                                               |
| [assertJobsAdapterRuntime](/docs/api/jobs#assertjobsadapterruntime)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobsadapterruntime)                                                                            |
| [assertJobsAdapterRuntimeEffect](/docs/api/jobs#assertjobsadapterruntimeeffect)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobsadapterruntimeeffect)                                                                      |
| [assertJobsCapability](/docs/api/jobs#assertjobscapability-1)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobscapability-1)                                                                              |
| [assertJobsCapabilityEffect](/docs/api/jobs#assertjobscapabilityeffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertjobscapabilityeffect)                                                                          |
| [assertRequestMapping](/docs/api/routes#assertrequestmapping)                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#assertrequestmapping)                                                                              |
| [assertRequestMappingEffect](/docs/api/routes#assertrequestmappingeffect)                            | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#assertrequestmappingeffect)                                                                        |
| [assertResponse](/docs/api/routes#assertresponse)                                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#assertresponse)                                                                                    |
| [assertResponseEffect](/docs/api/routes#assertresponseeffect)                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#assertresponseeffect)                                                                              |
| [assertRfc3339Instant](/docs/api/jobs#assertrfc3339instant-1)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertrfc3339instant-1)                                                                              |
| [assertRfc3339InstantEffect](/docs/api/jobs#assertrfc3339instanteffect-1)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertrfc3339instanteffect-1)                                                                        |
| [assertServiceDescriptor](/docs/api/services#assertservicedescriptor)                                | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertservicedescriptor)                                                                         |
| [assertServiceDescriptorEffect](/docs/api/services#assertservicedescriptoreffect)                    | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertservicedescriptoreffect)                                                                   |
| [assertServiceMemberName](/docs/api/services#assertservicemembername)                                | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertservicemembername)                                                                         |
| [assertServiceMemberNameEffect](/docs/api/services#assertservicemembernameeffect)                    | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertservicemembernameeffect)                                                                   |
| [assertServiceRef](/docs/api/services#assertserviceref)                                              | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertserviceref)                                                                                |
| [assertServiceRefEffect](/docs/api/services#assertservicerefeffect)                                  | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#assertservicerefeffect)                                                                          |
| [assertSupportedJobsServiceOptions](/docs/api/jobs#assertsupportedjobsserviceoptions)                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertsupportedjobsserviceoptions)                                                                   |
| [assertSupportedJobsServiceOptionsEffect](/docs/api/jobs#assertsupportedjobsserviceoptionseffect)    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#assertsupportedjobsserviceoptionseffect)                                                             |
| [assertTaskDescriptor](/docs/api/jobs#asserttaskdescriptor)                                          | Value | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [API example](/docs/api/jobs#asserttaskdescriptor)                                                                                |
| [assertTaskDescriptorEffect](/docs/api/jobs#asserttaskdescriptoreffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#asserttaskdescriptoreffect)                                                                          |
| [assertToolDescriptor](/docs/api/tools#asserttooldescriptor)                                         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#asserttooldescriptor)                                                                               |
| [assertToolDescriptorEffect](/docs/api/tools#asserttooldescriptoreffect)                             | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#asserttooldescriptoreffect)                                                                         |
| [AuthContext](/docs/api/functions#authcontext-interface)                                             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#authcontext-interface)                                                                          |
| [authorize](/docs/api/jobs#authorize)                                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#authorize)                                                                                           |
| [authorizeJobAccess](/docs/api/jobs#authorizejobaccess)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#authorizejobaccess)                                                                                  |
| [authorizeJobAccessEffect](/docs/api/jobs#authorizejobaccesseffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#authorizejobaccesseffect)                                                                            |
| [bindDescriptorIdentity](/docs/api/functions#binddescriptoridentity)                                 | Value | `@relkit/app`                                                     | [API example](/docs/api/functions#binddescriptoridentity)                                                                         |
| [bindFunctionEvents](/docs/api/events#bindfunctionevents)                                            | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#bindfunctionevents)                                                                                |
| [BindingSource](/docs/api/jobs#bindingsource-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [BindingValueRef](/docs/api/provider#bindingvalueref-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/config`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [BrowserMessage](/docs/api/app#browsermessage-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L23)   |
| [BrowserMessagePart](/docs/api/app#browsermessagepart-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [BucketBridgeOptions](/docs/api/buckets#bucketbridgeoptions-interface)                               | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketbridgeoptions-interface)                                                                    |
| [BucketCapabilities](/docs/api/buckets#bucketcapabilities-interface)                                 | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketcapabilities-interface)                                                                     |
| [BucketCapability](/docs/api/buckets#bucketcapability-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketcapability-type-alias)                                                                      |
| [BucketCapabilityError](/docs/api/buckets#bucketcapabilityerror-class)                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketcapabilityerror-class)                                                                      |
| [BucketClient](/docs/api/buckets#bucketclient-interface)                                             | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/buckets`     | [API example](/docs/api/buckets#bucketclient-interface)                                                                           |
| [BucketClientFor](/docs/api/functions#bucketclientfor-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#bucketclientfor-type-alias)                                                                     |
| [BucketClientOptions](/docs/api/buckets#bucketclientoptions-interface)                               | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketclientoptions-interface)                                                                    |
| [BucketClients](/docs/api/functions#bucketclients-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#bucketclients-type-alias)                                                                       |
| [BucketDependencyError](/docs/api/buckets#bucketdependencyerror-class)                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketdependencyerror-class)                                                                      |
| [BucketDescriptor](/docs/api/buckets#bucketdescriptor-interface)                                     | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketdescriptor-interface)                                                                       |
| [BucketDescriptorAny](/docs/api/buckets#bucketdescriptorany-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketdescriptorany-type-alias)                                                                   |
| [BucketInvocationBridge](/docs/api/buckets#bucketinvocationbridge-interface)                         | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketinvocationbridge-interface)                                                                 |
| [BucketObjectMetadata](/docs/api/buckets#bucketobjectmetadata-interface)                             | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/buckets`     | [API example](/docs/api/buckets#bucketobjectmetadata-interface)                                                                   |
| [BucketObservedEdge](/docs/api/buckets#bucketobservededge-interface)                                 | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketobservededge-interface)                                                                     |
| [BucketOperation](/docs/api/buckets#bucketoperation-type-alias)                                      | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketoperation-type-alias)                                                                       |
| [BucketOperationCancelledError](/docs/api/buckets#bucketoperationcancellederror-class)               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketoperationcancellederror-class)                                                              |
| [BucketOperationContext](/docs/api/buckets#bucketoperationcontext-interface)                         | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketoperationcontext-interface)                                                                 |
| [BucketOperationObservation](/docs/api/buckets#bucketoperationobservation-interface)                 | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketoperationobservation-interface)                                                             |
| [BucketOperationOutcome](/docs/api/buckets#bucketoperationoutcome-type-alias)                        | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [Module example](/docs/learn/concepts/application)                                                                                |
| [BucketOperationTimeoutError](/docs/api/buckets#bucketoperationtimeouterror-class)                   | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketoperationtimeouterror-class)                                                                |
| [BucketProvider](/docs/api/buckets#bucketprovider-interface)                                         | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketprovider-interface)                                                                         |
| [BucketProviderError](/docs/api/buckets#bucketprovidererror-class)                                   | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketprovidererror-class)                                                                        |
| [BucketProviderFailureError](/docs/api/buckets#bucketproviderfailureerror-class)                     | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketproviderfailureerror-class)                                                                 |
| [BucketPutOptions](/docs/api/buckets#bucketputoptions-interface)                                     | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketputoptions-interface)                                                                       |
| [BucketRef](/docs/api/functions#bucketref-type-alias)                                                | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#bucketref-type-alias)                                                                           |
| [BucketRefAny](/docs/api/functions#bucketrefany-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#bucketrefany-type-alias)                                                                        |
| [BucketRuntime](/docs/api/buckets#bucketruntime-class)                                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketruntime-class)                                                                              |
| [bucketRuntimeLayer](/docs/api/buckets#bucketruntimelayer)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketruntimelayer)                                                                               |
| [BucketTelemetry](/docs/api/buckets#buckettelemetry-class)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#buckettelemetry-class)                                                                            |
| [BucketTelemetryLive](/docs/api/buckets#buckettelemetrylive)                                         | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#buckettelemetrylive)                                                                              |
| [BucketValidationError](/docs/api/buckets#bucketvalidationerror-class)                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketvalidationerror-class)                                                                      |
| [BucketVisibility](/docs/api/buckets#bucketvisibility-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#bucketvisibility-type-alias)                                                                      |
| [buildSchemaEffect](/docs/api/schema#buildschemaeffect)                                              | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#buildschemaeffect)                                                                                 |
| [CacheBridgeOptions](/docs/api/cache#cachebridgeoptions-interface)                                   | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachebridgeoptions-interface)                                                                       |
| [CacheCapabilities](/docs/api/cache#cachecapabilities-interface)                                     | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachecapabilities-interface)                                                                        |
| [CacheCapability](/docs/api/cache#cachecapability-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachecapability-type-alias)                                                                         |
| [CacheCapabilityError](/docs/api/cache#cachecapabilityerror-class)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachecapabilityerror-class)                                                                         |
| [CacheClient](/docs/api/cache#cacheclient-type-alias)                                                | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/cache`       | [API example](/docs/api/cache#cacheclient-type-alias)                                                                             |
| [CacheClientBase](/docs/api/cache#cacheclientbase-interface)                                         | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheclientbase-interface)                                                                          |
| [CacheClientFor](/docs/api/functions#cacheclientfor-type-alias)                                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#cacheclientfor-type-alias)                                                                      |
| [CacheClientOptions](/docs/api/cache#cacheclientoptions-interface)                                   | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheclientoptions-interface)                                                                       |
| [CacheClients](/docs/api/functions#cacheclients-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#cacheclients-type-alias)                                                                        |
| [CacheDependencyError](/docs/api/cache#cachedependencyerror-class)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachedependencyerror-class)                                                                         |
| [CacheDescriptor](/docs/api/cache#cachedescriptor-interface)                                         | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachedescriptor-interface)                                                                          |
| [CacheDescriptorAny](/docs/api/cache#cachedescriptorany-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachedescriptorany-type-alias)                                                                      |
| [CacheDescriptorError](/docs/api/cache#cachedescriptorerror-class)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachedescriptorerror-class)                                                                         |
| [CacheDescriptorPolicy](/docs/api/cache#cachedescriptorpolicy-interface)                             | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachedescriptorpolicy-interface)                                                                    |
| [CacheEffectClient](/docs/api/cache#cacheeffectclient-interface)                                     | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheeffectclient-interface)                                                                        |
| [CacheIncrementUnsupportedError](/docs/api/cache#cacheincrementunsupportederror-class)               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheincrementunsupportederror-class)                                                               |
| [CacheInvocationBridge](/docs/api/cache#cacheinvocationbridge-interface)                             | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheinvocationbridge-interface)                                                                    |
| [CacheNumericClient](/docs/api/cache#cachenumericclient-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachenumericclient-type-alias)                                                                      |
| [CacheObservedEdge](/docs/api/cache#cacheobservededge-interface)                                     | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheobservededge-interface)                                                                        |
| [CacheOperation](/docs/api/cache#cacheoperation-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperation-type-alias)                                                                          |
| [CacheOperationCancelledError](/docs/api/cache#cacheoperationcancellederror-class)                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationcancellederror-class)                                                                 |
| [CacheOperationContext](/docs/api/cache#cacheoperationcontext-interface)                             | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationcontext-interface)                                                                    |
| [CacheOperationError](/docs/api/cache#cacheoperationerror-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationerror-type-alias)                                                                     |
| [CacheOperationObservation](/docs/api/cache#cacheoperationobservation-interface)                     | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationobservation-interface)                                                                |
| [CacheOperationOptions](/docs/api/cache#cacheoperationoptions-interface)                             | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/cache`       | [API example](/docs/api/cache#cacheoperationoptions-interface)                                                                    |
| [CacheOperationOutcome](/docs/api/cache#cacheoperationoutcome-type-alias)                            | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationoutcome-type-alias)                                                                   |
| [CacheOperationTimeoutError](/docs/api/cache#cacheoperationtimeouterror-class)                       | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheoperationtimeouterror-class)                                                                   |
| [CacheProvider](/docs/api/cache#cacheprovider-interface)                                             | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheprovider-interface)                                                                            |
| [CacheProviderError](/docs/api/cache#cacheprovidererror-class)                                       | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheprovidererror-class)                                                                           |
| [CacheProviderFailureError](/docs/api/cache#cacheproviderfailureerror-class)                         | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheproviderfailureerror-class)                                                                    |
| [CacheRef](/docs/api/functions#cacheref-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#cacheref-interface)                                                                             |
| [CacheRefAny](/docs/api/functions#cacherefany-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#cacherefany-type-alias)                                                                         |
| [CacheRuntime](/docs/api/cache#cacheruntime-class)                                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheruntime-class)                                                                                 |
| [cacheRuntimeLayer](/docs/api/cache#cacheruntimelayer)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheruntimelayer)                                                                                  |
| [CacheSchemaValidationError](/docs/api/cache#cacheschemavalidationerror-class)                       | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cacheschemavalidationerror-class)                                                                   |
| [CacheTelemetry](/docs/api/cache#cachetelemetry-class)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachetelemetry-class)                                                                               |
| [CacheTelemetryLive](/docs/api/cache#cachetelemetrylive)                                             | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachetelemetrylive)                                                                                 |
| [CacheTtlPolicyError](/docs/api/cache#cachettlpolicyerror-class)                                     | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachettlpolicyerror-class)                                                                          |
| [CacheValidationError](/docs/api/cache#cachevalidationerror-class)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#cachevalidationerror-class)                                                                         |
| [cancelRun](/docs/api/jobs#cancelrun)                                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#cancelrun)                                                                                           |
| [cancelRunEffect](/docs/api/jobs#cancelruneffect)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#cancelruneffect)                                                                                     |
| [CanonicalTaskSubmissionOptions](/docs/api/jobs#canonicaltasksubmissionoptions-interface)            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [captureAgentContent](/docs/api/agents#captureagentcontent)                                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#captureagentcontent)                                                                               |
| [captureAgentContentEffect](/docs/api/agents#captureagentcontenteffect)                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#captureagentcontenteffect)                                                                         |
| [ChannelCheckpoint](/docs/api/realtime#channelcheckpoint-interface)                                  | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelcheckpoint-interface)                                                                     |
| [ChannelClientPolicy](/docs/api/realtime#channelclientpolicy-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelclientpolicy-type-alias)                                                                  |
| [ChannelDescriptor](/docs/api/realtime#channeldescriptor-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeldescriptor-type-alias)                                                                    |
| [ChannelDescriptorAny](/docs/api/realtime#channeldescriptorany-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeldescriptorany-type-alias)                                                                 |
| [ChannelDescriptorData](/docs/api/realtime#channeldescriptordata-type-alias)                         | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeldescriptordata-type-alias)                                                                |
| [ChannelEventPage](/docs/api/realtime#channeleventpage-interface)                                    | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeleventpage-interface)                                                                      |
| [ChannelEventRecord](/docs/api/realtime#channeleventrecord-interface)                                | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeleventrecord-interface)                                                                    |
| [ChannelGrant](/docs/api/realtime#channelgrant-interface)                                            | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelgrant-interface)                                                                          |
| [ChannelGuard](/docs/api/realtime#channelguard-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelguard-type-alias)                                                                         |
| [ChannelPresence](/docs/api/realtime#channelpresence-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelpresence-type-alias)                                                                      |
| [ChannelReplay](/docs/api/realtime#channelreplay-interface)                                          | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelreplay-interface)                                                                         |
| [ChannelTriggerOptions](/docs/api/realtime#channeltriggeroptions-interface)                          | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channeltriggeroptions-interface)                                                                 |
| [ChannelValidationError](/docs/api/realtime#channelvalidationerror-class)                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#channelvalidationerror-class)                                                                    |
| [ClaimControlRequest](/docs/api/app#claimcontrolrequest-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ClaimRunRequest](/docs/api/app#claimrunrequest-interface)                                           | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [clientPolicyCount](/docs/api/agents#clientpolicycount)                                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [clientPolicyFailures](/docs/api/agents#clientpolicyfailures)                                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [CompleteRunRequest](/docs/api/app#completerunrequest-interface)                                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [CompletionReceipt](/docs/api/app#completionreceipt-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ConfigOperation](/docs/api/config#configoperation-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/config`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/config/tests/effect-telemetry.test.ts#L14)                  |
| [ConfigTelemetry](/docs/api/config#configtelemetry-class)                                            | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#configtelemetry-class)                                                                             |
| [ConfigTelemetryLive](/docs/api/config#configtelemetrylive)                                          | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#configtelemetrylive)                                                                               |
| [ConfigTelemetryService](/docs/api/config#configtelemetryservice-interface)                          | Type  | `@relkit/app`, `@relkit/app/config`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ConfigValidationError](/docs/api/config#configvalidationerror-class)                                | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#configvalidationerror-class)                                                                       |
| [ConstantResolver](/docs/api/app#constantresolver-type-alias)                                        | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#constantresolver-type-alias)                                                                          |
| [ConstantsDescriptor](/docs/api/app#constantsdescriptor-interface)                                   | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#constantsdescriptor-interface)                                                                        |
| [ConstantsShape](/docs/api/app#constantsshape-type-alias)                                            | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#constantsshape-type-alias)                                                                            |
| [ConstantValue](/docs/api/app#constantvalue-type-alias)                                              | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#constantvalue-type-alias)                                                                             |
| [ContextDescriptorFailure](/docs/api/app#contextdescriptorfailure-class)                             | Value | `@relkit/app`                                                     | [API example](/docs/api/app#contextdescriptorfailure-class)                                                                       |
| [ContextDescriptorOptions](/docs/api/app#contextdescriptoroptions-interface)                         | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#contextdescriptoroptions-interface)                                                                   |
| [ContextResolutionFailure](/docs/api/app#contextresolutionfailure-class)                             | Value | `@relkit/app`                                                     | [API example](/docs/api/app#contextresolutionfailure-class)                                                                       |
| [ContextResolverOptions](/docs/api/app#contextresolveroptions-interface)                             | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#contextresolveroptions-interface)                                                                     |
| [ContinuationIdentity](/docs/api/app#continuationidentity-interface)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ContinuationReceipt](/docs/api/app#continuationreceipt-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ContinuationReceiptLookup](/docs/api/app#continuationreceiptlookup-type-alias)                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ContinueMapping](/docs/api/routes#continuemapping-interface)                                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#continuemapping-interface)                                                                         |
| [ControlClaim](/docs/api/app#controlclaim-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlEffectOutcome](/docs/api/app#controleffectoutcome-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlLimits](/docs/api/app#controllimits-interface)                                               | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlPage](/docs/api/app#controlpage-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlReceipt](/docs/api/app#controlreceipt-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlReceiptLookup](/docs/api/app#controlreceiptlookup-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlRecord](/docs/api/app#controlrecord-interface)                                               | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ControlStatus](/docs/api/app#controlstatus-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [copyAgentChat](/docs/api/agents#copyagentchat)                                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentchat)                                                                                     |
| [copyAgentChatEffect](/docs/api/agents#copyagentchateffect)                                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentchateffect)                                                                               |
| [copyAgentClientPolicy](/docs/api/agents#copyagentclientpolicy)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentclientpolicy)                                                                             |
| [copyAgentClientPolicyEffect](/docs/api/agents#copyagentclientpolicyeffect)                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentclientpolicyeffect)                                                                       |
| [copyAgentControls](/docs/api/agents#copyagentcontrols)                                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentcontrols)                                                                                 |
| [copyAgentControlsEffect](/docs/api/agents#copyagentcontrolseffect)                                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentcontrolseffect)                                                                           |
| [copyAgentLimits](/docs/api/agents#copyagentlimits)                                                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentlimits)                                                                                   |
| [copyAgentLimitsEffect](/docs/api/agents#copyagentlimitseffect)                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#copyagentlimitseffect)                                                                             |
| [copyConcurrency](/docs/api/jobs#copyconcurrency)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copyconcurrency)                                                                                     |
| [copyConcurrencyEffect](/docs/api/jobs#copyconcurrencyeffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copyconcurrencyeffect)                                                                               |
| [copyFunctionToolHooks](/docs/api/functions#copyfunctiontoolhooks)                                   | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#copyfunctiontoolhooks)                                                                          |
| [copyFunctionToolHooksEffect](/docs/api/functions#copyfunctiontoolhookseffect)                       | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#copyfunctiontoolhookseffect)                                                                    |
| [copyLogging](/docs/api/jobs#copylogging)                                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copylogging)                                                                                         |
| [copyLoggingEffect](/docs/api/jobs#copyloggingeffect)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copyloggingeffect)                                                                                   |
| [copyResources](/docs/api/jobs#copyresources)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copyresources)                                                                                       |
| [copyResourcesEffect](/docs/api/jobs#copyresourceseffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copyresourceseffect)                                                                                 |
| [copyTaskTags](/docs/api/jobs#copytasktags)                                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copytasktags)                                                                                        |
| [copyTaskTagsEffect](/docs/api/jobs#copytasktagseffect)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copytasktagseffect)                                                                                  |
| [copyTriggerOptions](/docs/api/jobs#copytriggeroptions-1)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#copytriggeroptions-1)                                                                                |
| [CountPresence](/docs/api/realtime#countpresence-interface)                                          | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#countpresence-interface)                                                                         |
| [createAgentCapturePolicy](/docs/api/agents#createagentcapturepolicy)                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createagentcapturepolicy)                                                                          |
| [createAgentCapturePolicyEffect](/docs/api/agents#createagentcapturepolicyeffect)                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createagentcapturepolicyeffect)                                                                    |
| [createAgentSpanCapture](/docs/api/agents#createagentspancapture)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createagentspancapture)                                                                            |
| [createAgentSpanCaptureEffect](/docs/api/agents#createagentspancaptureeffect)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createagentspancaptureeffect)                                                                      |
| [createApplicationContextResolver](/docs/api/app#createapplicationcontextresolver)                   | Value | `@relkit/app`                                                     | [API example](/docs/api/app#createapplicationcontextresolver)                                                                     |
| [createApplicationContextResolverEffect](/docs/api/app#createapplicationcontextresolvereffect)       | Value | `@relkit/app`                                                     | [API example](/docs/api/app#createapplicationcontextresolvereffect)                                                               |
| [createApproval](/docs/api/agents#createapproval)                                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createapproval)                                                                                    |
| [createApprovalEffect](/docs/api/agents#createapprovaleffect)                                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#createapprovaleffect)                                                                              |
| [createBucketClient](/docs/api/buckets#createbucketclient)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#createbucketclient)                                                                               |
| [createBucketClientEffect](/docs/api/buckets#createbucketclienteffect)                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#createbucketclienteffect)                                                                         |
| [createBucketReadUrlEffect](/docs/api/buckets#createbucketreadurleffect)                             | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#createbucketreadurleffect)                                                                        |
| [createBucketWriteUrlEffect](/docs/api/buckets#createbucketwriteurleffect)                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#createbucketwriteurleffect)                                                                       |
| [createCacheClient](/docs/api/cache#createcacheclient)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#createcacheclient)                                                                                  |
| [createCacheClientEffect](/docs/api/cache#createcacheclienteffect)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#createcacheclienteffect)                                                                            |
| [createCursor](/docs/api/jobs#createcursor)                                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createcursor)                                                                                        |
| [createEnvRefEffect](/docs/api/config#createenvrefeffect)                                            | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#createenvrefeffect)                                                                                |
| [createEventClient](/docs/api/events#createeventclient)                                              | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#createeventclient)                                                                                 |
| [createFunctionGraphNode](/docs/api/functions#createfunctiongraphnode)                               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#createfunctiongraphnode)                                                                        |
| [createFunctionGraphNodeEffect](/docs/api/functions#createfunctiongraphnodeeffect)                   | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#createfunctiongraphnodeeffect)                                                                  |
| [createFunctionToolInvoker](/docs/api/functions#createfunctiontoolinvoker)                           | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#createfunctiontoolinvoker)                                                                      |
| [createFunctionToolInvokerEffect](/docs/api/functions#createfunctiontoolinvokereffect)               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#createfunctiontoolinvokereffect)                                                                |
| [createGeneratedAgentFunction](/docs/api/agents#creategeneratedagentfunction)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#creategeneratedagentfunction)                                                                      |
| [createGeneratedAgentFunctionEffect](/docs/api/agents#creategeneratedagentfunctioneffect)            | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#creategeneratedagentfunctioneffect)                                                                |
| [createJobClient](/docs/api/jobs#createjobclient)                                                    | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#createjobclient)                                                                                     |
| [createJobClientEffect](/docs/api/jobs#createjobclienteffect)                                        | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#createjobclienteffect)                                                                               |
| [createJobCursor](/docs/api/jobs#createjobcursor)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobcursor)                                                                                     |
| [createJobCursorEffect](/docs/api/jobs#createjobcursoreffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobcursoreffect)                                                                               |
| [createJobsControls](/docs/api/jobs#createjobscontrols)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobscontrols)                                                                                  |
| [createJobsControlsEffect](/docs/api/jobs#createjobscontrolseffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobscontrolseffect)                                                                            |
| [createJobsRuntime](/docs/api/jobs#createjobsruntime)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobsruntime)                                                                                   |
| [createJobsRuntimeEffect](/docs/api/jobs#createjobsruntimeeffect)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createjobsruntimeeffect)                                                                             |
| [createOperationId](/docs/api/realtime#createoperationid)                                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#createoperationid)                                                                               |
| [createOperationIdEffect](/docs/api/realtime#createoperationideffect)                                | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#createoperationideffect)                                                                         |
| [createProviderRealtimeDispatcher](/docs/api/realtime#createproviderrealtimedispatcher)              | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#createproviderrealtimedispatcher)                                                                |
| [createProviderRealtimeDispatcherEffect](/docs/api/realtime#createproviderrealtimedispatchereffect)  | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#createproviderrealtimedispatchereffect)                                                          |
| [createRunLocator](/docs/api/jobs#createrunlocator)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createrunlocator)                                                                                    |
| [createRunLocatorEffect](/docs/api/jobs#createrunlocatoreffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createrunlocatoreffect)                                                                              |
| [createScheduleControls](/docs/api/jobs#createschedulecontrols)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createschedulecontrols)                                                                              |
| [createScheduleControlsEffect](/docs/api/jobs#createschedulecontrolseffect)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createschedulecontrolseffect)                                                                        |
| [createSubmissionPipeline](/docs/api/jobs#createsubmissionpipeline)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createsubmissionpipeline)                                                                            |
| [createSubmissionPipelineEffect](/docs/api/jobs#createsubmissionpipelineeffect)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createsubmissionpipelineeffect)                                                                      |
| [createTaskProgressEmitter](/docs/api/jobs#createtaskprogressemitter)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createtaskprogressemitter)                                                                           |
| [createTaskProgressEmitterEffect](/docs/api/jobs#createtaskprogressemittereffect)                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createtaskprogressemittereffect)                                                                     |
| [createTaskStreamEmitter](/docs/api/jobs#createtaskstreamemitter)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createtaskstreamemitter)                                                                             |
| [createTaskStreamEmitterEffect](/docs/api/jobs#createtaskstreamemittereffect)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#createtaskstreamemittereffect)                                                                       |
| [CreateThreadReceipt](/docs/api/app#createthreadreceipt-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [CreateThreadRequest](/docs/api/app#createthreadrequest-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [createToolRuntime](/docs/api/tools#createtoolruntime)                                               | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#createtoolruntime)                                                                                  |
| [createToolRuntimeEffect](/docs/api/tools#createtoolruntimeeffect)                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#createtoolruntimeeffect)                                                                            |
| [currentJobsRuntime](/docs/api/jobs#currentjobsruntime)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#currentjobsruntime)                                                                                  |
| [currentJobsRuntimeEffect](/docs/api/jobs#currentjobsruntimeeffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#currentjobsruntimeeffect)                                                                            |
| [currentRealtimeDispatcher](/docs/api/realtime#currentrealtimedispatcher)                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#currentrealtimedispatcher)                                                                       |
| [currentRealtimeDispatcherEffect](/docs/api/realtime#currentrealtimedispatchereffect)                | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#currentrealtimedispatchereffect)                                                                 |
| [decideThreadTransition](/docs/api/agents#decidethreadtransition)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L20) |
| [decideThreadTransitionEffect](/docs/api/agents#decidethreadtransitioneffect)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L45) |
| [DeclaredError](/docs/api/functions#declarederror-class)                                             | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#declarederror-class)                                                                            |
| [DeclaredErrorOf](/docs/api/functions#declarederrorof-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#declarederrorof-type-alias)                                                                     |
| [DeclaredErrorsOf](/docs/api/functions#declarederrorsof-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#declarederrorsof-type-alias)                                                                    |
| [decodeCursor](/docs/api/jobs#decodecursor)                                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#decodecursor)                                                                                        |
| [decodeJobWire](/docs/api/jobs#decodejobwire)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#decodejobwire)                                                                                       |
| [decodeJobWireEffect](/docs/api/jobs#decodejobwireeffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#decodejobwireeffect)                                                                                 |
| [decodeRunLocator](/docs/api/jobs#decoderunlocator)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#decoderunlocator)                                                                                    |
| [defineAgent](/docs/api/agents#defineagent)                                                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#defineagent)                                                                                       |
| [defineAgentEffect](/docs/api/agents#defineagenteffect)                                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [DefineAgentOptions](/docs/api/agents#defineagentoptions-interface)                                  | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [defineApp](/docs/api/app#defineapp)                                                                 | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#defineapp)                                                                                            |
| [defineAppEffect](/docs/api/app#defineappeffect)                                                     | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#defineappeffect)                                                                                      |
| [DefineAppOptions](/docs/api/app#defineappoptions-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#defineappoptions-type-alias)                                                                          |
| [defineBucket](/docs/api/buckets#definebucket)                                                       | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#definebucket)                                                                                     |
| [defineBucketEffect](/docs/api/buckets#definebucketeffect)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#definebucketeffect)                                                                               |
| [DefineBucketOptions](/docs/api/buckets#definebucketoptions-interface)                               | Type  | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#definebucketoptions-interface)                                                                    |
| [defineCache](/docs/api/cache#definecache)                                                           | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#definecache)                                                                                        |
| [defineCacheEffect](/docs/api/cache#definecacheeffect)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#definecacheeffect)                                                                                  |
| [DefineCacheOptions](/docs/api/cache#definecacheoptions-interface)                                   | Type  | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#definecacheoptions-interface)                                                                       |
| [defineChannel](/docs/api/realtime#definechannel)                                                    | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#definechannel)                                                                                   |
| [defineChannelEffect](/docs/api/realtime#definechanneleffect)                                        | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#definechanneleffect)                                                                             |
| [DefineChannelOptions](/docs/api/realtime#definechanneloptions-interface)                            | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#definechanneloptions-interface)                                                                  |
| [defineConstants](/docs/api/app#defineconstants)                                                     | Value | `@relkit/app`                                                     | [API example](/docs/api/app#defineconstants)                                                                                      |
| [defineConstantsEffect](/docs/api/app#defineconstantseffect)                                         | Value | `@relkit/app`                                                     | [API example](/docs/api/app#defineconstantseffect)                                                                                |
| [defineEnv](/docs/api/config#defineenv)                                                              | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#defineenv)                                                                                         |
| [defineEnvEffect](/docs/api/config#defineenveffect)                                                  | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#defineenveffect)                                                                                   |
| [defineError](/docs/api/functions#defineerror)                                                       | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#defineerror)                                                                                    |
| [defineErrorEffect](/docs/api/functions#defineerroreffect)                                           | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#defineerroreffect)                                                                              |
| [DefineErrorOptions](/docs/api/functions#defineerroroptions-interface)                               | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#defineerroroptions-interface)                                                                   |
| [defineEvent](/docs/api/events#defineevent)                                                          | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#defineevent)                                                                                       |
| [defineEventFunction](/docs/api/events#defineeventfunction)                                          | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#defineeventfunction)                                                                               |
| [DefineEventFunctionOptions](/docs/api/events#defineeventfunctionoptions-interface)                  | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#defineeventfunctionoptions-interface)                                                              |
| [DefineEventOptions](/docs/api/events#defineeventoptions-interface)                                  | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#defineeventoptions-interface)                                                                      |
| [defineFunction](/docs/api/functions#definefunction)                                                 | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#definefunction)                                                                                 |
| [defineFunctionEffect](/docs/api/functions#definefunctioneffect)                                     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#definefunctioneffect)                                                                           |
| [DefineFunctionOptions](/docs/api/functions#definefunctionoptions-interface)                         | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#definefunctionoptions-interface)                                                                |
| [defineJob](/docs/api/jobs#definejob)                                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#definejob)                                                                                           |
| [defineJob](/docs/api/jobs#definejob-1)                                                              | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#definejob-1)                                                                                         |
| [defineJobEffect](/docs/api/jobs#definejobeffect)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#definejobeffect)                                                                                     |
| [defineJobEffect](/docs/api/jobs#definejobeffect-1)                                                  | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#definejobeffect-1)                                                                                   |
| [DefineJobOptions](/docs/api/jobs#definejoboptions-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [DefineJobOptions](/docs/api/jobs#definejoboptions-interface)                                        | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [defineMiddleware](/docs/api/routes#definemiddleware)                                                | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definemiddleware)                                                                                  |
| [defineMiddlewareEffect](/docs/api/routes#definemiddlewareeffect)                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definemiddlewareeffect)                                                                            |
| [definePrompt](/docs/api/app#defineprompt)                                                           | Value | `@relkit/app`                                                     | [API example](/docs/api/app#defineprompt)                                                                                         |
| [definePromptEffect](/docs/api/app#defineprompteffect)                                               | Value | `@relkit/app`                                                     | [API example](/docs/api/app#defineprompteffect)                                                                                   |
| [defineRequestTransform](/docs/api/routes#definerequesttransform)                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definerequesttransform)                                                                            |
| [defineRequestTransformEffect](/docs/api/routes#definerequesttransformeffect)                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definerequesttransformeffect)                                                                      |
| [defineRoute](/docs/api/routes#defineroute)                                                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#defineroute)                                                                                       |
| [defineRouteEffect](/docs/api/routes#definerouteeffect)                                              | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definerouteeffect)                                                                                 |
| [defineService](/docs/api/services#defineservice)                                                    | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#defineservice)                                                                                   |
| [DefineService](/docs/api/services#defineservice-interface)                                          | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#defineservice-interface)                                                                         |
| [defineServiceEffect](/docs/api/services#defineserviceeffect)                                        | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#defineserviceeffect)                                                                             |
| [DefineServiceOptions](/docs/api/services#defineserviceoptions-interface)                            | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#defineserviceoptions-interface)                                                                  |
| [defineServiceRoutes](/docs/api/routes#defineserviceroutes)                                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#defineserviceroutes)                                                                               |
| [defineServiceRoutesEffect](/docs/api/routes#defineservicerouteseffect)                              | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#defineservicerouteseffect)                                                                         |
| [defineTask](/docs/api/jobs#definetask)                                                              | Value | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [API example](/docs/api/jobs#definetask)                                                                                          |
| [defineTaskEffect](/docs/api/jobs#definetaskeffect)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#definetaskeffect)                                                                                    |
| [DefineTaskOptions](/docs/api/jobs#definetaskoptions-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [defineTool](/docs/api/tools#definetool)                                                             | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#definetool)                                                                                         |
| [defineToolEffect](/docs/api/tools#definetooleffect)                                                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#definetooleffect)                                                                                   |
| [DefineToolOptions](/docs/api/tools#definetooloptions-interface)                                     | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#definetooloptions-interface)                                                                        |
| [defineTransform](/docs/api/routes#definetransform)                                                  | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definetransform)                                                                                   |
| [defineTransformEffect](/docs/api/routes#definetransformeffect)                                      | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definetransformeffect)                                                                             |
| [DefineTransformOptions](/docs/api/routes#definetransformoptions-interface)                          | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#definetransformoptions-interface)                                                                  |
| [deleteBucketEffect](/docs/api/buckets#deletebucketeffect)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#deletebucketeffect)                                                                               |
| [deleteCacheEffect](/docs/api/cache#deletecacheeffect)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#deletecacheeffect)                                                                                  |
| [DeniedApproval](/docs/api/agents#deniedapproval-interface)                                          | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [denyApproval](/docs/api/agents#denyapproval)                                                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#denyapproval)                                                                                      |
| [denyApprovalEffect](/docs/api/agents#denyapprovaleffect)                                            | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#denyapprovaleffect)                                                                                |
| [deriveApplicationId](/docs/api/app#deriveapplicationid)                                             | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#deriveapplicationid)                                                                                  |
| [deriveApplicationIdEffect](/docs/api/app#deriveapplicationideffect)                                 | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#deriveapplicationideffect)                                                                            |
| [DescriptorRef](/docs/api/functions#descriptorref-interface)                                         | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#descriptorref-interface)                                                                        |
| [deserializeJobsServiceOptions](/docs/api/jobs#deserializejobsserviceoptions)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#deserializejobsserviceoptions)                                                                       |
| [deserializeJobsServiceOptionsEffect](/docs/api/jobs#deserializejobsserviceoptionseffect)            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#deserializejobsserviceoptionseffect)                                                                 |
| [diagnoseJobMigration](/docs/api/jobs#diagnosejobmigration)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#diagnosejobmigration)                                                                                |
| [diagnoseJobMigrationEffect](/docs/api/jobs#diagnosejobmigrationeffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#diagnosejobmigrationeffect)                                                                          |
| [diagnoseLegacyCompatibility](/docs/api/jobs#diagnoselegacycompatibility)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#diagnoselegacycompatibility)                                                                         |
| [diagnoseLegacyCompatibilityEffect](/docs/api/jobs#diagnoselegacycompatibilityeffect)                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#diagnoselegacycompatibilityeffect)                                                                   |
| [DurationInput](/docs/api/jobs#durationinput-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [durationToMillis](/docs/api/jobs#durationtomillis)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#durationtomillis)                                                                                    |
| [durationToMillisEffect](/docs/api/jobs#durationtomilliseffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#durationtomilliseffect)                                                                              |
| [DurationUnit](/docs/api/jobs#durationunit-type-alias)                                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [DurationValidationError](/docs/api/jobs#durationvalidationerror-class)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#durationvalidationerror-class)                                                                       |
| [EffectJobClient](/docs/api/jobs#effectjobclient-interface)                                          | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [EffectTaskEmitter](/docs/api/jobs#effecttaskemitter-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [emitAgentEdge](/docs/api/agents#emitagentedge)                                                      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#emitagentedge)                                                                                     |
| [emitAgentEdgeEffect](/docs/api/agents#emitagentedgeeffect)                                          | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#emitagentedgeeffect)                                                                               |
| [encodeJobWire](/docs/api/jobs#encodejobwire)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodejobwire)                                                                                       |
| [encodeJobWireEffect](/docs/api/jobs#encodejobwireeffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodejobwireeffect)                                                                                 |
| [encodeRunLocator](/docs/api/jobs#encoderunlocator)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encoderunlocator)                                                                                    |
| [encodeTaskInput](/docs/api/jobs#encodetaskinput)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodetaskinput)                                                                                     |
| [encodeTaskInputEffect](/docs/api/jobs#encodetaskinputeffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodetaskinputeffect)                                                                               |
| [encodeTaskOutput](/docs/api/jobs#encodetaskoutput)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodetaskoutput)                                                                                    |
| [encodeTaskOutputEffect](/docs/api/jobs#encodetaskoutputeffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#encodetaskoutputeffect)                                                                              |
| [env](/docs/api/config#env)                                                                          | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#env)                                                                                               |
| [EnvBuilder](/docs/api/config#envbuilder-interface)                                                  | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envbuilder-interface)                                                                              |
| [EnvBuilderBase](/docs/api/config#envbuilderbase-interface)                                          | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envbuilderbase-interface)                                                                          |
| [EnvBuilderFactory](/docs/api/config#envbuilderfactory-interface)                                    | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envbuilderfactory-interface)                                                                       |
| [EnvDefinition](/docs/api/config#envdefinition-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envdefinition-type-alias)                                                                          |
| [EnvIssue](/docs/api/config#envissue-interface)                                                      | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envissue-interface)                                                                                |
| [EnvMetadata](/docs/api/config#envmetadata-interface)                                                | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envmetadata-interface)                                                                             |
| [EnvMetadataMap](/docs/api/config#envmetadatamap-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envmetadatamap-type-alias)                                                                         |
| [EnvProjection](/docs/api/config#envprojection-interface)                                            | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envprojection-interface)                                                                           |
| [EnvRef](/docs/api/config#envref-interface)                                                          | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envref-interface)                                                                                  |
| [EnvResolutionError](/docs/api/config#envresolutionerror-class)                                      | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envresolutionerror-class)                                                                          |
| [EnvShape](/docs/api/config#envshape-type-alias)                                                     | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envshape-type-alias)                                                                               |
| [EnvSource](/docs/api/config#envsource-type-alias)                                                   | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envsource-type-alias)                                                                              |
| [EnvValueType](/docs/api/config#envvaluetype-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#envvaluetype-type-alias)                                                                           |
| [ErrorDescriptor](/docs/api/functions#errordescriptor-interface)                                     | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#errordescriptor-interface)                                                                      |
| [ErrorDescriptorAny](/docs/api/functions#errordescriptorany-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/functions`                            | [Module example](/docs/learn/concepts/application)                                                                                |
| [ErrorHttpMapping](/docs/api/functions#errorhttpmapping-interface)                                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#errorhttpmapping-interface)                                                                     |
| [ErrorRef](/docs/api/functions#errorref-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#errorref-interface)                                                                             |
| [ErrorRetry](/docs/api/functions#errorretry-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#errorretry-type-alias)                                                                          |
| [ErrorRetryInput](/docs/api/functions#errorretryinput-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#errorretryinput-type-alias)                                                                     |
| [EventAttributeValue](/docs/api/functions#eventattributevalue-type-alias)                            | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/events`      | [API example](/docs/api/functions#eventattributevalue-type-alias)                                                                 |
| [EventClient](/docs/api/events#eventclient-interface)                                                | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventclient-interface)                                                                             |
| [EventClientFor](/docs/api/functions#eventclientfor-type-alias)                                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#eventclientfor-type-alias)                                                                      |
| [EventClientOptions](/docs/api/events#eventclientoptions-interface)                                  | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventclientoptions-interface)                                                                      |
| [EventClients](/docs/api/functions#eventclients-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#eventclients-type-alias)                                                                        |
| [EventDeclaredEdge](/docs/api/events#eventdeclarededge-interface)                                    | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdeclarededge-interface)                                                                       |
| [EventDelivery](/docs/api/events#eventdelivery-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdelivery-type-alias)                                                                          |
| [EventDependencyError](/docs/api/events#eventdependencyerror-class)                                  | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdependencyerror-class)                                                                        |
| [EventDescriptor](/docs/api/events#eventdescriptor-interface)                                        | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdescriptor-interface)                                                                         |
| [EventDescriptorAny](/docs/api/events#eventdescriptorany-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdescriptorany-type-alias)                                                                     |
| [EventDescriptorByName](/docs/api/events#eventdescriptorbyname-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventdescriptorbyname-type-alias)                                                                  |
| [EventEnvelope](/docs/api/events#eventenvelope-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventenvelope-type-alias)                                                                          |
| [EventEnvelopeFor](/docs/api/events#eventenvelopefor-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventenvelopefor-type-alias)                                                                       |
| [EventFunctionContext](/docs/api/events#eventfunctioncontext-interface)                              | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventfunctioncontext-interface)                                                                    |
| [EventFunctionDescriptor](/docs/api/events#eventfunctiondescriptor-interface)                        | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventfunctiondescriptor-interface)                                                                 |
| [EventFunctionDescriptorAny](/docs/api/events#eventfunctiondescriptorany-interface)                  | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventfunctiondescriptorany-interface)                                                              |
| [EventFunctionHandler](/docs/api/events#eventfunctionhandler-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventfunctionhandler-type-alias)                                                                   |
| [EventFunctionTrigger](/docs/api/events#eventfunctiontrigger-interface)                              | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventfunctiontrigger-interface)                                                                    |
| [EventInputByName](/docs/api/events#eventinputbyname-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventinputbyname-type-alias)                                                                       |
| [EventInvocationBridge](/docs/api/events#eventinvocationbridge-interface)                            | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventinvocationbridge-interface)                                                                   |
| [EventInvocationBridgeOptions](/docs/api/events#eventinvocationbridgeoptions-interface)              | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventinvocationbridgeoptions-interface)                                                            |
| [EventName](/docs/api/events#eventname-type-alias)                                                   | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventname-type-alias)                                                                              |
| [EventObservedEdge](/docs/api/events#eventobservededge-interface)                                    | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventobservededge-interface)                                                                       |
| [EventOperationCancelledError](/docs/api/events#eventoperationcancellederror-class)                  | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventoperationcancellederror-class)                                                                |
| [EventOperationContext](/docs/api/events#eventoperationcontext-interface)                            | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventoperationcontext-interface)                                                                   |
| [EventOperationTimeoutError](/docs/api/events#eventoperationtimeouterror-class)                      | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventoperationtimeouterror-class)                                                                  |
| [EventPayloadValidationError](/docs/api/events#eventpayloadvalidationerror-class)                    | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventpayloadvalidationerror-class)                                                                 |
| [EventProfileError](/docs/api/events#eventprofileerror-class)                                        | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventprofileerror-class)                                                                           |
| [EventProvider](/docs/api/events#eventprovider-interface)                                            | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventprovider-interface)                                                                           |
| [EventProviderError](/docs/api/events#eventprovidererror-class)                                      | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventprovidererror-class)                                                                          |
| [EventProviderResult](/docs/api/events#eventproviderresult-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventproviderresult-type-alias)                                                                    |
| [EventPublishOptions](/docs/api/functions#eventpublishoptions-interface)                             | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/events`      | [API example](/docs/api/functions#eventpublishoptions-interface)                                                                  |
| [EventPublishResult](/docs/api/functions#eventpublishresult-interface)                               | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/events`      | [API example](/docs/api/functions#eventpublishresult-interface)                                                                   |
| [EventRef](/docs/api/functions#eventref-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#eventref-interface)                                                                             |
| [EventRefAny](/docs/api/functions#eventrefany-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#eventrefany-type-alias)                                                                         |
| [EventRegistry](/docs/api/events#eventregistry-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventregistry-type-alias)                                                                          |
| [EventRetryPolicy](/docs/api/events#eventretrypolicy-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventretrypolicy-type-alias)                                                                       |
| [EventVersionByName](/docs/api/events#eventversionbyname-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#eventversionbyname-type-alias)                                                                     |
| [ExecutionClaim](/docs/api/app#executionclaim-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L61)           |
| [existsBucketEffect](/docs/api/buckets#existsbucketeffect)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#existsbucketeffect)                                                                               |
| [fail](/docs/api/functions#fail)                                                                     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#fail)                                                                                           |
| [failEffect](/docs/api/functions#faileffect)                                                         | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#faileffect)                                                                                     |
| [FileSchema](/docs/api/schema#fileschema-type-alias)                                                 | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#fileschema-type-alias)                                                                             |
| [FileSchemaOptions](/docs/api/schema#fileschemaoptions-interface)                                    | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#fileschemaoptions-interface)                                                                       |
| [freezeServiceContextValue](/docs/api/services#freezeservicecontextvalue)                            | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#freezeservicecontextvalue)                                                                       |
| [freezeServiceContextValueEffect](/docs/api/services#freezeservicecontextvalueeffect)                | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#freezeservicecontextvalueeffect)                                                                 |
| [freezeServiceDescriptor](/docs/api/services#freezeservicedescriptor)                                | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#freezeservicedescriptor)                                                                         |
| [freezeServiceDescriptorEffect](/docs/api/services#freezeservicedescriptoreffect)                    | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#freezeservicedescriptoreffect)                                                                   |
| [FunctionAsGraphNode](/docs/api/functions#functionasgraphnode-type-alias)                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionasgraphnode-type-alias)                                                                 |
| [functionAttempt](/docs/api/functions#functionattempt)                                               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionattempt)                                                                                |
| [FunctionContext](/docs/api/functions#functioncontext-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functioncontext-type-alias)                                                                     |
| [FunctionDependencies](/docs/api/functions#functiondependencies-interface)                           | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiondependencies-interface)                                                                 |
| [FunctionDescriptor](/docs/api/functions#functiondescriptor-interface)                               | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiondescriptor-interface)                                                                   |
| [FunctionEffectValue](/docs/api/functions#functioneffectvalue-interface)                             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functioneffectvalue-interface)                                                                  |
| [FunctionFailure](/docs/api/functions#functionfailure-interface)                                     | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionfailure-interface)                                                                      |
| [FunctionGraphNodeDescriptor](/docs/api/functions#functiongraphnodedescriptor-interface)             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiongraphnodedescriptor-interface)                                                          |
| [FunctionGraphNodeOptions](/docs/api/functions#functiongraphnodeoptions-interface)                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiongraphnodeoptions-interface)                                                             |
| [FunctionHandlerResult](/docs/api/functions#functionhandlerresult-type-alias)                        | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionhandlerresult-type-alias)                                                               |
| [FunctionHandlerValidation](/docs/api/functions#functionhandlervalidation-type-alias)                | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionhandlervalidation-type-alias)                                                           |
| [FunctionOperation](/docs/api/functions#functionoperation-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionoperation-type-alias)                                                                   |
| [FunctionOperationError](/docs/api/functions#functionoperationerror-class)                           | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionoperationerror-class)                                                                   |
| [FunctionRef](/docs/api/functions#functionref-interface)                                             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionref-interface)                                                                          |
| [FunctionRefAny](/docs/api/functions#functionrefany-type-alias)                                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functionrefany-type-alias)                                                                      |
| [FunctionRouteDescriptor](/docs/api/routes#functionroutedescriptor-interface)                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#functionroutedescriptor-interface)                                                                 |
| [FunctionRouteOptions](/docs/api/routes#functionrouteoptions-interface)                              | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#functionrouteoptions-interface)                                                                    |
| [FunctionTelemetry](/docs/api/functions#functiontelemetry-class)                                     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontelemetry-class)                                                                        |
| [FunctionTelemetryLive](/docs/api/functions#functiontelemetrylive)                                   | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontelemetrylive)                                                                          |
| [FunctionTelemetryService](/docs/api/functions#functiontelemetryservice-interface)                   | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontelemetryservice-interface)                                                             |
| [FunctionToolApproval](/docs/api/functions#functiontoolapproval-type-alias)                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapproval-type-alias)                                                                |
| [FunctionToolApprovalDecision](/docs/api/functions#functiontoolapprovaldecision-type-alias)          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovaldecision-type-alias)                                                        |
| [FunctionToolApprovalDeniedError](/docs/api/functions#functiontoolapprovaldeniederror-class)         | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovaldeniederror-class)                                                          |
| [FunctionToolApprovalDeniedFailure](/docs/api/functions#functiontoolapprovaldeniedfailure-class)     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovaldeniedfailure-class)                                                        |
| [FunctionToolApprovalRequest](/docs/api/functions#functiontoolapprovalrequest-interface)             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovalrequest-interface)                                                          |
| [FunctionToolApprovalRequiredError](/docs/api/functions#functiontoolapprovalrequirederror-class)     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovalrequirederror-class)                                                        |
| [FunctionToolApprovalRequiredFailure](/docs/api/functions#functiontoolapprovalrequiredfailure-class) | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovalrequiredfailure-class)                                                      |
| [FunctionToolApprovalResolver](/docs/api/functions#functiontoolapprovalresolver-type-alias)          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolapprovalresolver-type-alias)                                                        |
| [FunctionToolArgumentFailure](/docs/api/functions#functiontoolargumentfailure-class)                 | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolargumentfailure-class)                                                              |
| [FunctionToolArgumentValidationError](/docs/api/functions#functiontoolargumentvalidationerror-class) | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolargumentvalidationerror-class)                                                      |
| [FunctionToolCancelledFailure](/docs/api/functions#functiontoolcancelledfailure-class)               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolcancelledfailure-class)                                                             |
| [FunctionToolContext](/docs/api/functions#functiontoolcontext-type-alias)                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolcontext-type-alias)                                                                 |
| [FunctionToolDescriptor](/docs/api/functions#functiontooldescriptor-interface)                       | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontooldescriptor-interface)                                                               |
| [FunctionToolHook](/docs/api/functions#functiontoolhook-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolhook-type-alias)                                                                    |
| [FunctionToolInvokeOptions](/docs/api/functions#functiontoolinvokeoptions-interface)                 | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolinvokeoptions-interface)                                                            |
| [FunctionToolMetadata](/docs/api/functions#functiontoolmetadata-interface)                           | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolmetadata-interface)                                                                 |
| [FunctionToolOperationCancelledError](/docs/api/functions#functiontooloperationcancellederror-class) | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontooloperationcancellederror-class)                                                      |
| [FunctionToolOptions](/docs/api/functions#functiontooloptions-interface)                             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontooloptions-interface)                                                                  |
| [FunctionToolSideEffect](/docs/api/functions#functiontoolsideeffect-type-alias)                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontoolsideeffect-type-alias)                                                              |
| [FunctionToolTarget](/docs/api/functions#functiontooltarget-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontooltarget-type-alias)                                                                  |
| [functionTry](/docs/api/functions#functiontry)                                                       | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#functiontry)                                                                                    |
| [GENERATED_AGENT_FUNCTION_PREFIX](/docs/api/agents#generated_agent_function_prefix)                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [GENERATED_AGENT_FUNCTION_SUFFIX](/docs/api/agents#generated_agent_function_suffix)                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [GeneratedAgentExecutor](/docs/api/agents#generatedagentexecutor-type-alias)                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [GeneratedAgentFunction](/docs/api/agents#generatedagentfunction-type-alias)                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [generatedAgentFunctionId](/docs/api/agents#generatedagentfunctionid)                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#generatedagentfunctionid)                                                                          |
| [generatedAgentFunctionIdEffect](/docs/api/agents#generatedagentfunctionideffect)                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#generatedagentfunctionideffect)                                                                    |
| [GeneratedAgentFunctionMarker](/docs/api/agents#generatedagentfunctionmarker-interface)              | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [GeneratedAgentFunctionUnboundError](/docs/api/agents#generatedagentfunctionunbounderror-class)      | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [getBucketEffect](/docs/api/buckets#getbucketeffect)                                                 | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#getbucketeffect)                                                                                  |
| [getCacheEffect](/docs/api/cache#getcacheeffect)                                                     | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#getcacheeffect)                                                                                     |
| [getChannelPresenceEffect](/docs/api/realtime#getchannelpresenceeffect)                              | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#getchannelpresenceeffect)                                                                        |
| [getJsonSchema](/docs/api/schema#getjsonschema-1)                                                    | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#getjsonschema-1)                                                                                   |
| [getJsonSchemaEffect](/docs/api/schema#getjsonschemaeffect-1)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#getjsonschemaeffect-1)                                                                             |
| [getOrSetCacheEffect](/docs/api/cache#getorsetcacheeffect)                                           | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#getorsetcacheeffect)                                                                                |
| [getRun](/docs/api/jobs#getrun)                                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#getrun)                                                                                              |
| [getRunEffect](/docs/api/jobs#getruneffect)                                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#getruneffect)                                                                                        |
| [getScheduleEffect](/docs/api/jobs#getscheduleeffect)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#getscheduleeffect)                                                                                   |
| [getSchemaMetadata](/docs/api/schema#getschemametadata-1)                                            | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#getschemametadata-1)                                                                               |
| [getSchemaMetadataEffect](/docs/api/schema#getschemametadataeffect-1)                                | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#getschemametadataeffect-1)                                                                         |
| [hasCacheEffect](/docs/api/cache#hascacheeffect)                                                     | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#hascacheeffect)                                                                                     |
| [headBucketEffect](/docs/api/buckets#headbucketeffect)                                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#headbucketeffect)                                                                                 |
| [http](/docs/api/routes#http)                                                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#http)                                                                                              |
| [HttpBodyMapping](/docs/api/routes#httpbodymapping-interface)                                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpbodymapping-interface)                                                                         |
| [HttpConstantMapping](/docs/api/routes#httpconstantmapping-interface)                                | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpconstantmapping-interface)                                                                     |
| [HttpCookieMapping](/docs/api/routes#httpcookiemapping-interface)                                    | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpcookiemapping-interface)                                                                       |
| [HttpDefaultMapping](/docs/api/routes#httpdefaultmapping-interface)                                  | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpdefaultmapping-interface)                                                                      |
| [HttpDsl](/docs/api/routes#httpdsl-interface)                                                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpdsl-interface)                                                                                 |
| [httpEffects](/docs/api/routes#httpeffects)                                                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpeffects)                                                                                       |
| [HttpHeaderMapping](/docs/api/routes#httpheadermapping-interface)                                    | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpheadermapping-interface)                                                                       |
| [HttpInputMapping](/docs/api/routes#httpinputmapping-interface)                                      | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpinputmapping-interface)                                                                        |
| [HttpMapping](/docs/api/routes#httpmapping-interface)                                                | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmapping-interface)                                                                             |
| [HttpMappingNode](/docs/api/routes#httpmappingnode-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmappingnode-type-alias)                                                                        |
| [HttpMappingOutput](/docs/api/routes#httpmappingoutput-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmappingoutput-type-alias)                                                                      |
| [HttpMappingShape](/docs/api/routes#httpmappingshape-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmappingshape-type-alias)                                                                       |
| [HttpMethod](/docs/api/routes#httpmethod-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmethod-type-alias)                                                                             |
| [HttpMultipartAllMapping](/docs/api/routes#httpmultipartallmapping-interface)                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmultipartallmapping-interface)                                                                 |
| [HttpMultipartMapping](/docs/api/routes#httpmultipartmapping-interface)                              | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpmultipartmapping-interface)                                                                    |
| [HttpNestedMapping](/docs/api/routes#httpnestedmapping-interface)                                    | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpnestedmapping-interface)                                                                       |
| [HttpOptionalMapping](/docs/api/routes#httpoptionalmapping-interface)                                | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpoptionalmapping-interface)                                                                     |
| [HttpPathMapping](/docs/api/routes#httppathmapping-interface)                                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httppathmapping-interface)                                                                         |
| [HttpPathSegmentsMapping](/docs/api/routes#httppathsegmentsmapping-interface)                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httppathsegmentsmapping-interface)                                                                 |
| [HttpQueryMapping](/docs/api/routes#httpquerymapping-interface)                                      | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpquerymapping-interface)                                                                        |
| [HttpRateLimitKey](/docs/api/routes#httpratelimitkey-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpratelimitkey-type-alias)                                                                       |
| [HttpRequestContentType](/docs/api/routes#httprequestcontenttype-type-alias)                         | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httprequestcontenttype-type-alias)                                                                 |
| [HttpRequestMapping](/docs/api/routes#httprequestmapping-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httprequestmapping-type-alias)                                                                     |
| [HttpResponseMapping](/docs/api/routes#httpresponsemapping-interface)                                | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpresponsemapping-interface)                                                                     |
| [HttpSourceOptions](/docs/api/routes#httpsourceoptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpsourceoptions-interface)                                                                       |
| [HttpTransformDescriptor](/docs/api/routes#httptransformdescriptor-interface)                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httptransformdescriptor-interface)                                                                 |
| [HttpTransformMapping](/docs/api/routes#httptransformmapping-interface)                              | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httptransformmapping-interface)                                                                    |
| [HttpTransformRef](/docs/api/routes#httptransformref-interface)                                      | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httptransformref-interface)                                                                        |
| [HttpWholeBodyMapping](/docs/api/routes#httpwholebodymapping-interface)                              | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#httpwholebodymapping-interface)                                                                    |
| [IdempotencyDefinition](/docs/api/jobs#idempotencydefinition-interface)                              | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [incrementCacheEffect](/docs/api/cache#incrementcacheeffect)                                         | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#incrementcacheeffect)                                                                               |
| [InferEnvValue](/docs/api/config#inferenvvalue-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#inferenvvalue-type-alias)                                                                          |
| [InferEnvValues](/docs/api/config#inferenvvalues-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#inferenvvalues-type-alias)                                                                         |
| [InferInput](/docs/api/schema#inferinput-type-alias-1)                                               | Type  | `@relkit/app/schema`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/authoring-boundaries.ts#L43)                             |
| [InferOutput](/docs/api/schema#inferoutput-type-alias-1)                                             | Type  | `@relkit/app/schema`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/test-native-tool.ts#L11)       |
| [InputOf](/docs/api/jobs#inputof-type-alias)                                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [InspectorConfig](/docs/api/app#inspectorconfig-interface)                                           | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#inspectorconfig-interface)                                                                            |
| [InstantValidationError](/docs/api/jobs#instantvalidationerror-class)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#instantvalidationerror-class)                                                                        |
| [InterruptionReceipt](/docs/api/app#interruptionreceipt-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [InterruptOwnedRunRequest](/docs/api/app#interruptownedrunrequest-interface)                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [InvocationMetadata](/docs/api/functions#invocationmetadata-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#invocationmetadata-type-alias)                                                                  |
| [InvocationSource](/docs/api/functions#invocationsource-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#invocationsource-type-alias)                                                                    |
| [invokeFunctionGraphNodeEffect](/docs/api/functions#invokefunctiongraphnodeeffect)                   | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#invokefunctiongraphnodeeffect)                                                                  |
| [invokeFunctionToolEffect](/docs/api/functions#invokefunctiontooleffect)                             | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#invokefunctiontooleffect)                                                                       |
| [invokeTool](/docs/api/tools#invoketool)                                                             | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#invoketool)                                                                                         |
| [invokeToolEffect](/docs/api/tools#invoketooleffect)                                                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#invoketooleffect)                                                                                   |
| [isAgentDescriptor](/docs/api/agents#isagentdescriptor)                                              | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#isagentdescriptor)                                                                                 |
| [isApprovalRecord](/docs/api/agents#isapprovalrecord)                                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#isapprovalrecord)                                                                                  |
| [isApprovalRecordEffect](/docs/api/agents#isapprovalrecordeffect)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#isapprovalrecordeffect)                                                                            |
| [isBindingValueRef](/docs/api/provider#isbindingvalueref)                                            | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/provider#isbindingvalueref)                                                                               |
| [isBucketDescriptor](/docs/api/buckets#isbucketdescriptor)                                           | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#isbucketdescriptor)                                                                               |
| [isBucketDescriptorEffect](/docs/api/buckets#isbucketdescriptoreffect)                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#isbucketdescriptoreffect)                                                                         |
| [isCacheDescriptor](/docs/api/cache#iscachedescriptor)                                               | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#iscachedescriptor)                                                                                  |
| [isCacheDescriptorEffect](/docs/api/cache#iscachedescriptoreffect)                                   | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#iscachedescriptoreffect)                                                                            |
| [isChannelDescriptor](/docs/api/realtime#ischanneldescriptor)                                        | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#ischanneldescriptor)                                                                             |
| [isChannelDescriptorEffect](/docs/api/realtime#ischanneldescriptoreffect)                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#ischanneldescriptoreffect)                                                                       |
| [isDurationInput](/docs/api/jobs#isdurationinput)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isdurationinput)                                                                                     |
| [isDurationInputEffect](/docs/api/jobs#isdurationinputeffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isdurationinputeffect)                                                                               |
| [isEnvDefinition](/docs/api/app#isenvdefinition)                                                     | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#isenvdefinition)                                                                                      |
| [isEnvDefinitionEffect](/docs/api/app#isenvdefinitioneffect)                                         | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#isenvdefinitioneffect)                                                                                |
| [isEnvRef](/docs/api/config#isenvref)                                                                | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#isenvref)                                                                                          |
| [isEnvRefEffect](/docs/api/config#isenvrefeffect)                                                    | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#isenvrefeffect)                                                                                    |
| [isErrorDescriptor](/docs/api/functions#iserrordescriptor)                                           | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#iserrordescriptor)                                                                              |
| [isErrorDescriptorEffect](/docs/api/functions#iserrordescriptoreffect)                               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#iserrordescriptoreffect)                                                                        |
| [isEventDescriptor](/docs/api/events#iseventdescriptor)                                              | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#iseventdescriptor)                                                                                 |
| [isEventFunctionDescriptor](/docs/api/events#iseventfunctiondescriptor)                              | Value | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#iseventfunctiondescriptor)                                                                         |
| [isFunctionDescriptor](/docs/api/services#isfunctiondescriptor)                                      | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isfunctiondescriptor)                                                                            |
| [isFunctionDescriptorEffect](/docs/api/services#isfunctiondescriptoreffect)                          | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isfunctiondescriptoreffect)                                                                      |
| [isFunctionGraphNode](/docs/api/functions#isfunctiongraphnode)                                       | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#isfunctiongraphnode)                                                                            |
| [isFunctionGraphNodeEffect](/docs/api/functions#isfunctiongraphnodeeffect)                           | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#isfunctiongraphnodeeffect)                                                                      |
| [isGeneratedAgentFunction](/docs/api/agents#isgeneratedagentfunction)                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#isgeneratedagentfunction)                                                                          |
| [isGeneratedAgentFunctionEffect](/docs/api/agents#isgeneratedagentfunctioneffect)                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#isgeneratedagentfunctioneffect)                                                                    |
| [isHttpMapping](/docs/api/routes#ishttpmapping)                                                      | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttpmapping)                                                                                     |
| [isHttpMappingEffect](/docs/api/routes#ishttpmappingeffect)                                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttpmappingeffect)                                                                               |
| [isHttpRequestMapping](/docs/api/routes#ishttprequestmapping)                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttprequestmapping)                                                                              |
| [isHttpRequestMappingEffect](/docs/api/routes#ishttprequestmappingeffect)                            | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttprequestmappingeffect)                                                                        |
| [isHttpResponseMapping](/docs/api/routes#ishttpresponsemapping)                                      | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttpresponsemapping)                                                                             |
| [isHttpResponseMappingEffect](/docs/api/routes#ishttpresponsemappingeffect)                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ishttpresponsemappingeffect)                                                                       |
| [isJobDescriptor](/docs/api/jobs#isjobdescriptor)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobdescriptor)                                                                                     |
| [isJobDescriptorEffect](/docs/api/jobs#isjobdescriptoreffect)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobdescriptoreffect)                                                                               |
| [isJobName](/docs/api/jobs#isjobname-1)                                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobname-1)                                                                                         |
| [isJobNameEffect](/docs/api/jobs#isjobnameeffect-1)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobnameeffect-1)                                                                                   |
| [isJobsAdapterRuntime](/docs/api/jobs#isjobsadapterruntime)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobsadapterruntime)                                                                                |
| [isJobsAdapterRuntimeEffect](/docs/api/jobs#isjobsadapterruntimeeffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isjobsadapterruntimeeffect)                                                                          |
| [isJsonSchemaAvailable](/docs/api/schema#isjsonschemaavailable-1)                                    | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#isjsonschemaavailable-1)                                                                           |
| [isMiddlewareDecision](/docs/api/routes#ismiddlewaredecision)                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewaredecision)                                                                              |
| [isMiddlewareDecisionEffect](/docs/api/routes#ismiddlewaredecisioneffect)                            | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewaredecisioneffect)                                                                        |
| [isMiddlewareDescriptor](/docs/api/routes#ismiddlewaredescriptor)                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewaredescriptor)                                                                            |
| [isMiddlewareDescriptorEffect](/docs/api/routes#ismiddlewaredescriptoreffect)                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewaredescriptoreffect)                                                                      |
| [isMiddlewarePath](/docs/api/routes#ismiddlewarepath)                                                | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewarepath)                                                                                  |
| [isMiddlewarePathEffect](/docs/api/routes#ismiddlewarepatheffect)                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#ismiddlewarepatheffect)                                                                            |
| [isReservedServiceMemberName](/docs/api/services#isreservedservicemembername)                        | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isreservedservicemembername)                                                                     |
| [isReservedServiceMemberNameEffect](/docs/api/services#isreservedservicemembernameeffect)            | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isreservedservicemembernameeffect)                                                               |
| [isRfc3339Instant](/docs/api/jobs#isrfc3339instant-1)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isrfc3339instant-1)                                                                                  |
| [isRfc3339InstantEffect](/docs/api/jobs#isrfc3339instanteffect-1)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isrfc3339instanteffect-1)                                                                            |
| [isSchemaTransformed](/docs/api/schema#isschematransformed-1)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#isschematransformed-1)                                                                             |
| [isSchemaTransformedEffect](/docs/api/schema#isschematransformedeffect-1)                            | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#isschematransformedeffect-1)                                                                       |
| [isServiceDescriptor](/docs/api/services#isservicedescriptor)                                        | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isservicedescriptor)                                                                             |
| [isServiceDescriptorEffect](/docs/api/services#isservicedescriptoreffect)                            | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isservicedescriptoreffect)                                                                       |
| [isServiceRef](/docs/api/services#isserviceref)                                                      | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isserviceref)                                                                                    |
| [isServiceRefEffect](/docs/api/services#isservicerefeffect)                                          | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#isservicerefeffect)                                                                              |
| [isStreamOutputSchema](/docs/api/functions#isstreamoutputschema)                                     | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#isstreamoutputschema)                                                                           |
| [isStreamOutputSchemaEffect](/docs/api/functions#isstreamoutputschemaeffect)                         | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#isstreamoutputschemaeffect)                                                                     |
| [isTaskDescriptor](/docs/api/jobs#istaskdescriptor)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [API example](/docs/api/jobs#istaskdescriptor)                                                                                    |
| [isTaskDescriptorEffect](/docs/api/jobs#istaskdescriptoreffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#istaskdescriptoreffect)                                                                              |
| [isToolDescriptor](/docs/api/tools#istooldescriptor)                                                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#istooldescriptor)                                                                                   |
| [isToolDescriptorEffect](/docs/api/tools#istooldescriptoreffect)                                     | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#istooldescriptoreffect)                                                                             |
| [isToolRef](/docs/api/tools#istoolref)                                                               | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#istoolref)                                                                                          |
| [isToolRefEffect](/docs/api/tools#istoolrefeffect)                                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#istoolrefeffect)                                                                                    |
| [isTransformRef](/docs/api/routes#istransformref)                                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#istransformref)                                                                                    |
| [isTransformRefEffect](/docs/api/routes#istransformrefeffect)                                        | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#istransformrefeffect)                                                                              |
| [isValidJobName](/docs/api/jobs#isvalidjobname-1)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#isvalidjobname-1)                                                                                    |
| [JOB_NAME_MAX_LENGTH](/docs/api/app#job_name_max_length)                                             | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JOB_NAME_PATTERN](/docs/api/jobs#job_name_pattern-1)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#job_name_pattern-1)                                                                                  |
| [JOB_NAME_RESERVED](/docs/api/jobs#job_name_reserved-1)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#job_name_reserved-1)                                                                                 |
| [JOB_PROFILE_DEPRECATED_CODE](/docs/api/jobs#job_profile_deprecated_code)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#job_profile_deprecated_code)                                                                         |
| [JobAccessGrant](/docs/api/app#jobaccessgrant-interface)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobAccessRequest](/docs/api/app#jobaccessrequest-interface)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobAdmission](/docs/api/jobs#jobadmission-interface)                                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobAuthorizationContext](/docs/api/jobs#jobauthorizationcontext-interface)                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobAuthorizationError](/docs/api/jobs#jobauthorizationerror-class)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobauthorizationerror-class)                                                                         |
| [JobAuthorizationFailure](/docs/api/jobs#jobauthorizationfailure-class)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobauthorizationfailure-class)                                                                       |
| [JobBindingErrorCode](/docs/api/jobs#jobbindingerrorcode-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobBindingFailure](/docs/api/jobs#jobbindingfailure-class)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobbindingfailure-class)                                                                             |
| [JobBindingMigration](/docs/api/jobs#jobbindingmigration-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobBindingResolutionError](/docs/api/jobs#jobbindingresolutionerror-class)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobbindingresolutionerror-class)                                                                     |
| [JobCancelOptions](/docs/api/jobs#jobcanceloptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClient](/docs/api/jobs#jobclient-interface)                                                      | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClientAccess](/docs/api/jobs#jobclientaccess-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClientFailure](/docs/api/jobs#jobclientfailure-class)                                            | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#jobclientfailure-class)                                                                              |
| [JobClientField](/docs/api/jobs#jobclientfield-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClientFor](/docs/api/functions#jobclientfor-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#jobclientfor-type-alias)                                                                        |
| [JobClientOperation](/docs/api/app#jobclientoperation-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClientOptions](/docs/api/jobs#jobclientoptions-interface)                                        | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobClients](/docs/api/functions#jobclients-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#jobclients-type-alias)                                                                          |
| [JobControlFailure](/docs/api/jobs#jobcontrolfailure-class)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobcontrolfailure-class)                                                                             |
| [JobControlUnknownError](/docs/api/jobs#jobcontrolunknownerror-class)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobcontrolunknownerror-class)                                                                        |
| [JobCursorBinding](/docs/api/jobs#jobcursorbinding-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobCursorError](/docs/api/jobs#jobcursorerror-class)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobcursorerror-class)                                                                                |
| [JobCursorFailure](/docs/api/jobs#jobcursorfailure-class)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobcursorfailure-class)                                                                              |
| [JobCursorOptions](/docs/api/jobs#jobcursoroptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobDeclaredEdge](/docs/api/jobs#jobdeclarededge-interface)                                          | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobDefinitionFailure](/docs/api/jobs#jobdefinitionfailure-class)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobdefinitionfailure-class)                                                                          |
| [JobDependencyError](/docs/api/jobs#jobdependencyerror-class)                                        | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#jobdependencyerror-class)                                                                            |
| [JobDescriptor](/docs/api/jobs#jobdescriptor-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobDescriptor](/docs/api/jobs#jobdescriptor-interface)                                              | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobDescriptorAny](/docs/api/jobs#jobdescriptorany-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L42)                        |
| [JobDescriptorForThisTask](/docs/api/jobs#jobdescriptorforthistask-type-alias)                       | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobEnqueueOptions](/docs/api/functions#jobenqueueoptions-interface)                                 | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/jobs/legacy` | [API example](/docs/api/functions#jobenqueueoptions-interface)                                                                    |
| [JobEnqueueResult](/docs/api/functions#jobenqueueresult-interface)                                   | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/jobs/legacy` | [API example](/docs/api/functions#jobenqueueresult-interface)                                                                     |
| [JobErrorEnvelope](/docs/api/app#joberrorenvelope-interface)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobIdentityError](/docs/api/jobs#jobidentityerror-class)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobidentityerror-class)                                                                              |
| [JobInputValidationError](/docs/api/jobs#jobinputvalidationerror-class)                              | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#jobinputvalidationerror-class)                                                                       |
| [JobInvocationBridge](/docs/api/jobs#jobinvocationbridge-interface)                                  | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobInvocationBridgeOptions](/docs/api/jobs#jobinvocationbridgeoptions-interface)                    | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobMigrationDiagnostic](/docs/api/jobs#jobmigrationdiagnostic-interface)                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobMigrationSeverity](/docs/api/jobs#jobmigrationseverity-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobMigrationSnapshot](/docs/api/jobs#jobmigrationsnapshot-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobName](/docs/api/jobs#jobname-type-alias)                                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobNameValidationError](/docs/api/jobs#jobnamevalidationerror-class)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobnamevalidationerror-class)                                                                        |
| [JobObservationTimeoutError](/docs/api/jobs#jobobservationtimeouterror-class)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobobservationtimeouterror-class)                                                                    |
| [JobObservedEdge](/docs/api/jobs#jobobservededge-interface)                                          | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobObserveOptions](/docs/api/jobs#jobobserveoptions-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobOperationCancelledError](/docs/api/jobs#joboperationcancellederror-class)                        | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#joboperationcancellederror-class)                                                                    |
| [JobOperationContext](/docs/api/jobs#joboperationcontext-interface)                                  | Type  | `@relkit/app/jobs/legacy`                                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/client.test.ts#L26)                              |
| [JobOperationTimeoutError](/docs/api/jobs#joboperationtimeouterror-class)                            | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#joboperationtimeouterror-class)                                                                      |
| [JobProfileError](/docs/api/jobs#jobprofileerror-class)                                              | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#jobprofileerror-class)                                                                               |
| [JobProvider](/docs/api/jobs#jobprovider-interface)                                                  | Type  | `@relkit/app/jobs/legacy`                                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/client.test.ts#L27)                              |
| [JobProviderError](/docs/api/jobs#jobprovidererror-class)                                            | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#jobprovidererror-class)                                                                              |
| [JobProviderResult](/docs/api/jobs#jobproviderresult-type-alias)                                     | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobReceiptError](/docs/api/jobs#jobreceipterror-class)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobreceipterror-class)                                                                               |
| [JobRef](/docs/api/app#jobref-interface)                                                             | Type  | `@relkit/app`, `@relkit/app/functions`                            | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobRefAny](/docs/api/app#jobrefany-type-alias)                                                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobResultUnavailableError](/docs/api/jobs#jobresultunavailableerror-class)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobresultunavailableerror-class)                                                                     |
| [JobRetryOptions](/docs/api/jobs#jobretryoptions-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobRunResultOptions](/docs/api/jobs#jobrunresultoptions-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobRunStatus](/docs/api/app#jobrunstatus-type-alias)                                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JOBS_ADAPTER_PROTOCOL_VERSION](/docs/api/jobs#jobs_adapter_protocol_version)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobs_adapter_protocol_version)                                                                       |
| [JobsAdapterRuntime](/docs/api/jobs#jobsadapterruntime-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/adapter-effect.test.ts#L32)                      |
| [JobsAdapterValidationError](/docs/api/jobs#jobsadaptervalidationerror-class)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsadaptervalidationerror-class)                                                                    |
| [JobsCapability](/docs/api/jobs#jobscapability-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsCapabilityError](/docs/api/jobs#jobscapabilityerror-class)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobscapabilityerror-class)                                                                           |
| [JobsCapabilityFailure](/docs/api/jobs#jobscapabilityfailure-class)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobscapabilityfailure-class)                                                                         |
| [JobsCapabilityName](/docs/api/jobs#jobscapabilityname-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsCapabilityReport](/docs/api/jobs#jobscapabilityreport-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsCapabilitySupport](/docs/api/jobs#jobscapabilitysupport-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobScheduleClient](/docs/api/jobs#jobscheduleclient-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobScheduleControlFailure](/docs/api/jobs#jobschedulecontrolfailure-class)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobschedulecontrolfailure-class)                                                                     |
| [JobsControls](/docs/api/jobs#jobscontrols-interface)                                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobServiceSelection](/docs/api/jobs#jobserviceselection-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsManifestLike](/docs/api/jobs#jobsmanifestlike-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsOperationOptions](/docs/api/jobs#jobsoperationoptions-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsRuntime](/docs/api/jobs#jobsruntime-interface)                                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/control-result-effect.test.ts#L12)               |
| [JobsRuntimeBinding](/docs/api/jobs#jobsruntimebinding-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/submission-support-effect.test.ts#L37)           |
| [JobsRuntimeCallbackError](/docs/api/jobs#jobsruntimecallbackerror-class)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsruntimecallbackerror-class)                                                                      |
| [JobsRuntimeError](/docs/api/jobs#jobsruntimeerror-class)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsruntimeerror-class)                                                                              |
| [JobsRuntimeOptions](/docs/api/jobs#jobsruntimeoptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsServiceBehavior](/docs/api/jobs#jobsservicebehavior-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsServiceOptionName](/docs/api/jobs#jobsserviceoptionname-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobsServiceOptions](/docs/api/jobs#jobsserviceoptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/service-options-validation.test.ts#L9)           |
| [JobsServiceOptionsError](/docs/api/jobs#jobsserviceoptionserror-class)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsserviceoptionserror-class)                                                                       |
| [JobState](/docs/api/functions#jobstate-type-alias)                                                  | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/jobs/legacy` | [API example](/docs/api/functions#jobstate-type-alias)                                                                            |
| [JobStatus](/docs/api/functions#jobstatus-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/functions`, `@relkit/app/jobs/legacy` | [API example](/docs/api/functions#jobstatus-interface)                                                                            |
| [JobsTelemetry](/docs/api/jobs#jobstelemetry-class)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobstelemetry-class)                                                                                 |
| [JobsTelemetryLive](/docs/api/jobs#jobstelemetrylive-1)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobstelemetrylive-1)                                                                                 |
| [JobSubmissionCancelledError](/docs/api/jobs#jobsubmissioncancellederror-class)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsubmissioncancellederror-class)                                                                   |
| [JobSubmissionError](/docs/api/jobs#jobsubmissionerror-class)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsubmissionerror-class)                                                                            |
| [JobSubmissionPipelineFailure](/docs/api/jobs#jobsubmissionpipelinefailure-class)                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsubmissionpipelinefailure-class)                                                                  |
| [JobSubmissionUnknownError](/docs/api/jobs#jobsubmissionunknownerror-class)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#jobsubmissionunknownerror-class)                                                                     |
| [JobTriggerClients](/docs/api/jobs#jobtriggerclients-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobUnknownOutcome](/docs/api/app#jobunknownoutcome-interface)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JobWireEnvelope](/docs/api/app#jobwireenvelope-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [JournalCheckpoint](/docs/api/app#journalcheckpoint-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L13)   |
| [JournalPage](/docs/api/app#journalpage-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [JournalReceipt](/docs/api/app#journalreceipt-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [JournalRecord](/docs/api/app#journalrecord-interface)                                               | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L100)                    |
| [JSON_SCHEMA_UNAVAILABLE](/docs/api/schema#json_schema_unavailable-1)                                | Value | `@relkit/app/schema`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/schema/tests/schema.test.ts#L50)                            |
| [JsonSchema](/docs/api/schema#jsonschema-type-alias)                                                 | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschema-type-alias)                                                                             |
| [JsonSchemaAvailable](/docs/api/schema#jsonschemaavailable-interface)                                | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemaavailable-interface)                                                                     |
| [JsonSchemaDirection](/docs/api/schema#jsonschemadirection-type-alias)                               | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemadirection-type-alias)                                                                    |
| [JsonSchemaFactory](/docs/api/schema#jsonschemafactory-type-alias)                                   | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemafactory-type-alias)                                                                      |
| [JsonSchemaOptions](/docs/api/schema#jsonschemaoptions-interface)                                    | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemaoptions-interface)                                                                       |
| [JsonSchemaResult](/docs/api/schema#jsonschemaresult-type-alias)                                     | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemaresult-type-alias)                                                                       |
| [JsonSchemaUnavailable](/docs/api/schema#jsonschemaunavailable-interface)                            | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemaunavailable-interface)                                                                   |
| [JsonSchemaUnavailableError](/docs/api/schema#jsonschemaunavailableerror-class)                      | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#jsonschemaunavailableerror-class)                                                                  |
| [JsonValue](/docs/api/config#jsonvalue-type-alias)                                                   | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#jsonvalue-type-alias)                                                                              |
| [JsonWireEnvelope](/docs/api/app#jsonwireenvelope-interface)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [LegacyCompatibilitySnapshot](/docs/api/jobs#legacycompatibilitysnapshot-interface)                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [LegacyJobValidationError](/docs/api/jobs#legacyjobvalidationerror-class)                            | Value | `@relkit/app/jobs/legacy`                                         | [API example](/docs/api/jobs#legacyjobvalidationerror-class)                                                                      |
| [limitsForEffect](/docs/api/realtime#limitsforeffect-1)                                              | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#limitsforeffect-1)                                                                               |
| [listBucketEffect](/docs/api/buckets#listbucketeffect)                                               | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#listbucketeffect)                                                                                 |
| [listRuns](/docs/api/jobs#listruns)                                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#listruns)                                                                                            |
| [listRunsEffect](/docs/api/jobs#listrunseffect)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#listrunseffect)                                                                                      |
| [listSchedulesEffect](/docs/api/jobs#listscheduleseffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#listscheduleseffect)                                                                                 |
| [ListThreadsRequest](/docs/api/app#listthreadsrequest-interface)                                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [LiteralValue](/docs/api/config#literalvalue-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#literalvalue-type-alias)                                                                           |
| [LoadThreadRequest](/docs/api/app#loadthreadrequest-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [LookupAppendReceipt](/docs/api/realtime#lookupappendreceipt-interface)                              | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#lookupappendreceipt-interface)                                                                   |
| [LookupContinuationReceiptRequest](/docs/api/app#lookupcontinuationreceiptrequest-interface)         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [LookupControlReceiptRequest](/docs/api/app#lookupcontrolreceiptrequest-interface)                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [LookupRunReceiptRequest](/docs/api/app#lookuprunreceiptrequest-interface)                           | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [MappingShapeOutput](/docs/api/routes#mappingshapeoutput-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#mappingshapeoutput-type-alias)                                                                     |
| [MarkControlEffectStartedRequest](/docs/api/app#markcontroleffectstartedrequest-interface)           | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [MemberPresence](/docs/api/realtime#memberpresence-interface)                                        | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#memberpresence-interface)                                                                        |
| [MemberPresenceDescriptor](/docs/api/realtime#memberpresencedescriptor-interface)                    | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#memberpresencedescriptor-interface)                                                              |
| [memoryBytes](/docs/api/jobs#memorybytes)                                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#memorybytes)                                                                                         |
| [memoryBytesEffect](/docs/api/jobs#memorybyteseffect)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#memorybyteseffect)                                                                                   |
| [MemoryInput](/docs/api/jobs#memoryinput-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [MiddlewareContext](/docs/api/routes#middlewarecontext-interface)                                    | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#middlewarecontext-interface)                                                                       |
| [MiddlewareDecisionMapping](/docs/api/routes#middlewaredecisionmapping-type-alias)                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#middlewaredecisionmapping-type-alias)                                                              |
| [MiddlewareDescriptor](/docs/api/routes#middlewaredescriptor-interface)                              | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#middlewaredescriptor-interface)                                                                    |
| [MiddlewareHandler](/docs/api/routes#middlewarehandler-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#middlewarehandler-type-alias)                                                                      |
| [ModelProviderConfiguration](/docs/api/agents#modelproviderconfiguration-interface)                  | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ModelSelectionEffectError](/docs/api/agents#modelselectioneffecterror-class)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ModelSelectionError](/docs/api/agents#modelselectionerror-class)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#modelselectionerror-class)                                                                         |
| [ModelSelectionErrorCode](/docs/api/agents#modelselectionerrorcode-type-alias)                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [NamedStreamFrame](/docs/api/app#namedstreamframe-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [namespaceHash](/docs/api/jobs#namespacehash-1)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#namespacehash-1)                                                                                     |
| [namespaceHashEffect](/docs/api/jobs#namespacehasheffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#namespacehasheffect)                                                                                 |
| [NativeCancelRequest](/docs/api/jobs#nativecancelrequest-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeControlReceipt](/docs/api/jobs#nativecontrolreceipt-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeDurableSleep](/docs/api/jobs#nativedurablesleep-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeLocator](/docs/api/jobs#nativelocator-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeObservation](/docs/api/jobs#nativeobservation-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeOwnedScheduleRecord](/docs/api/jobs#nativeownedschedulerecord-interface)                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeProgressWriter](/docs/api/jobs#nativeprogresswriter-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeReceipt](/docs/api/jobs#nativereceipt-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeRetryRequest](/docs/api/jobs#nativeretryrequest-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeRun](/docs/api/jobs#nativerun-type-alias)                                                     | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeRunPage](/docs/api/jobs#nativerunpage-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeRunQuery](/docs/api/jobs#nativerunquery-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [nativeScheduleLayer](/docs/api/jobs#nativeschedulelayer)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#nativeschedulelayer)                                                                                 |
| [NativeScheduleOperations](/docs/api/jobs#nativescheduleoperations-interface)                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-controls-operations.test.ts#L19)        |
| [NativeScheduleService](/docs/api/jobs#nativescheduleservice-class)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#nativescheduleservice-class)                                                                         |
| [NativeStreamFormat](/docs/api/routes#nativestreamformat-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#nativestreamformat-type-alias)                                                                     |
| [NativeStreamWriter](/docs/api/jobs#nativestreamwriter-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeStreamWriters](/docs/api/jobs#nativestreamwriters-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeSubmission](/docs/api/jobs#nativesubmission-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/native-jobs.test.ts#L19)              |
| [NativeTaskWork](/docs/api/jobs#nativetaskwork-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/commerce-layout-task-run.ts#L59)          |
| [NativeTaskWorker](/docs/api/jobs#nativetaskworker-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [NativeWatchRequest](/docs/api/jobs#nativewatchrequest-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [normalizeCompatibility](/docs/api/app#normalizecompatibility)                                       | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#normalizecompatibility)                                                                               |
| [normalizeCompatibilityEffect](/docs/api/app#normalizecompatibilityeffect)                           | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#normalizecompatibilityeffect)                                                                         |
| [NormalizedAppProviderDefaults](/docs/api/app#normalizedappproviderdefaults-type-alias)              | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#normalizedappproviderdefaults-type-alias)                                                             |
| [NormalizedErrorRetry](/docs/api/functions#normalizederrorretry-interface)                           | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#normalizederrorretry-interface)                                                                 |
| [NormalizedTaskRetryPolicy](/docs/api/jobs#normalizedtaskretrypolicy-interface)                      | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L27)                        |
| [normalizeJobName](/docs/api/jobs#normalizejobname-1)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#normalizejobname-1)                                                                                  |
| [normalizeModelSelector](/docs/api/agents#normalizemodelselector)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#normalizemodelselector)                                                                            |
| [normalizeModelSelectorEffect](/docs/api/agents#normalizemodelselectoreffect)                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#normalizemodelselectoreffect)                                                                      |
| [normalizeServiceMemberName](/docs/api/services#normalizeservicemembername)                          | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#normalizeservicemembername)                                                                      |
| [normalizeServiceMemberNameEffect](/docs/api/services#normalizeservicemembernameeffect)              | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#normalizeservicemembernameeffect)                                                                |
| [NumberSchema](/docs/api/schema#numberschema-interface)                                              | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#numberschema-interface)                                                                            |
| [observeAgent](/docs/api/agents#observeagent)                                                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#observeagent)                                                                                      |
| [observeBucket](/docs/api/buckets#observebucket)                                                     | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#observebucket)                                                                                    |
| [observeFunction](/docs/api/functions#observefunction)                                               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#observefunction)                                                                                |
| [observeRealtime](/docs/api/realtime#observerealtime)                                                | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#observerealtime)                                                                                 |
| [observeRun](/docs/api/jobs#observerun)                                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#observerun)                                                                                          |
| [observeRunEffect](/docs/api/jobs#observeruneffect)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#observeruneffect)                                                                                    |
| [observeService](/docs/api/services#observeservice)                                                  | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#observeservice)                                                                                  |
| [observeTool](/docs/api/tools#observetool-1)                                                         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#observetool-1)                                                                                      |
| [OperationContext](/docs/api/jobs#operationcontext-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-reconciliation.test.ts#L18)             |
| [OperationIdEntropy](/docs/api/realtime#operationidentropy-class)                                    | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationidentropy-class)                                                                        |
| [OperationIdEntropyLive](/docs/api/realtime#operationidentropylive)                                  | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationidentropylive)                                                                          |
| [OperationIdError](/docs/api/realtime#operationiderror-class)                                        | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationiderror-class)                                                                          |
| [OperationIdFailure](/docs/api/realtime#operationidfailure-class)                                    | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationidfailure-class)                                                                        |
| [operationIdTimestamp](/docs/api/realtime#operationidtimestamp)                                      | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationidtimestamp)                                                                            |
| [operationIdTimestampEffect](/docs/api/realtime#operationidtimestampeffect)                          | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#operationidtimestampeffect)                                                                      |
| [OutputOf](/docs/api/jobs#outputof-type-alias)                                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [parseDuration](/docs/api/jobs#parseduration)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#parseduration)                                                                                       |
| [parseEnvBuilderEffect](/docs/api/config#parseenvbuildereffect)                                      | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#parseenvbuildereffect)                                                                             |
| [parseModelProviderConfiguration](/docs/api/agents#parsemodelproviderconfiguration)                  | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#parsemodelproviderconfiguration)                                                                   |
| [parseModelProviderConfigurationEffect](/docs/api/agents#parsemodelproviderconfigurationeffect)      | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#parsemodelproviderconfigurationeffect)                                                             |
| [parseOperationId](/docs/api/realtime#parseoperationid)                                              | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#parseoperationid)                                                                                |
| [parseOperationIdEffect](/docs/api/realtime#parseoperationideffect)                                  | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#parseoperationideffect)                                                                          |
| [PendingApproval](/docs/api/agents#pendingapproval-interface)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/agent-approval.fixture.ts#L40)           |
| [prepareCanonicalSubmission](/docs/api/jobs#preparecanonicalsubmission)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#preparecanonicalsubmission)                                                                          |
| [prepareCanonicalSubmissionEffect](/docs/api/jobs#preparecanonicalsubmissioneffect)                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#preparecanonicalsubmissioneffect)                                                                    |
| [prepareSubmission](/docs/api/jobs#preparesubmission)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#preparesubmission)                                                                                   |
| [prepareSubmissionEffect](/docs/api/jobs#preparesubmissioneffect)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#preparesubmissioneffect)                                                                             |
| [PresenceLeaseRequest](/docs/api/realtime#presenceleaserequest-interface)                            | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#presenceleaserequest-interface)                                                                  |
| [PresenceMember](/docs/api/realtime#presencemember-interface)                                        | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#presencemember-interface)                                                                        |
| [PresenceSnapshot](/docs/api/realtime#presencesnapshot-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#presencesnapshot-type-alias)                                                                     |
| [ProgressEmitReceipt](/docs/api/app#progressemitreceipt-interface)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [projectEnv](/docs/api/config#projectenv-1)                                                          | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#projectenv-1)                                                                                      |
| [projectEnvEffect](/docs/api/config#projectenveffect-1)                                              | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#projectenveffect-1)                                                                                |
| [projectRun](/docs/api/jobs#projectrun)                                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#projectrun)                                                                                          |
| [projectRunPage](/docs/api/jobs#projectrunpage)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#projectrunpage)                                                                                      |
| [projectRunPageEffect](/docs/api/jobs#projectrunpageeffect)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#projectrunpageeffect)                                                                                |
| [projectRunSnapshot](/docs/api/jobs#projectrunsnapshot)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#projectrunsnapshot)                                                                                  |
| [projectRunSnapshotEffect](/docs/api/jobs#projectrunsnapshoteffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#projectrunsnapshoteffect)                                                                            |
| [PromptDescriptor](/docs/api/app#promptdescriptor-interface)                                         | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#promptdescriptor-interface)                                                                           |
| [PromptInstructions](/docs/api/agents#promptinstructions-interface)                                  | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [PromptTemplate](/docs/api/agents#prompttemplate-interface)                                          | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [PromptValue](/docs/api/app#promptvalue-type-alias)                                                  | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#promptvalue-type-alias)                                                                               |
| [ProviderRealtimeDispatcherOptions](/docs/api/realtime#providerrealtimedispatcheroptions-interface)  | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#providerrealtimedispatcheroptions-interface)                                                     |
| [providerSourceLayer](/docs/api/realtime#providersourcelayer)                                        | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#providersourcelayer)                                                                             |
| [PublicClock](/docs/api/functions#publicclock-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#publicclock-type-alias)                                                                         |
| [PublicLogger](/docs/api/functions#publiclogger-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#publiclogger-type-alias)                                                                        |
| [PublishedEventName](/docs/api/jobs#publishedeventname-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [putBucketEffect](/docs/api/buckets#putbucketeffect)                                                 | Value | `@relkit/app`, `@relkit/app/buckets`                              | [API example](/docs/api/buckets#putbucketeffect)                                                                                  |
| [RawHttpHandler](/docs/api/routes#rawhttphandler-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#rawhttphandler-type-alias)                                                                         |
| [RawRouteDescriptor](/docs/api/routes#rawroutedescriptor-interface)                                  | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#rawroutedescriptor-interface)                                                                      |
| [RawRouteOptions](/docs/api/routes#rawrouteoptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#rawrouteoptions-interface)                                                                         |
| [ReadChannelEvents](/docs/api/realtime#readchannelevents-interface)                                  | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#readchannelevents-interface)                                                                     |
| [ReadControlsRequest](/docs/api/app#readcontrolsrequest-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [readJobCursor](/docs/api/jobs#readjobcursor)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#readjobcursor)                                                                                       |
| [readJobCursorEffect](/docs/api/jobs#readjobcursoreffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#readjobcursoreffect)                                                                                 |
| [ReadJournalRequest](/docs/api/app#readjournalrequest-interface)                                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ReadPresenceRequest](/docs/api/realtime#readpresencerequest-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#readpresencerequest-type-alias)                                                                  |
| [readProviderPresenceEffect](/docs/api/realtime#readproviderpresenceeffect)                          | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#readproviderpresenceeffect)                                                                      |
| [ReadSnapshotHistoryRequest](/docs/api/app#readsnapshothistoryrequest-interface)                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RealtimeActionError](/docs/api/realtime#realtimeactionerror-class)                                  | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeactionerror-class)                                                                       |
| [RealtimeDispatcher](/docs/api/realtime#realtimedispatcher-interface)                                | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimedispatcher-interface)                                                                    |
| [RealtimeDispatcherError](/docs/api/realtime#realtimedispatchererror-class)                          | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimedispatchererror-class)                                                                   |
| [RealtimeDispatcherLive](/docs/api/realtime#realtimedispatcherlive)                                  | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimedispatcherlive)                                                                          |
| [RealtimeDispatcherService](/docs/api/realtime#realtimedispatcherservice-class)                      | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimedispatcherservice-class)                                                                 |
| [RealtimeLimits](/docs/api/realtime#realtimelimits-interface)                                        | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimelimits-interface)                                                                        |
| [RealtimeOperation](/docs/api/realtime#realtimeoperation-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeoperation-type-alias)                                                                    |
| [RealtimeProvider](/docs/api/realtime#realtimeprovider-interface)                                    | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeprovider-interface)                                                                      |
| [RealtimeProviderError](/docs/api/realtime#realtimeprovidererror-class)                              | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeprovidererror-class)                                                                     |
| [RealtimeProviderSource](/docs/api/realtime#realtimeprovidersource-class)                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeprovidersource-class)                                                                    |
| [RealtimeProviderSourceService](/docs/api/realtime#realtimeprovidersourceservice-interface)          | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimeprovidersourceservice-interface)                                                         |
| [RealtimeScope](/docs/api/realtime#realtimescope-interface)                                          | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimescope-interface)                                                                         |
| [RealtimeTelemetry](/docs/api/realtime#realtimetelemetry-class)                                      | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimetelemetry-class)                                                                         |
| [RealtimeTelemetryLive](/docs/api/realtime#realtimetelemetrylive)                                    | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimetelemetrylive)                                                                           |
| [RealtimeTelemetryService](/docs/api/realtime#realtimetelemetryservice-interface)                    | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#realtimetelemetryservice-interface)                                                              |
| [reconcileNativeSchedules](/docs/api/jobs#reconcilenativeschedules)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#reconcilenativeschedules)                                                                            |
| [reconcileNativeSchedulesEffect](/docs/api/jobs#reconcilenativescheduleseffect)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#reconcilenativescheduleseffect)                                                                      |
| [RecoverAbandonedControlRequest](/docs/api/app#recoverabandonedcontrolrequest-interface)             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ReleasePresenceLease](/docs/api/realtime#releasepresencelease-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#releasepresencelease-type-alias)                                                                 |
| [RELKIT_FUNCTION_GRAPH_NODE](/docs/api/functions#relkit_function_graph_node)                         | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#relkit_function_graph_node)                                                                     |
| [RelkitSchema](/docs/api/schema#relkitschema-interface)                                              | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#relkitschema-interface)                                                                            |
| [RenewControlClaimRequest](/docs/api/app#renewcontrolclaimrequest-interface)                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RenewPresenceLease](/docs/api/realtime#renewpresencelease-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#renewpresencelease-type-alias)                                                                   |
| [RenewRunClaimRequest](/docs/api/app#renewrunclaimrequest-interface)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [requireJobsRuntime](/docs/api/jobs#requirejobsruntime)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#requirejobsruntime)                                                                                  |
| [requireJobsRuntimeEffect](/docs/api/jobs#requirejobsruntimeeffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#requirejobsruntimeeffect)                                                                            |
| [requiresApproval](/docs/api/agents#requiresapproval)                                                | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#requiresapproval)                                                                                  |
| [requiresApprovalEffect](/docs/api/agents#requiresapprovaleffect)                                    | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#requiresapprovaleffect)                                                                            |
| [RESERVED_SERVICE_MEMBER_NAMES](/docs/api/services#reserved_service_member_names)                    | Value | `@relkit/app`, `@relkit/app/services`                             | [Module example](/docs/learn/concepts/application)                                                                                |
| [resolveBinding](/docs/api/jobs#resolvebinding)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#resolvebinding)                                                                                      |
| [ResolveBindingOptions](/docs/api/jobs#resolvebindingoptions-interface)                              | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ResolvedApplicationContext](/docs/api/app#resolvedapplicationcontext-interface)                     | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#resolvedapplicationcontext-interface)                                                                 |
| [ResolvedApplicationEnv](/docs/api/functions#resolvedapplicationenv-type-alias)                      | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#resolvedapplicationenv-type-alias)                                                              |
| [ResolvedConstants](/docs/api/app#resolvedconstants-type-alias)                                      | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#resolvedconstants-type-alias)                                                                         |
| [ResolvedEnv](/docs/api/config#resolvedenv-type-alias)                                               | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#resolvedenv-type-alias)                                                                            |
| [ResolvedModelSelection](/docs/api/agents#resolvedmodelselection-interface)                          | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ResolvedPrompt](/docs/api/app#resolvedprompt-type-alias)                                            | Type  | `@relkit/app`                                                     | [API example](/docs/api/app#resolvedprompt-type-alias)                                                                            |
| [ResolvedTaskBinding](/docs/api/jobs#resolvedtaskbinding-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ResolvedToolTarget](/docs/api/tools#resolvedtooltarget-interface)                                   | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#resolvedtooltarget-interface)                                                                       |
| [resolveEnv](/docs/api/config#resolveenv-1)                                                          | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#resolveenv-1)                                                                                      |
| [resolveEnvEffect](/docs/api/config#resolveenveffect-1)                                              | Value | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#resolveenveffect-1)                                                                                |
| [ResolveEnvOptions](/docs/api/config#resolveenvoptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/config#resolveenvoptions-interface)                                                                       |
| [resolveModelSelector](/docs/api/agents#resolvemodelselector)                                        | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#resolvemodelselector)                                                                              |
| [resolveModelSelectorEffect](/docs/api/agents#resolvemodelselectoreffect)                            | Value | `@relkit/app`, `@relkit/app/agents`                               | [API example](/docs/api/agents#resolvemodelselectoreffect)                                                                        |
| [resolveTaskBinding](/docs/api/jobs#resolvetaskbinding)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#resolvetaskbinding)                                                                                  |
| [resolveTaskBindingEffect](/docs/api/jobs#resolvetaskbindingeffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#resolvetaskbindingeffect)                                                                            |
| [resolveToolTarget](/docs/api/tools#resolvetooltarget)                                               | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#resolvetooltarget)                                                                                  |
| [resolveToolTargetEffect](/docs/api/tools#resolvetooltargeteffect)                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#resolvetooltargeteffect)                                                                            |
| [RespondMapping](/docs/api/routes#respondmapping-interface)                                          | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#respondmapping-interface)                                                                          |
| [ResultAvailability](/docs/api/app#resultavailability-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [retryDelayMillis](/docs/api/jobs#retrydelaymillis)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retrydelaymillis)                                                                                    |
| [retryDelayMillisEffect](/docs/api/jobs#retrydelaymilliseffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retrydelaymilliseffect)                                                                              |
| [RetryJitter](/docs/api/jobs#retryjitter-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RetryJitter](/docs/api/jobs#retryjitter-type-alias-1)                                               | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [retryOperationIdentity](/docs/api/jobs#retryoperationidentity)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retryoperationidentity)                                                                              |
| [retryOperationIdentityEffect](/docs/api/jobs#retryoperationidentityeffect)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retryoperationidentityeffect)                                                                        |
| [RetryPolicy](/docs/api/jobs#retrypolicy-interface)                                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RetryPolicy](/docs/api/jobs#retrypolicy-interface-1)                                                | Type  | `@relkit/app/jobs/legacy`                                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/events.ts#L19)                                       |
| [retryRun](/docs/api/jobs#retryrun)                                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retryrun)                                                                                            |
| [retryRunEffect](/docs/api/jobs#retryruneffect)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#retryruneffect)                                                                                      |
| [rotateRunLocatorKeys](/docs/api/jobs#rotaterunlocatorkeys)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#rotaterunlocatorkeys)                                                                                |
| [rotateRunLocatorKeysEffect](/docs/api/jobs#rotaterunlocatorkeyseffect)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#rotaterunlocatorkeyseffect)                                                                          |
| [RouteClientPolicy](/docs/api/routes#routeclientpolicy-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routeclientpolicy-type-alias)                                                                      |
| [RouteDescriptor](/docs/api/routes#routedescriptor-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routedescriptor-type-alias)                                                                        |
| [RouteInputError](/docs/api/routes#routeinputerror-class)                                            | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routeinputerror-class)                                                                             |
| [RouteModuleContract](/docs/api/routes#routemodulecontract-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/routes`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/route-modules.ts#L18)                                    |
| [RouteModuleMethod](/docs/api/routes#routemodulemethod-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RouteOperation](/docs/api/routes#routeoperation-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routeoperation-type-alias)                                                                         |
| [RouteOperationError](/docs/api/routes#routeoperationerror-class)                                    | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routeoperationerror-class)                                                                         |
| [RouteRateLimit](/docs/api/routes#routeratelimit-interface)                                          | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routeratelimit-interface)                                                                          |
| [RouteTelemetry](/docs/api/routes#routetelemetry-class)                                              | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routetelemetry-class)                                                                              |
| [RouteTelemetryLive](/docs/api/routes#routetelemetrylive-1)                                          | Value | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routetelemetrylive-1)                                                                              |
| [RouteTelemetryService](/docs/api/routes#routetelemetryservice-interface)                            | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#routetelemetryservice-interface)                                                                   |
| [RUN_LOCATOR_MAX_BYTES](/docs/api/jobs#run_locator_max_bytes)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#run_locator_max_bytes)                                                                               |
| [RUN_LOCATOR_VERSION](/docs/api/jobs#run_locator_version)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#run_locator_version)                                                                                 |
| [RunAvailability](/docs/api/app#runavailability-interface)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunCancellationReceipt](/docs/api/app#runcancellationreceipt-interface)                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunConnection](/docs/api/app#runconnection-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [runFunctionPromise](/docs/api/functions#runfunctionpromise)                                         | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#runfunctionpromise)                                                                             |
| [runFunctionSync](/docs/api/functions#runfunctionsync)                                               | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#runfunctionsync)                                                                                |
| [RunHandle](/docs/api/app#runhandle-interface)                                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L36)                                      |
| [runInJobsRuntime](/docs/api/jobs#runinjobsruntime)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runinjobsruntime)                                                                                    |
| [runInJobsRuntimeEffect](/docs/api/jobs#runinjobsruntimeeffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runinjobsruntimeeffect)                                                                              |
| [RunListQuery](/docs/api/app#runlistquery-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorCreateOptions](/docs/api/jobs#runlocatorcreateoptions-interface)                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorError](/docs/api/jobs#runlocatorerror-class)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorerror-class)                                                                               |
| [RunLocatorFailure](/docs/api/jobs#runlocatorfailure-class)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorfailure-class)                                                                             |
| [RunLocatorGeneration](/docs/api/jobs#runlocatorgeneration-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorGenerationStorage](/docs/api/jobs#runlocatorgenerationstorage-class)                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorgenerationstorage-class)                                                                   |
| [RunLocatorGenerationStore](/docs/api/jobs#runlocatorgenerationstore-interface)                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorKeyRing](/docs/api/jobs#runlocatorkeyring-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorKeyRingStore](/docs/api/jobs#runlocatorkeyringstore-interface)                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorPayload](/docs/api/jobs#runlocatorpayload-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunLocatorRouter](/docs/api/jobs#runlocatorrouter-class)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorrouter-class)                                                                              |
| [RunLocatorStoreFailure](/docs/api/jobs#runlocatorstorefailure-class)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorstorefailure-class)                                                                        |
| [runLocatorStoreLayer](/docs/api/jobs#runlocatorstorelayer)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runlocatorstorelayer)                                                                                |
| [RunLocatorVerifyOptions](/docs/api/jobs#runlocatorverifyoptions-interface)                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunOwner](/docs/api/app#runowner-interface)                                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunPage](/docs/api/app#runpage-interface)                                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector-api/tests/compatibility/jobs.test.ts#L85)         |
| [RunReceiptLookup](/docs/api/app#runreceiptlookup-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunResultOptions](/docs/api/jobs#runresultoptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunRetryReceipt](/docs/api/app#runretryreceipt-interface)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [runServiceSync](/docs/api/services#runservicesync)                                                  | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#runservicesync)                                                                                  |
| [RunSnapshot](/docs/api/app#runsnapshot-type-alias)                                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L557)         |
| [RunStatus](/docs/api/app#runstatus-type-alias)                                                      | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunStatus](/docs/api/app#runstatus-type-alias-1)                                                    | Type  | `@relkit/app/jobs`                                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [RunWatchFrame](/docs/api/app#runwatchframe-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L615)         |
| [runWithJobsRuntime](/docs/api/jobs#runwithjobsruntime)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runwithjobsruntime)                                                                                  |
| [runWithJobsRuntimeEffect](/docs/api/jobs#runwithjobsruntimeeffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#runwithjobsruntimeeffect)                                                                            |
| [runWithRealtimeDispatcher](/docs/api/realtime#runwithrealtimedispatcher)                            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#runwithrealtimedispatcher)                                                                       |
| [runWithRealtimeDispatcherEffect](/docs/api/realtime#runwithrealtimedispatchereffect)                | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#runwithrealtimedispatchereffect)                                                                 |
| [ScheduleDefinition](/docs/api/jobs#scheduledefinition-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-controls.test.ts#L70)                   |
| [ScheduleDefinition](/docs/api/jobs#scheduledefinition-interface)                                    | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleListOptions](/docs/api/jobs#schedulelistoptions-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleMisfire](/docs/api/jobs#schedulemisfire-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [scheduleOccurrenceIdentity](/docs/api/jobs#scheduleoccurrenceidentity)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleoccurrenceidentity)                                                                          |
| [scheduleOccurrenceIdentityEffect](/docs/api/jobs#scheduleoccurrenceidentityeffect)                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleoccurrenceidentityeffect)                                                                    |
| [scheduleOperationId](/docs/api/jobs#scheduleoperationid)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleoperationid)                                                                                 |
| [scheduleOperationIdEffect](/docs/api/jobs#scheduleoperationideffect)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleoperationideffect)                                                                           |
| [ScheduleOverlap](/docs/api/jobs#scheduleoverlap-type-alias-1)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleOverlap](/docs/api/jobs#scheduleoverlap-type-alias)                                         | Type  | `@relkit/app/jobs/legacy`                                         | [Module example](/docs/learn/concepts/application)                                                                                |
| [scheduleOwner](/docs/api/jobs#scheduleowner)                                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleowner)                                                                                       |
| [scheduleOwnerEffect](/docs/api/jobs#scheduleownereffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#scheduleownereffect)                                                                                 |
| [ScheduleReadReceipt](/docs/api/jobs#schedulereadreceipt-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleReconciliationFailure](/docs/api/jobs#schedulereconciliationfailure-class)                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#schedulereconciliationfailure-class)                                                                 |
| [ScheduleReconciliationOptions](/docs/api/jobs#schedulereconciliationoptions-interface)              | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleReconciliationResult](/docs/api/jobs#schedulereconciliationresult-interface)                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleRecord](/docs/api/jobs#schedulerecord-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleWriteOptions](/docs/api/jobs#schedulewriteoptions-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleWriteOutcome](/docs/api/jobs#schedulewriteoutcome-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [ScheduleWriteReceipt](/docs/api/jobs#schedulewritereceipt-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [Schema](/docs/api/schema#schema-interface)                                                          | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schema-interface)                                                                                  |
| [SchemaAsyncError](/docs/api/schema#schemaasyncerror-class)                                          | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaasyncerror-class)                                                                            |
| [SchemaBuilderError](/docs/api/schema#schemabuildererror-class)                                      | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemabuildererror-class)                                                                          |
| [SchemaExecutionError](/docs/api/schema#schemaexecutionerror-class)                                  | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaexecutionerror-class)                                                                        |
| [SchemaInvalidError](/docs/api/schema#schemainvaliderror-class)                                      | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemainvaliderror-class)                                                                          |
| [SchemaIssuesError](/docs/api/schema#schemaissueserror-class)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaissueserror-class)                                                                           |
| [SchemaProjector](/docs/api/schema#schemaprojector-class)                                            | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaprojector-class)                                                                             |
| [SchemaProjectorLive](/docs/api/schema#schemaprojectorlive-1)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaprojectorlive-1)                                                                             |
| [SchemaProjectorService](/docs/api/schema#schemaprojectorservice-interface)                          | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemaprojectorservice-interface)                                                                  |
| [SchemaTelemetry](/docs/api/schema#schematelemetry-class)                                            | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schematelemetry-class)                                                                             |
| [SchemaTelemetryLive](/docs/api/schema#schematelemetrylive-1)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schematelemetrylive-1)                                                                             |
| [SchemaTelemetryService](/docs/api/schema#schematelemetryservice-interface)                          | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schematelemetryservice-interface)                                                                  |
| [SchemaValidationError](/docs/api/schema#schemavalidationerror-class)                                | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemavalidationerror-class)                                                                       |
| [SchemaValidator](/docs/api/schema#schemavalidator-class)                                            | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemavalidator-class)                                                                             |
| [SchemaValidatorLive](/docs/api/schema#schemavalidatorlive-1)                                        | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemavalidatorlive-1)                                                                             |
| [SchemaValidatorService](/docs/api/schema#schemavalidatorservice-interface)                          | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#schemavalidatorservice-interface)                                                                  |
| [serializeJobsServiceOptions](/docs/api/jobs#serializejobsserviceoptions)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#serializejobsserviceoptions)                                                                         |
| [serializeJobsServiceOptionsEffect](/docs/api/jobs#serializejobsserviceoptionseffect)                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#serializejobsserviceoptionseffect)                                                                   |
| [ServerConfig](/docs/api/app#serverconfig-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/config`                               | [API example](/docs/api/app#serverconfig-interface)                                                                               |
| [ServerTriggerOptions](/docs/api/jobs#servertriggeroptions-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [SERVICE_RESERVED_MEMBER_NAMES](/docs/api/services#service_reserved_member_names)                    | Value | `@relkit/app`, `@relkit/app/services`                             | [Module example](/docs/learn/concepts/application)                                                                                |
| [SERVICE_ROUTE_METHODS](/docs/api/routes#service_route_methods)                                      | Value | `@relkit/app`, `@relkit/app/routes`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/routes/tests/define-service-routes.test.ts#L26)             |
| [ServiceDescriptor](/docs/api/services#servicedescriptor-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicedescriptor-type-alias)                                                                    |
| [ServiceDescriptorAny](/docs/api/services#servicedescriptorany-type-alias)                           | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicedescriptorany-type-alias)                                                                 |
| [ServiceEventMap](/docs/api/services#serviceeventmap-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#serviceeventmap-type-alias)                                                                      |
| [ServiceEvents](/docs/api/services#serviceevents-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#serviceevents-type-alias)                                                                        |
| [ServiceFunctionMap](/docs/api/services#servicefunctionmap-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicefunctionmap-type-alias)                                                                   |
| [ServiceFunctions](/docs/api/services#servicefunctions-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicefunctions-type-alias)                                                                     |
| [ServiceJobMap](/docs/api/services#servicejobmap-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicejobmap-type-alias)                                                                        |
| [ServiceJobs](/docs/api/services#servicejobs-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicejobs-type-alias)                                                                          |
| [serviceMemberEntries](/docs/api/services#servicememberentries)                                      | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicememberentries)                                                                            |
| [serviceMemberEntriesEffect](/docs/api/services#servicememberentrieseffect)                          | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicememberentrieseffect)                                                                      |
| [ServiceRef](/docs/api/services#serviceref-interface)                                                | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#serviceref-interface)                                                                            |
| [ServiceRefAny](/docs/api/services#servicerefany-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicerefany-type-alias)                                                                        |
| [ServiceRouteEntry](/docs/api/routes#servicerouteentry-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#servicerouteentry-type-alias)                                                                      |
| [ServiceRouteMethod](/docs/api/routes#serviceroutemethod-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#serviceroutemethod-type-alias)                                                                     |
| [ServiceRouteOptions](/docs/api/routes#servicerouteoptions-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#servicerouteoptions-type-alias)                                                                    |
| [ServiceRoutesOptions](/docs/api/routes#serviceroutesoptions-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#serviceroutesoptions-type-alias)                                                                   |
| [ServiceRoutesResult](/docs/api/routes#serviceroutesresult-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#serviceroutesresult-type-alias)                                                                    |
| [ServiceTaskMap](/docs/api/services#servicetaskmap-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicetaskmap-type-alias)                                                                       |
| [ServiceTasks](/docs/api/services#servicetasks-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicetasks-type-alias)                                                                         |
| [ServiceTelemetry](/docs/api/services#servicetelemetry-class)                                        | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicetelemetry-class)                                                                          |
| [ServiceTelemetryLive](/docs/api/services#servicetelemetrylive)                                      | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicetelemetrylive)                                                                            |
| [ServiceValidationError](/docs/api/services#servicevalidationerror-class)                            | Value | `@relkit/app`, `@relkit/app/services`                             | [API example](/docs/api/services#servicevalidationerror-class)                                                                    |
| [setActiveRealtimeDispatcher](/docs/api/realtime#setactiverealtimedispatcher)                        | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#setactiverealtimedispatcher)                                                                     |
| [setActiveRealtimeDispatcherEffect](/docs/api/realtime#setactiverealtimedispatchereffect)            | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#setactiverealtimedispatchereffect)                                                               |
| [setCacheEffect](/docs/api/cache#setcacheeffect)                                                     | Value | `@relkit/app`, `@relkit/app/cache`                                | [API example](/docs/api/cache#setcacheeffect)                                                                                     |
| [SettleControlRequest](/docs/api/app#settlecontrolrequest-interface)                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [SnapshotHistoryPage](/docs/api/app#snapshothistorypage-interface)                                   | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [stableIdentityTuple](/docs/api/jobs#stableidentitytuple)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#stableidentitytuple)                                                                                 |
| [stableIdentityTupleEffect](/docs/api/jobs#stableidentitytupleeffect)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#stableidentitytupleeffect)                                                                           |
| [StandardFailure](/docs/api/schema#standardfailure-interface)                                        | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardfailure-interface)                                                                         |
| [StandardIssue](/docs/api/schema#standardissue-interface)                                            | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardissue-interface)                                                                           |
| [StandardJSONSchemaV1](/docs/api/schema#standardjsonschemav1-interface)                              | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardjsonschemav1-interface)                                                                    |
| [StandardPathSegment](/docs/api/schema#standardpathsegment-type-alias)                               | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardpathsegment-type-alias)                                                                    |
| [StandardResult](/docs/api/schema#standardresult-type-alias)                                         | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardresult-type-alias)                                                                         |
| [StandardSchemaOptions](/docs/api/schema#standardschemaoptions-interface)                            | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardschemaoptions-interface)                                                                   |
| [StandardSchemaTypes](/docs/api/schema#standardschematypes-interface)                                | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardschematypes-interface)                                                                     |
| [StandardSchemaV1](/docs/api/schema#standardschemav1-interface)                                      | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardschemav1-interface)                                                                        |
| [StandardSuccess](/docs/api/schema#standardsuccess-interface)                                        | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#standardsuccess-interface)                                                                         |
| [StoredApproval](/docs/api/app#storedapproval-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [StoredRun](/docs/api/app#storedrun-interface)                                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [StoredRunRouting](/docs/api/app#storedrunrouting-interface)                                         | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [StoredThread](/docs/api/app#storedthread-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [StreamIdentity](/docs/api/app#streamidentity-interface)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [StreamItem](/docs/api/app#streamitem-type-alias)                                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [streamOf](/docs/api/functions#streamof)                                                             | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#streamof)                                                                                       |
| [streamOfEffect](/docs/api/functions#streamofeffect)                                                 | Value | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#streamofeffect)                                                                                 |
| [StreamOutputSchema](/docs/api/functions#streamoutputschema-interface)                               | Type  | `@relkit/app`, `@relkit/app/functions`                            | [API example](/docs/api/functions#streamoutputschema-interface)                                                                   |
| [StringSchema](/docs/api/schema#stringschema-interface)                                              | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#stringschema-interface)                                                                            |
| [SubmissionAdmission](/docs/api/jobs#submissionadmission-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [SubmissionPipeline](/docs/api/jobs#submissionpipeline-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [submitCanonicalTask](/docs/api/jobs#submitcanonicaltask)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submitcanonicaltask)                                                                                 |
| [submitCanonicalTaskEffect](/docs/api/jobs#submitcanonicaltaskeffect)                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submitcanonicaltaskeffect)                                                                           |
| [submitJob](/docs/api/jobs#submitjob)                                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submitjob)                                                                                           |
| [submitJobEffect](/docs/api/jobs#submitjobeffect)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submitjobeffect)                                                                                     |
| [submitPreparedSubmission](/docs/api/jobs#submitpreparedsubmission)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submitpreparedsubmission)                                                                            |
| [submitTask](/docs/api/jobs#submittask)                                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submittask)                                                                                          |
| [submitTaskEffect](/docs/api/jobs#submittaskeffect)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#submittaskeffect)                                                                                    |
| [SuspendRunRequest](/docs/api/app#suspendrunrequest-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [SuspensionReceipt](/docs/api/app#suspensionreceipt-interface)                                       | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [TASK_INPUT_MAX_BYTES](/docs/api/jobs#task_input_max_bytes-2)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_input_max_bytes-2)                                                                              |
| [TASK_ITEM_MAX_BYTES](/docs/api/jobs#task_item_max_bytes-2)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_item_max_bytes-2)                                                                               |
| [TASK_KEY_MAX_BYTES](/docs/api/jobs#task_key_max_bytes-2)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_key_max_bytes-2)                                                                                |
| [TASK_MAX_TAGS](/docs/api/jobs#task_max_tags-2)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_max_tags-2)                                                                                     |
| [TASK_OUTPUT_MAX_BYTES](/docs/api/jobs#task_output_max_bytes-2)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_output_max_bytes-2)                                                                             |
| [TASK_REASON_MAX_BYTES](/docs/api/jobs#task_reason_max_bytes-2)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#task_reason_max_bytes-2)                                                                             |
| [TaskAuthContext](/docs/api/jobs#taskauthcontext-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskBlockingWaitError](/docs/api/jobs#taskblockingwaiterror-class)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskblockingwaiterror-class)                                                                         |
| [TaskCallerInput](/docs/api/jobs#taskcallerinput-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L80)                                |
| [TaskCanonicalInput](/docs/api/jobs#taskcanonicalinput-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L81)                                |
| [TaskClientFor](/docs/api/jobs#taskclientfor-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskClientFor](/docs/api/functions#taskclientfor-type-alias)                                        | Type  | `@relkit/app/functions`                                           | [API example](/docs/api/functions#taskclientfor-type-alias)                                                                       |
| [TaskClients](/docs/api/jobs#taskclients-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskClients](/docs/api/functions#taskclients-type-alias)                                            | Type  | `@relkit/app/functions`                                           | [API example](/docs/api/functions#taskclients-type-alias)                                                                         |
| [TaskConcurrency](/docs/api/jobs#taskconcurrency-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskContext](/docs/api/jobs#taskcontext-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskContextBase](/docs/api/jobs#taskcontextbase-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskDefinitionFailure](/docs/api/jobs#taskdefinitionfailure-class)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskdefinitionfailure-class)                                                                         |
| [TaskDependencies](/docs/api/jobs#taskdependencies-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskDescriptor](/docs/api/jobs#taskdescriptor-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskDescriptorAny](/docs/api/jobs#taskdescriptorany-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L32)                        |
| [TaskEmissionError](/docs/api/jobs#taskemissionerror-class)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskemissionerror-class)                                                                             |
| [TaskEmissionErrorCode](/docs/api/jobs#taskemissionerrorcode-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskEmissionFailure](/docs/api/jobs#taskemissionfailure-class)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskemissionfailure-class)                                                                           |
| [TaskEmissionSink](/docs/api/jobs#taskemissionsink-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskEmitterOptions](/docs/api/jobs#taskemitteroptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskExecution](/docs/api/jobs#taskexecution-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskExecutionBinding](/docs/api/jobs#taskexecutionbinding-interface)                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskExecutionEnvelope](/docs/api/jobs#taskexecutionenvelope-interface)                              | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskExecutor](/docs/api/jobs#taskexecutor-interface)                                                | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskFailureHook](/docs/api/jobs#taskfailurehook-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskHandler](/docs/api/jobs#taskhandler-type-alias)                                                 | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L94)                                |
| [TaskHandlerResult](/docs/api/jobs#taskhandlerresult-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskHookContext](/docs/api/jobs#taskhookcontext-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskInput](/docs/api/jobs#taskinput-type-alias)                                                     | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskLogging](/docs/api/jobs#tasklogging-interface)                                                  | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskObservation](/docs/api/jobs#taskobservation-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [taskOperationIdentity](/docs/api/jobs#taskoperationidentity)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskoperationidentity)                                                                               |
| [taskOperationIdentityEffect](/docs/api/jobs#taskoperationidentityeffect)                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskoperationidentityeffect)                                                                         |
| [TaskOutput](/docs/api/jobs#taskoutput-type-alias)                                                   | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskPolicyRandom](/docs/api/jobs#taskpolicyrandom-class)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskpolicyrandom-class)                                                                              |
| [taskPolicyRandomLayer](/docs/api/jobs#taskpolicyrandomlayer)                                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskpolicyrandomlayer)                                                                               |
| [TaskProgressEmitter](/docs/api/jobs#taskprogressemitter-interface)                                  | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskProgressInput](/docs/api/jobs#taskprogressinput-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L86)                                |
| [TaskProgressOutput](/docs/api/jobs#taskprogressoutput-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L87)                                |
| [TaskRawHandlerOutput](/docs/api/jobs#taskrawhandleroutput-type-alias)                               | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L82)                                |
| [TaskResources](/docs/api/jobs#taskresources-interface)                                              | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskRetryPolicy](/docs/api/jobs#taskretrypolicy-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskRunContext](/docs/api/jobs#taskruncontext-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskSleepOptions](/docs/api/jobs#tasksleepoptions-interface)                                        | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStartHook](/docs/api/jobs#taskstarthook-type-alias)                                             | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamEmitter](/docs/api/jobs#taskstreamemitter-interface)                                      | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamEmitterOptions](/docs/api/jobs#taskstreamemitteroptions-interface)                        | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamEmitters](/docs/api/jobs#taskstreamemitters-type-alias)                                   | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamFrames](/docs/api/jobs#taskstreamframes-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamInput](/docs/api/jobs#taskstreaminput-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L88)                                |
| [TaskStreamItem](/docs/api/jobs#taskstreamitem-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamOutput](/docs/api/jobs#taskstreamoutput-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L89)                                |
| [TaskStreamSchemas](/docs/api/jobs#taskstreamschemas-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskStreamSink](/docs/api/jobs#taskstreamsink-type-alias)                                           | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskSubmissionMetadata](/docs/api/jobs#tasksubmissionmetadata-interface)                            | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/submission-write-effect.test.ts#L16)             |
| [TaskSuccessHook](/docs/api/jobs#tasksuccesshook-type-alias)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L90)                                |
| [TaskTriggerOptions](/docs/api/jobs#tasktriggeroptions-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskTriggerOptions](/docs/api/functions#tasktriggeroptions-interface)                               | Type  | `@relkit/app/functions`                                           | [API example](/docs/api/functions#tasktriggeroptions-interface)                                                                   |
| [TaskValidatedOutput](/docs/api/jobs#taskvalidatedoutput-type-alias)                                 | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L83)                                |
| [TaskWireErrorCode](/docs/api/jobs#taskwireerrorcode-type-alias)                                     | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [TaskWireFailure](/docs/api/jobs#taskwirefailure-class)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskwirefailure-class)                                                                               |
| [TaskWireValidationError](/docs/api/jobs#taskwirevalidationerror-class)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#taskwirevalidationerror-class)                                                                       |
| [ThreadAction](/docs/api/app#threadaction-type-alias)                                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L15) |
| [ThreadList](/docs/api/app#threadlist-interface)                                                     | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ThreadListItem](/docs/api/app#threadlistitem-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [ThreadSnapshot](/docs/api/app#threadsnapshot-interface)                                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L127) |
| [ThreadStatus](/docs/api/app#threadstatus-type-alias)                                                | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L8)  |
| [ThreadTransition](/docs/api/app#threadtransition-type-alias)                                        | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [toJsonSchema](/docs/api/schema#tojsonschema-1)                                                      | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#tojsonschema-1)                                                                                    |
| [ToolAllowlistEntry](/docs/api/tools#toolallowlistentry-type-alias)                                  | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolallowlistentry-type-alias)                                                                      |
| [ToolApproval](/docs/api/tools#toolapproval-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolApprovalDecision](/docs/api/tools#toolapprovaldecision-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolApprovalDeniedError](/docs/api/functions#functiontoolapprovaldeniederror-class)                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/functions#functiontoolapprovaldeniederror-class)                                                          |
| [ToolApprovalRequest](/docs/api/tools#toolapprovalrequest-type-alias)                                | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolApprovalRequiredError](/docs/api/functions#functiontoolapprovalrequirederror-class)             | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/functions#functiontoolapprovalrequirederror-class)                                                        |
| [ToolApprovalResolver](/docs/api/tools#toolapprovalresolver-type-alias)                              | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolArgumentsFailure](/docs/api/tools#toolargumentsfailure-class)                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolargumentsfailure-class)                                                                         |
| [ToolArgumentValidationError](/docs/api/functions#functiontoolargumentvalidationerror-class)         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/functions#functiontoolargumentvalidationerror-class)                                                      |
| [ToolCancelledFailure](/docs/api/tools#toolcancelledfailure-class)                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolcancelledfailure-class)                                                                         |
| [ToolDescriptor](/docs/api/tools#tooldescriptor-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooldescriptor-type-alias)                                                                          |
| [ToolEffectOptions](/docs/api/tools#tooleffectoptions-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooleffectoptions-type-alias)                                                                       |
| [ToolEngine](/docs/api/tools#toolengine-interface)                                                   | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolengine-interface)                                                                               |
| [ToolEngineFailure](/docs/api/tools#toolenginefailure-class)                                         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolenginefailure-class)                                                                            |
| [ToolEngineInvocation](/docs/api/tools#toolengineinvocation-interface)                               | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolengineinvocation-interface)                                                                     |
| [ToolEngineLive](/docs/api/tools#toolenginelive)                                                     | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolenginelive)                                                                                     |
| [ToolEngineLiveEffect](/docs/api/tools#toolengineliveeffect)                                         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolengineliveeffect)                                                                               |
| [ToolEngineService](/docs/api/tools#toolengineservice-class)                                         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolengineservice-class)                                                                            |
| [ToolInvocationContext](/docs/api/tools#toolinvocationcontext-interface)                             | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolinvocationcontext-interface)                                                                    |
| [ToolInvocationRequest](/docs/api/tools#toolinvocationrequest-interface)                             | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolinvocationrequest-interface)                                                                    |
| [ToolInvokeOptions](/docs/api/tools#toolinvokeoptions-type-alias)                                    | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolNotAllowedError](/docs/api/tools#toolnotallowederror-class)                                     | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolnotallowederror-class)                                                                          |
| [ToolNotAllowedFailure](/docs/api/tools#toolnotallowedfailure-class)                                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolnotallowedfailure-class)                                                                        |
| [ToolOperation](/docs/api/tools#tooloperation-type-alias)                                            | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooloperation-type-alias)                                                                           |
| [ToolOperationCancelledError](/docs/api/functions#functiontooloperationcancellederror-class)         | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/functions#functiontooloperationcancellederror-class)                                                      |
| [ToolOperationFailure](/docs/api/tools#tooloperationfailure-class)                                   | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooloperationfailure-class)                                                                         |
| [ToolPartState](/docs/api/app#toolpartstate-type-alias)                                              | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L12)                     |
| [ToolRef](/docs/api/tools#toolref-interface)                                                         | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolref-interface)                                                                                  |
| [ToolRefAny](/docs/api/tools#toolrefany-type-alias)                                                  | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolRuntime](/docs/api/tools#toolruntime-interface)                                                 | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolruntime-interface)                                                                              |
| [ToolRuntimeOptions](/docs/api/tools#toolruntimeoptions-interface)                                   | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolruntimeoptions-interface)                                                                       |
| [ToolSideEffect](/docs/api/tools#toolsideeffect-type-alias)                                          | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolSource](/docs/api/tools#toolsource-type-alias)                                                  | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolsource-type-alias)                                                                              |
| [ToolTarget](/docs/api/tools#tooltarget-type-alias)                                                  | Type  | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooltarget-type-alias)                                                                              |
| [ToolTelemetry](/docs/api/tools#tooltelemetry-class)                                                 | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooltelemetry-class)                                                                                |
| [ToolTelemetryLive](/docs/api/tools#tooltelemetrylive-1)                                             | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#tooltelemetrylive-1)                                                                                |
| [ToolTelemetryService](/docs/api/tools#tooltelemetryservice-interface)                               | Type  | `@relkit/app`, `@relkit/app/tools`                                | [Module example](/docs/learn/concepts/application)                                                                                |
| [ToolUnknownError](/docs/api/tools#toolunknownerror-class)                                           | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolunknownerror-class)                                                                             |
| [ToolUnknownFailure](/docs/api/tools#toolunknownfailure-class)                                       | Value | `@relkit/app`, `@relkit/app/tools`                                | [API example](/docs/api/tools#toolunknownfailure-class)                                                                           |
| [TransformOutput](/docs/api/routes#transformoutput-type-alias)                                       | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#transformoutput-type-alias)                                                                        |
| [TransformReference](/docs/api/routes#transformreference-interface)                                  | Type  | `@relkit/app`, `@relkit/app/routes`                               | [API example](/docs/api/routes#transformreference-interface)                                                                      |
| [triggerChannelEffect](/docs/api/realtime#triggerchanneleffect)                                      | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#triggerchanneleffect)                                                                            |
| [TriggerOptions](/docs/api/jobs#triggeroptions-interface)                                            | Type  | `@relkit/app`, `@relkit/app/jobs`, `@relkit/app/tasks`            | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L224)                               |
| [triggerProviderEffect](/docs/api/realtime#triggerprovidereffect)                                    | Value | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#triggerprovidereffect)                                                                           |
| [TriggerReceipt](/docs/api/realtime#triggerreceipt-interface)                                        | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#triggerreceipt-interface)                                                                        |
| [TrustedJobScope](/docs/api/jobs#trustedjobscope-interface)                                          | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#trustedjobscope-interface)                                                                           |
| [UnknownEventEnvelope](/docs/api/events#unknowneventenvelope-type-alias)                             | Type  | `@relkit/app`, `@relkit/app/events`                               | [API example](/docs/api/events#unknowneventenvelope-type-alias)                                                                   |
| [utf8Bytes](/docs/api/jobs#utf8bytes)                                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#utf8bytes)                                                                                           |
| [utf8BytesEffect](/docs/api/jobs#utf8byteseffect)                                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#utf8byteseffect)                                                                                     |
| [validate](/docs/api/schema#validate-1)                                                              | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#validate-1)                                                                                        |
| [validateCanonicalInput](/docs/api/jobs#validatecanonicalinput)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatecanonicalinput)                                                                              |
| [validateCanonicalInputEffect](/docs/api/jobs#validatecanonicalinputeffect)                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatecanonicalinputeffect)                                                                        |
| [validateCanonicalOutput](/docs/api/jobs#validatecanonicaloutput)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatecanonicaloutput)                                                                             |
| [validateCanonicalOutputEffect](/docs/api/jobs#validatecanonicaloutputeffect)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatecanonicaloutputeffect)                                                                       |
| [validateDuration](/docs/api/jobs#validateduration)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validateduration)                                                                                    |
| [validateEffect](/docs/api/schema#validateeffect-1)                                                  | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#validateeffect-1)                                                                                  |
| [validateJobName](/docs/api/jobs#validatejobname-1)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobname-1)                                                                                   |
| [validateJobNameEffect](/docs/api/jobs#validatejobnameeffect-1)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobnameeffect-1)                                                                             |
| [validateJobsCapabilityReport](/docs/api/jobs#validatejobscapabilityreport-1)                        | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobscapabilityreport-1)                                                                      |
| [validateJobsCapabilityReportEffect](/docs/api/jobs#validatejobscapabilityreporteffect)              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobscapabilityreporteffect)                                                                  |
| [validateJobsServiceOptions](/docs/api/jobs#validatejobsserviceoptions)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobsserviceoptions)                                                                          |
| [validateJobsServiceOptionsEffect](/docs/api/jobs#validatejobsserviceoptionseffect)                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatejobsserviceoptionseffect)                                                                    |
| [validateResultOptions](/docs/api/jobs#validateresultoptions-1)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validateresultoptions-1)                                                                             |
| [validateRunLocatorKeyRing](/docs/api/jobs#validaterunlocatorkeyring-1)                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validaterunlocatorkeyring-1)                                                                         |
| [validateRunLocatorKeyRingEffect](/docs/api/jobs#validaterunlocatorkeyringeffect)                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validaterunlocatorkeyringeffect)                                                                     |
| [validateSync](/docs/api/schema#validatesync-1)                                                      | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#validatesync-1)                                                                                    |
| [validateSyncEffect](/docs/api/schema#validatesynceffect-1)                                          | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#validatesynceffect-1)                                                                              |
| [validateTaskInput](/docs/api/jobs#validatetaskinput)                                                | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatetaskinput)                                                                                   |
| [validateTaskInputEffect](/docs/api/jobs#validatetaskinputeffect)                                    | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatetaskinputeffect)                                                                             |
| [validateTaskOutput](/docs/api/jobs#validatetaskoutput)                                              | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatetaskoutput)                                                                                  |
| [validateTaskOutputEffect](/docs/api/jobs#validatetaskoutputeffect)                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#validatetaskoutputeffect)                                                                            |
| [ValidJobName](/docs/api/jobs#validjobname-type-alias)                                               | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [VerifiedRunLocator](/docs/api/jobs#verifiedrunlocator-interface)                                    | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [verifyRunLocator](/docs/api/jobs#verifyrunlocator)                                                  | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#verifyrunlocator)                                                                                    |
| [verifyRunLocatorEffect](/docs/api/jobs#verifyrunlocatoreffect)                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#verifyrunlocatoreffect)                                                                              |
| [VoidWireEnvelope](/docs/api/app#voidwireenvelope-interface)                                         | Type  | `@relkit/app`, `@relkit/app/jobs`                                 | [Module example](/docs/learn/concepts/application)                                                                                |
| [WaitForChannelEvents](/docs/api/realtime#waitforchannelevents-interface)                            | Type  | `@relkit/app`, `@relkit/app/realtime`                             | [API example](/docs/api/realtime#waitforchannelevents-interface)                                                                  |
| [WaitForControlsRequest](/docs/api/app#waitforcontrolsrequest-interface)                             | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [WaitForJournalRequest](/docs/api/app#waitforjournalrequest-interface)                               | Type  | `@relkit/app`, `@relkit/app/agents`                               | [Module example](/docs/learn/concepts/application)                                                                                |
| [waitForResult](/docs/api/jobs#waitforresult-1)                                                      | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#waitforresult-1)                                                                                     |
| [waitForResultEffect](/docs/api/jobs#waitforresulteffect-1)                                          | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#waitforresulteffect-1)                                                                               |
| [writeScheduleEffect](/docs/api/jobs#writescheduleeffect)                                            | Value | `@relkit/app`, `@relkit/app/jobs`                                 | [API example](/docs/api/jobs#writescheduleeffect)                                                                                 |
| [z](/docs/api/schema#z)                                                                              | Value | `@relkit/app/schema`                                              | [API example](/docs/api/schema#z)                                                                                                 |
| [ZBuilder](/docs/api/schema#zbuilder-interface)                                                      | Type  | `@relkit/app/schema`                                              | [API example](/docs/api/schema#zbuilder-interface)                                                                                |

## `agents.ts`

### "@relkit/agents" (namespace export)

Re-exports all named exports from the "@relkit/agents" module.

**Signature**

```ts
export * from "@relkit/agents";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/agents.ts#L1)

## `app-config.types.ts`

Declares server exposure and optional HTTP capability selection without loading
native SDKs. Compiler validation supplies defaults before runtime generation;
inspector settings select only the development bridge, independently of a tool.

### ApiDocsConfig (interface)

API documentation visibility and domain exclusions.

**Example**

```ts
const docs: ApiDocsConfig = { enabledInProduction: false };
```

**Signature**

```ts
export interface ApiDocsConfig {
  /** Explicitly selects Scalar; omitted/false keeps JSON OpenAPI only. */
  readonly ui?: "scalar" | false;
  readonly enabledInProduction?: boolean;
  readonly excludeDomains?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-config.types.ts#L10)

### AppCompatibilityConfig (interface)

Transitional compatibility switches for application authoring.

**Example**

```ts
const compatibility: AppCompatibilityConfig = { legacyJobs: true };
```

**Signature**

```ts
export interface AppCompatibilityConfig {
  readonly legacyJobs?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-config.types.ts#L38)

### InspectorConfig (interface)

Development bridge selection; installing or running the UI is independent.

**Example**

```ts
const inspector: InspectorConfig = { enabled: true };
```

**Signature**

```ts
export interface InspectorConfig extends InspectorConfigurationInput {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-config.types.ts#L33)

### ServerConfig (interface)

HTTP server settings attached to an application descriptor.

**Example**

```ts
const server: ServerConfig = { port: 3000, apiDocs: { enabledInProduction: false } };
```

**Signature**

```ts
export interface ServerConfig {
  readonly port?: number;
  readonly maxBodyBytes?: number;
  readonly apiDocs?: ApiDocsConfig;
  readonly clientContract?: boolean;
  readonly mcp?: boolean;
  /** Explicitly selects the optional AG-UI HTTP protocol independently of agent RPC. */
  readonly agUi?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-config.types.ts#L20)

## `app-observability.ts`

### AppTelemetry (class)

Injectable observer for application authoring operations.

**Example**

```ts
Effect.provide(defineAppEffect(options), AppTelemetryLive);
```

**Signature**

```ts
declare class AppTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-observability.ts#L7)

### AppTelemetryLive

Live spans, counts, failures, and durations for application operations.

**Example**

```ts
Effect.provide(defineAppEffect(options), AppTelemetryLive);
```

**Signature**

```ts
declare const AppTelemetryLive: Layer.Layer<AppTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-observability.ts#L14)

### observeApp

Applies an injected observer or the live observer to one operation.

**Example**

```ts
observeApp("define", Effect.succeed(app));
```

**Signature**

```ts
declare const observeApp: <A, E, R>(
  operation: AppOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-observability.ts#L28)

## `app-observability.types.ts`

Defines bounded application-authoring operation labels and the injectable
observer contract. Observers preserve each operation's success/error/services
while the live implementation records its spans and outcomes.

### AppOperation (type alias)

Fixed operation labels used for application authoring telemetry.

**Example**

```ts
const operation: AppOperation = "define";
```

**Signature**

```ts
type AppOperation =
  | "define"
  | "env.isDefinition"
  | "id.derive"
  | "compatibility.normalize"
  | "runtimeMetadata.normalize"
  | "alias.assertExclusive"
  | "constants.define"
  | "prompt.define"
  | "context.create"
  | "context.resolve";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-observability.types.ts#L11)

### AppTelemetryService (interface)

A replaceable observer for application authoring operations.

**Example**

```ts
const observer: AppTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface AppTelemetryService {
  /** Surrounds one operation without changing its result.
   * @param operation - A fixed operation label.
   * @param effect - The operation to observe.
   * @returns The observed Effect with its success and error channels intact.
   * @example observer.observe("define", Effect.succeed(app));
   */
  readonly observe: <A, E, R>(
    operation: AppOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-observability.types.ts#L26)

## `app-provider-capabilities.ts`

Provider capabilities accepted by application descriptors.

### APP_PROVIDER_CAPABILITIES

Provider capabilities accepted by application descriptors.

**Signature**

```ts
declare const APP_PROVIDER_CAPABILITIES: readonly [
  "bucket",
  "cache",
  "job",
  "event",
  "model",
  "realtime",
  "agent-state",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider-capabilities.ts#L2)

## `app-provider-normalization.ts`

### copyEffect

Copies a serializable configuration value through RELKIT's serializer.

**Example**

```ts
Effect.runSync(copyEffect({ port: 3000 }));
```

**Signature**

```ts
declare const copyEffect: <Value>(
  value: Value,
) => Effect.Effect<Value, AppValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider-normalization.ts#L74)

### normalizeDefaultsEffect

Checks default profile selections and returns an immutable copy.

**Example**

```ts
Effect.runSync(normalizeDefaultsEffect({}, undefined));
```

**Signature**

```ts
declare const normalizeDefaultsEffect: <Providers extends AppProviderInputs>(
  providers: Partial<
    Record<
      "bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
      NormalizedProviderProfiles<ProviderAdapter>
    >
  >,
  defaults: AppProviderDefaults<Providers> | undefined,
) => Effect.Effect<
  Readonly<{
    bucket?: ProfileFor<Providers, "bucket">;
    cache?: ProfileFor<Providers, "cache">;
    job?: ProfileFor<Providers, "job">;
    event?: ProfileFor<Providers, "event">;
    model?: ProfileFor<Providers, "model">;
    realtime?: ProfileFor<Providers, "realtime">;
    "agent-state"?: ProfileFor<Providers, "agent-state">;
  }>,
  AppValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider-normalization.ts#L45)

### normalizeProvidersEffect

Normalizes configured provider profiles in capability order.

**Example**

```ts
Effect.runSync(normalizeProvidersEffect({}));
```

**Signature**

```ts
declare const normalizeProvidersEffect: (
  options: AppProviderInputs,
) => Effect.Effect<
  Partial<
    Record<
      "bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
      NormalizedProviderProfiles<ProviderAdapter>
    >
  >,
  AppValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider-normalization.ts#L19)

## `app-provider.types.ts`

### AppProviderCapability (type alias)

Provider capabilities accepted by the application descriptor.

**Example**

```ts
const capability: AppProviderCapability = "cache";
```

**Signature**

```ts
type AppProviderCapability = (typeof APP_PROVIDER_CAPABILITIES)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider.types.ts#L13)

### AppProviderDefaults (type alias)

Public default-profile spellings; normalized descriptors use `job`.

**Example**

```ts
const defaults: AppProviderDefaults<typeof providers> = { cache: "default" };
```

**Signature**

```ts
type AppProviderDefaults<Providers extends AppProviderInputs> = Readonly<{
  [Capability in Exclude<AppProviderCapability, "job">]?: ProfileFor<Providers, Capability>;
}> & {
  readonly jobs?: ProfileFor<Providers, "job">;
  /** @deprecated Use `jobs`. */
  readonly job?: ProfileFor<Providers, "job">;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider.types.ts#L59)

### AppProviderInputs (interface)

Optional provider bindings for every supported capability.

**Example**

```ts
const providers: AppProviderInputs = { cache: redisAdapter };
```

**Signature**

```ts
export interface AppProviderInputs {
  readonly bucket?: CapabilityInput<"bucket">;
  readonly cache?: CapabilityInput<"cache">;
  /** Public plural spelling for the jobs provider capability. */
  readonly jobs?: CapabilityInput<"job">;
  /** @deprecated Use `jobs`. */
  readonly job?: CapabilityInput<"job">;
  readonly event?: CapabilityInput<"event">;
  readonly model?: CapabilityInput<"model">;
  readonly realtime?: CapabilityInput<"realtime">;
  readonly "agent-state"?: CapabilityInput<"agent-state">;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider.types.ts#L22)

### NormalizedAppProviderDefaults (type alias)

Validated default profiles keyed by normalized capability names.

**Example**

```ts
const defaults: NormalizedAppProviderDefaults<typeof providers> = { cache: "default" };
```

**Signature**

```ts
type NormalizedAppProviderDefaults<Providers extends AppProviderInputs> = Readonly<{
  [Capability in AppProviderCapability]?: ProfileFor<Providers, Capability>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider.types.ts#L70)

### NormalizedProviders (type alias)

Provider profiles inferred from the authored provider bindings.

**Example**

```ts
type Profiles = NormalizedProviders<typeof providers>;
```

**Signature**

```ts
type NormalizedProviders<Providers extends AppProviderInputs> = {
  readonly [
    Capability in AppProviderCapability as [ProviderInputFor<Providers, Capability>] extends [never]
      ? never
      : Capability
  ]: NormalizedProviderProfiles<AdapterOf<ProviderInputFor<Providers, Capability>>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-provider.types.ts#L77)

## `app-runtime-metadata.ts`

Copies application server/deployment metadata and validates optional inspection
selection before descriptor freezing. These pure authoring effects acquire no
listeners or providers; invalid input retains the public validation cause.

### normalizeAppRuntimeMetadataEffect

Normalizes immutable runtime policy without starting its selected features.

**Signature**

```ts
declare const normalizeAppRuntimeMetadataEffect: (
  options: Pick<ApplicationDescriptor, "server" | "inspector" | "deployment">,
) => Effect.Effect<
  {
    server: ServerConfig | undefined;
    inspector: InspectorConfiguration | undefined;
    deployment: Readonly<Record<string, JsonValue>> | undefined;
  },
  AppValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-runtime-metadata.ts#L18)

## `app-validation.ts`

### AppValidationFailure (class)

Expected invalid application input with the original cause preserved.

**Example**

```ts
if (error._tag === "AppValidationFailure") console.error(error.message);
```

**Signature**

```ts
declare class AppValidationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L10)

### assertExclusiveAlias

Synchronous alias exclusivity adapter.

**Throws**

TypeError when both aliases are present.

**Example**

```ts
assertExclusiveAlias(options, "jobs", "job", "defineApp");
```

**Signature**

```ts
declare const assertExclusiveAlias: (
  value: Record<string, unknown>,
  primary: string,
  legacy: string,
  label: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L146)

### assertExclusiveAliasEffect

Rejects simultaneous current and legacy aliases in Effect.

**Example**

```ts
Effect.runSync(assertExclusiveAliasEffect(options, "jobs", "job", "defineApp"));
```

**Signature**

```ts
declare const assertExclusiveAliasEffect: (
  value: Record<string, unknown>,
  primary: string,
  legacy: string,
  label: string,
) => Effect.Effect<void, AppValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L123)

### deriveApplicationId

Synchronous package-name ID adapter.

**Throws**

The original normalization error for invalid input.

**Example**

```ts
deriveApplicationId("@acme/orders");
```

**Signature**

```ts
declare const deriveApplicationId: (packageName: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L75)

### deriveApplicationIdEffect

Derives an application ID from a package name in Effect.

**Example**

```ts
Effect.runSync(deriveApplicationIdEffect("@acme/orders"));
```

**Signature**

```ts
declare const deriveApplicationIdEffect: (
  packageName: string,
) => Effect.Effect<StableId, AppValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L55)

### isEnvDefinition

Synchronous environment descriptor guard.

**Example**

```ts
if (isEnvDefinition(value)) console.log(value.shape);
```

**Signature**

```ts
declare const isEnvDefinition: (value: unknown) => value is EnvDefinition<EnvShape>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L46)

### isEnvDefinitionEffect

Checks the complete environment descriptor shape in Effect.

**Example**

```ts
Effect.runSync(isEnvDefinitionEffect(value));
```

**Signature**

```ts
declare const isEnvDefinitionEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L20)

### normalizeCompatibility

Synchronous compatibility normalizer.

**Throws**

TypeError for an invalid compatibility flag.

**Example**

```ts
normalizeCompatibility({ legacyJobs: true });
```

**Signature**

```ts
declare const normalizeCompatibility: (value: AppCompatibilityConfig | undefined) => {
  readonly legacyJobs: boolean;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L109)

### normalizeCompatibilityEffect

Normalizes the legacy jobs compatibility flag in Effect.

**Example**

```ts
Effect.runSync(normalizeCompatibilityEffect({ legacyJobs: true }));
```

**Signature**

```ts
declare const normalizeCompatibilityEffect: (
  value: AppCompatibilityConfig | undefined,
) => Effect.Effect<Readonly<{ legacyJobs: boolean }>, AppValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/app-validation.ts#L84)

## `buckets.ts`

### "@relkit/buckets" (namespace export)

Re-exports all named exports from the "@relkit/buckets" module.

**Signature**

```ts
export * from "@relkit/buckets";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/buckets.ts#L1)

## `cache.ts`

### "@relkit/cache" (namespace export)

Re-exports all named exports from the "@relkit/cache" module.

**Signature**

```ts
export * from "@relkit/cache";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/cache.ts#L1)

## `config.ts`

### "./app-validation.js" (namespace export)

Re-exports all named exports from the "./app-validation.js" module.

**Signature**

```ts
export * from "./app-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/config.ts#L1)

### "./define-app.js" (namespace export)

Re-exports all named exports from the "./define-app.js" module.

**Signature**

```ts
export * from "./define-app.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/config.ts#L3)

### "@relkit/config" (namespace export)

Re-exports all named exports from the "@relkit/config" module.

**Signature**

```ts
export * from "@relkit/config";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/config.ts#L4)

### AppTelemetry

**Signature**

```ts
declare const AppTelemetry: typeof AppTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/config.ts#L2)

### AppTelemetryLive

**Signature**

```ts
declare const AppTelemetryLive: Layer<AppTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/config.ts#L2)

## `context-descriptors.ts`

### "./context-descriptors.types.js" (namespace export)

Re-exports all named exports from the "./context-descriptors.types.js" module.

**Signature**

```ts
export * from "./context-descriptors.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L13)

### ContextDescriptorFailure (class)

Expected invalid constant or prompt descriptor input.

**Example**

```ts
if (error._tag === "ContextDescriptorFailure") console.error(error.message);
```

**Signature**

```ts
declare class ContextDescriptorFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L17)

### defineConstants

Synchronous constants descriptor adapter.

**Throws**

The original validation error for invalid values.

**Example**

```ts
import { defineConstants, defineEnv, env } from "@relkit/app";
const environment = defineEnv({ REGION: env.string() });
const limits = defineConstants({ maxItems: 20, region: environment.REGION });
// Literal values are immutable; the environment reference resolves with the context.
```

**See**

- https://relkit.dev/docs/modules/service/context-values

**Signature**

```ts
declare const defineConstants: <const Values extends ConstantsShape>(
  values: Values,
  options?: ContextDescriptorOptions,
) => ConstantsDescriptor<Values>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L69)

### defineConstantsEffect

Defines a frozen constants descriptor in Effect.

**Example**

```ts
Effect.runSync(defineConstantsEffect({ region: "eu" }));
```

**Signature**

```ts
declare const defineConstantsEffect: <const Values extends ConstantsShape>(
  values: Values,
  options?: ContextDescriptorOptions | undefined,
) => Effect.Effect<ConstantsDescriptor<Values>, ContextDescriptorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L27)

### definePrompt

Synchronous prompt descriptor adapter.

**Throws**

The original validation error for invalid text.

**Example**

```ts
import { definePrompt } from "@relkit/app";
const support = definePrompt(["Use the order details.", "Do not invent delivery dates."]);
// support.value preserves the two fragments in order.
```

**See**

- https://relkit.dev/docs/modules/service/context-values

**Signature**

```ts
declare const definePrompt: <const Value extends PromptValue>(
  value: Value,
  options?: ContextDescriptorOptions,
) => PromptDescriptor<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L121)

### definePromptEffect

Defines a frozen prompt descriptor in Effect.

**Example**

```ts
Effect.runSync(definePromptEffect("Be concise."));
```

**Signature**

```ts
declare const definePromptEffect: <const Value extends PromptValue>(
  value: Value,
  options?: ContextDescriptorOptions | undefined,
) => Effect.Effect<PromptDescriptor<Value>, ContextDescriptorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.ts#L81)

## `context-descriptors.types.ts`

### ConstantResolver (type alias)

Computes one constant for each context resolution.

**Example**

```ts
const region: ConstantResolver<string> = ({ env }) => String(env.REGION);
```

**Signature**

```ts
type ConstantResolver<Value = unknown> = (options: ContextResolverOptions) => MaybePromise<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L17)

### ConstantValue (type alias)

Accepted static, environment, or dynamic constant input.

**Example**

```ts
const value: ConstantValue = "eu-west-1";
```

**Signature**

```ts
type ConstantValue = JsonValue | EnvRef | ConstantResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L24)

### ConstantsDescriptor (interface)

Immutable descriptor for one set of constants.

**Example**

```ts
const descriptor: ConstantsDescriptor = defineConstants({ region: "eu" });
```

**Signature**

```ts
export interface ConstantsDescriptor<
  Values extends ConstantsShape = ConstantsShape,
> extends DescriptorBase<"constants", string> {
  readonly values: Values;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L34)

### ConstantsShape (type alias)

Named constant inputs for one descriptor.

**Example**

```ts
const values: ConstantsShape = { region: "eu-west-1" };
```

**Signature**

```ts
type ConstantsShape = Readonly<Record<string, ConstantValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L29)

### ContextDescriptorOptions (interface)

Optional stable identity for a context descriptor.

**Example**

```ts
const options: ContextDescriptorOptions = { id: "support.prompt" };
```

**Signature**

```ts
export interface ContextDescriptorOptions {
  readonly id?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L58)

### ContextResolverOptions (interface)

Inputs available to a dynamic constant resolver.

**Example**

```ts
const options: ContextResolverOptions = { env: {}, signal, log };
```

**Signature**

```ts
export interface ContextResolverOptions {
  readonly env: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly log: PublicLogger;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L8)

### PromptDescriptor (interface)

Immutable descriptor for one prompt.

**Example**

```ts
const descriptor: PromptDescriptor = definePrompt("Be concise.");
```

**Signature**

```ts
export interface PromptDescriptor<Value extends PromptValue = PromptValue> extends DescriptorBase<
  "prompt",
  string
> {
  readonly value: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L48)

### PromptValue (type alias)

Prompt text or an ordered list of prompt fragments.

**Example**

```ts
const prompt: PromptValue = ["Be concise.", "Use tools."];
```

**Signature**

```ts
type PromptValue = string | readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L43)

### ResolvedConstants (type alias)

Resolved values inferred from a constants descriptor.

**Example**

```ts
type Values = ResolvedConstants<typeof constants>;
```

**Signature**

```ts
type ResolvedConstants<Descriptor extends ConstantsDescriptor> = {
  readonly [Key in keyof Descriptor["values"]]: ResolveConstant<Descriptor["values"][Key]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L65)

### ResolvedPrompt (type alias)

Resolved prompt text inferred from a prompt descriptor.

**Example**

```ts
type Text = ResolvedPrompt<typeof prompt>;
```

**Signature**

```ts
type ResolvedPrompt<Descriptor extends PromptDescriptor> = Descriptor["value"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-descriptors.types.ts#L72)

## `context-resolution-service.ts`

### AppConstantRunner (class)

Replaceable boundary for dynamic constant callback execution.

**Example**

```ts
Effect.provide(resolver.resolveEffect(context), AppConstantRunnerLive);
```

**Signature**

```ts
declare class AppConstantRunner
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolution-service.ts#L8)

### AppConstantRunnerLive

Live runner that propagates Effect interruption into callback AbortSignals.

**Example**

```ts
Effect.provide(resolver.resolveEffect(context), AppConstantRunnerLive);
```

**Signature**

```ts
declare const AppConstantRunnerLive: Layer.Layer<AppConstantRunner, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolution-service.ts#L15)

### AppConstantRunnerPromiseLive

Compatibility runner that passes the caller's exact signal to callbacks.

**Signature**

```ts
declare const AppConstantRunnerPromiseLive: Layer.Layer<AppConstantRunner, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolution-service.ts#L27)

### AppConstantRunnerService

**Signature**

```ts
declare const AppConstantRunnerService: AppConstantRunnerService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolution-service.ts#L4)

## `context-resolution-service.types.ts`

### AppConstantRunnerService (interface)

Replaceable execution boundary for dynamic constant callbacks.

**Example**

```ts
const runner: AppConstantRunnerService = { run: () => Effect.succeed("eu") };
```

**Signature**

```ts
export interface AppConstantRunnerService {
  /** Invokes a dynamic constant resolver.
   * @param resolver - User supplied constant callback.
   * @param options - Environment, logger, and caller signal available to the callback.
   * @returns The callback result or ContextResolutionFailure.
   * @example runner.run(() => "eu", { env: {}, log });
   */
  readonly run: (
    resolver: ConstantResolver,
    options: {
      readonly env: Readonly<Record<string, unknown>>;
      readonly log: PublicLogger;
      readonly signal: AbortSignal;
    },
  ) => Effect.Effect<unknown, ContextResolutionFailure>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolution-service.types.ts#L9)

## `context-resolver.ts`

### "./context-resolver.types.js" (namespace export)

Re-exports all named exports from the "./context-resolver.types.js" module.

**Signature**

```ts
export * from "./context-resolver.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.ts#L12)

### ContextResolutionFailure (class)

Expected context registration or resolution failure with its original cause.

**Example**

```ts
if (error._tag === "ContextResolutionFailure") console.error(error.message);
```

**Signature**

```ts
declare class ContextResolutionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.ts#L16)

### createApplicationContextResolver

Builds a context resolver synchronously for existing application callers.

**Throws**

TypeError when constant names collide.

**Example**

```ts
createApplicationContextResolver({ env: {} });
```

**Signature**

```ts
declare const createApplicationContextResolver: (
  options: ApplicationContextOptions,
) => ApplicationContextResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.ts#L111)

### createApplicationContextResolverEffect

Builds an application context resolver in Effect.

**Example**

```ts
Effect.runSync(createApplicationContextResolverEffect({ env: {} }));
```

**Signature**

```ts
declare const createApplicationContextResolverEffect: (
  options: ApplicationContextOptions,
) => Effect.Effect<ApplicationContextResolver, ContextResolutionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.ts#L25)

## `context-resolver.types.ts`

### ApplicationContextOptions (interface)

Static and dynamic descriptor inputs for one context resolver.

**Example**

```ts
const options: ApplicationContextOptions = { env: {} };
```

**Signature**

```ts
export interface ApplicationContextOptions {
  readonly constants?: Readonly<Record<string, ConstantsDescriptor>>;
  readonly prompts?: Readonly<Record<string, PromptDescriptor>>;
  readonly env: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.types.ts#L14)

### ApplicationContextResolver (interface)

Resolves the current application constants and prompts.

**Example**

```ts
const resolver: ApplicationContextResolver = createApplicationContextResolver({ env: {} });
```

**Signature**

```ts
export interface ApplicationContextResolver {
  /** Resolves values in Effect with a replaceable constant runner.
   * @param options - Logger and cancellation signal.
   * @returns Resolved values or ContextResolutionFailure; requires AppConstantRunner.
   * @example Effect.runPromise(resolver.resolveEffect(context).pipe(Effect.provide(AppConstantRunnerLive)));
   */
  readonly resolveEffect: (
    options: ApplicationResolveOptions,
  ) => Effect.Effect<ResolvedApplicationContext, ContextResolutionFailure, AppConstantRunner>;
  /** Promise compatibility adapter for application handlers.
   * @param options - Logger and cancellation signal.
   * @returns Resolved values or a rejection with the original resolver error.
   * @example await resolver.resolve({ signal, log });
   */
  readonly resolve: (options: ApplicationResolveOptions) => Promise<ResolvedApplicationContext>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.types.ts#L39)

### ApplicationResolveOptions (interface)

Invocation inputs required to resolve dynamic constants.

**Example**

```ts
const context: ApplicationResolveOptions = { signal, log };
```

**Signature**

```ts
export interface ApplicationResolveOptions {
  readonly signal: AbortSignal;
  readonly log: PublicLogger;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.types.ts#L23)

### ResolvedApplicationContext (interface)

Context values produced by a resolver invocation.

**Example**

```ts
const constants = resolved.constants;
```

**Signature**

```ts
export interface ResolvedApplicationContext {
  readonly constants: Readonly<Record<string, unknown>>;
  readonly prompts: Readonly<Record<string, PromptValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/context-resolver.types.ts#L31)

## `define-app.ts`

Constructs immutable application descriptors without acquiring providers or
optional tools. Shared bridge validation rejects obsolete inspection settings;
the synchronous facade preserves original validation errors for authors.

### defineApp

Defines one immutable application topology synchronously.

**Throws**

The original validation error for invalid options.

**Example**

```ts
import { defineApp } from "@relkit/app";
import { defineEnv } from "@relkit/config";
const app = defineApp({ env: defineEnv({}), server: { port: 3000 } });
```

**Signature**

```ts
declare const defineApp: <
  const Shape extends EnvShape,
  const Providers extends AppProviderInputs,
  const Exporters extends TelemetryExporterMap = Readonly<
    Record<string, TelemetryExporterDescriptor<string, string, object>>
  >,
>(
  options: DefineAppOptions<Shape, Providers, Exporters>,
) => ApplicationDescriptor<Shape, Providers, Exporters>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.ts#L127)

Since v0.2.0

### "./define-app.types.js" (namespace export)

Re-exports all named exports from the "./define-app.types.js" module.

**Signature**

```ts
export * from "./define-app.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.ts#L30)

### APP_PROVIDER_CAPABILITIES

**Signature**

```ts
declare const APP_PROVIDER_CAPABILITIES: readonly [
  "bucket",
  "cache",
  "job",
  "event",
  "model",
  "realtime",
  "agent-state",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.ts#L31)

### defineAppEffect

Defines one immutable application topology in Effect.

**Example**

```ts
Effect.runSync(defineAppEffect({ env: defineEnv({}) }));
```

**Signature**

```ts
declare const defineAppEffect: <
  const Shape extends EnvShape,
  const Providers extends AppProviderInputs,
  const Exporters extends TelemetryExporterMap = Readonly<
    Record<string, TelemetryExporterDescriptor<string, string, object>>
  >,
>(
  options: DefineAppOptions<Shape, Providers, Exporters>,
) => Effect.Effect<ApplicationDescriptor<Shape, Providers, Exporters>, AppValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.ts#L54)

## `define-app.types.ts`

### ApiDocsConfig

**Signature**

```ts
declare const ApiDocsConfig: ApiDocsConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L13)

### AppCompatibilityConfig

**Signature**

```ts
declare const AppCompatibilityConfig: AppCompatibilityConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L16)

### AppDeploymentConfig (type alias)

JSON deployment metadata attached to the application descriptor.

**Example**

```ts
const deployment: AppDeploymentConfig = { engine: "pulumi" };
```

**Signature**

```ts
type AppDeploymentConfig = Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L34)

### AppProviderCapability

**Signature**

```ts
declare const AppProviderCapability:
  "bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L19)

### AppProviderDefaults

**Signature**

```ts
declare const AppProviderDefaults: AppProviderDefaults<Providers>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L21)

### AppProviderInputs

**Signature**

```ts
declare const AppProviderInputs: AppProviderInputs;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L20)

### AppTelemetryConfig (type alias)

Application telemetry settings parameterized by exporters.

**Example**

```ts
const telemetry: AppTelemetryConfig = { redaction: { mode: "off" } };
```

**Signature**

```ts
type AppTelemetryConfig<Exporters extends TelemetryExporterMap = TelemetryExporterMap> =
  TelemetryConfiguration<Exporters>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L28)

### ApplicationDescriptor (type alias)

Immutable normalized application descriptor returned by `defineApp`.

**Example**

```ts
const descriptor: ApplicationDescriptor = defineApp({ env: defineEnv({}) });
```

**Signature**

```ts
type ApplicationDescriptor<
  Shape extends EnvShape = EnvShape,
  Providers extends AppProviderInputs = AppProviderInputs,
  Exporters extends TelemetryExporterMap = TelemetryExporterMap,
> = DescriptorBase<"app", string> &
  NormalizedProviders<Providers> & {
    readonly env: EnvDefinition<Shape>;
    readonly defaults: NormalizedAppProviderDefaults<Providers>;
    readonly compatibility: { readonly legacyJobs: boolean };
    readonly telemetry?: AppTelemetryConfig<Exporters>;
    readonly server?: ServerConfig;
    readonly inspector?: InspectorConfig;
    readonly deployment?: AppDeploymentConfig;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L58)

### DefineAppOptions (type alias)

Authored application topology and runtime settings.

**Example**

```ts
const options: DefineAppOptions<{}, {}> = { env: defineEnv({}) };
```

**Signature**

```ts
type DefineAppOptions<
  Shape extends EnvShape,
  Providers extends AppProviderInputs,
  Exporters extends TelemetryExporterMap = TelemetryExporterMap,
> = DescriptorMetadata &
  Providers & {
    readonly id?: string;
    readonly env: EnvDefinition<Shape>;
    readonly defaults?: AppProviderDefaults<Providers>;
    readonly compatibility?: AppCompatibilityConfig;
    readonly telemetry?: AppTelemetryConfig<Exporters>;
    readonly server?: ServerConfig;
    readonly inspector?: InspectorConfig;
    readonly deployment?: AppDeploymentConfig;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L39)

### InspectorConfig

**Signature**

```ts
declare const InspectorConfig: InspectorConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L15)

### NormalizedAppProviderDefaults

**Signature**

```ts
declare const NormalizedAppProviderDefaults: Readonly<{
  bucket?: ProfileFor<Providers, "bucket">;
  cache?: ProfileFor<Providers, "cache">;
  job?: ProfileFor<Providers, "job">;
  event?: ProfileFor<Providers, "event">;
  model?: ProfileFor<Providers, "model">;
  realtime?: ProfileFor<Providers, "realtime">;
  "agent-state"?: ProfileFor<Providers, "agent-state">;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L22)

### ServerConfig

**Signature**

```ts
declare const ServerConfig: ServerConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/define-app.types.ts#L14)

## `events.ts`

### "@relkit/events" (namespace export)

Re-exports all named exports from the "@relkit/events" module.

**Signature**

```ts
export * from "@relkit/events";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/events.ts#L1)

## `functions.ts`

### "@relkit/functions" (namespace export)

Re-exports all named exports from the "@relkit/functions" module.

**Signature**

```ts
export * from "@relkit/functions";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/functions.ts#L1)

## `index.ts`

### "./config.js" (namespace export)

Re-exports all named exports from the "./config.js" module.

**Signature**

```ts
export * from "./config.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L1)

### "./context-descriptors.js" (namespace export)

Re-exports all named exports from the "./context-descriptors.js" module.

**Signature**

```ts
export * from "./context-descriptors.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L2)

### "./context-resolver.js" (namespace export)

Re-exports all named exports from the "./context-resolver.js" module.

**Signature**

```ts
export * from "./context-resolver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L3)

### "./tasks.js" (namespace export)

Re-exports all named exports from the "./tasks.js" module.

**Signature**

```ts
export * from "./tasks.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L14)

### "@relkit/agents" (namespace export)

Re-exports all named exports from the "@relkit/agents" module.

**Signature**

```ts
export * from "@relkit/agents";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L5)

### "@relkit/buckets" (namespace export)

Re-exports all named exports from the "@relkit/buckets" module.

**Signature**

```ts
export * from "@relkit/buckets";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L6)

### "@relkit/cache" (namespace export)

Re-exports all named exports from the "@relkit/cache" module.

**Signature**

```ts
export * from "@relkit/cache";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L7)

### "@relkit/events" (namespace export)

Re-exports all named exports from the "@relkit/events" module.

**Signature**

```ts
export * from "@relkit/events";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L8)

### "@relkit/functions" (namespace export)

Re-exports all named exports from the "@relkit/functions" module.

**Signature**

```ts
export * from "@relkit/functions";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L9)

### "@relkit/jobs" (namespace export)

Re-exports all named exports from the "@relkit/jobs" module.

**Signature**

```ts
export * from "@relkit/jobs";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L12)

### "@relkit/realtime" (namespace export)

Re-exports all named exports from the "@relkit/realtime" module.

**Signature**

```ts
export * from "@relkit/realtime";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L15)

### "@relkit/routes" (namespace export)

Re-exports all named exports from the "@relkit/routes" module.

**Signature**

```ts
export * from "@relkit/routes";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L16)

### "@relkit/services" (namespace export)

Re-exports all named exports from the "@relkit/services" module.

**Signature**

```ts
export * from "@relkit/services";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L17)

### "@relkit/tools" (namespace export)

Re-exports all named exports from the "@relkit/tools" module.

**Signature**

```ts
export * from "@relkit/tools";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L18)

### AppConstantRunner

**Signature**

```ts
declare const AppConstantRunner: typeof AppConstantRunner;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L4)

### AppConstantRunnerLive

**Signature**

```ts
declare const AppConstantRunnerLive: Layer<AppConstantRunner, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L4)

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L11)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L11)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L11)

### TaskClientFor

**Signature**

```ts
declare const TaskClientFor: TaskClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L13)

### TaskClients

**Signature**

```ts
declare const TaskClients: TaskClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L13)

### TaskTriggerOptions

**Signature**

```ts
declare const TaskTriggerOptions: TaskTriggerOptions<Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L13)

### bindDescriptorIdentity

**Signature**

```ts
declare const bindDescriptorIdentity: <T extends object>(descriptor: T, id: string) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/index.ts#L10)

## `internal-runtime.ts`

Exposes the framework-owned descriptor identity and application context wiring
needed by emitted hosts, including selected dependency preflight. Re-exports
preserve identity while resolving framework dependencies from their owning app.

### SelectedDependenciesLive

**Signature**

```ts
declare const SelectedDependenciesLive: Layer<SelectedDependencies, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/internal-runtime.ts#L10)

### bindDescriptorIdentity

**Signature**

```ts
declare const bindDescriptorIdentity: <T extends object>(descriptor: T, id: string) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/internal-runtime.ts#L6)

### checkIntegrationDependencies

**Signature**

```ts
declare const checkIntegrationDependencies: (
  plan: RuntimeIntegrationPlan,
  options: {
    readonly projectRoot: string;
    readonly phase: IntegrationDependencyPhase;
    readonly manager?: DependencyPackageManager;
  },
) => Effect<
  import("@relkit/provider/internal/dependencies").InstalledPackageIdentity[][],
  | import("@relkit/provider/internal/dependencies").DependencyResolutionFailure
  | import("@relkit/provider/internal/dependencies").SelectedDependencyFailure,
  SelectedDependencies
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/internal-runtime.ts#L9)

### createApplicationContextResolver

**Signature**

```ts
declare const createApplicationContextResolver: (
  options: ApplicationContextOptions,
) => ApplicationContextResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/internal-runtime.ts#L7)

### initializeIntegration

**Signature**

```ts
declare const initializeIntegration: <Module>(
  packageName: string,
  load: () => Promise<Module>,
) => Effect<Module, SelectedDependencyInitializationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/internal-runtime.ts#L11)

## `jobs-legacy.ts`

### "@relkit/jobs/legacy" (namespace export)

Re-exports all named exports from the "@relkit/jobs/legacy" module.

**Signature**

```ts
export * from "@relkit/jobs/legacy";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/jobs-legacy.ts#L1)

## `jobs.ts`

### "@relkit/jobs" (namespace export)

Re-exports all named exports from the "@relkit/jobs" module.

**Signature**

```ts
export * from "@relkit/jobs";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/jobs.ts#L1)

### RunStatus

**Signature**

```ts
declare const RunStatus: JobRunStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/jobs.ts#L2)

## `realtime.ts`

### "@relkit/realtime" (namespace export)

Re-exports all named exports from the "@relkit/realtime" module.

**Signature**

```ts
export * from "@relkit/realtime";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/realtime.ts#L1)

## `routes.ts`

### "@relkit/routes" (namespace export)

Re-exports all named exports from the "@relkit/routes" module.

**Signature**

```ts
export * from "@relkit/routes";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/routes.ts#L1)

## `schema.ts`

### "@relkit/schema" (namespace export)

Re-exports all named exports from the "@relkit/schema" module.

**Signature**

```ts
export * from "@relkit/schema";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/schema.ts#L1)

## `services.ts`

### "@relkit/services" (namespace export)

Re-exports all named exports from the "@relkit/services" module.

**Signature**

```ts
export * from "@relkit/services";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/services.ts#L1)

## `tasks.ts`

### DefineTaskOptions

**Signature**

```ts
declare const DefineTaskOptions: DefineTaskOptions<
  Id,
  Version,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema,
  Streams,
  Execution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L3)

### JobDescriptorForThisTask

**Signature**

```ts
declare const JobDescriptorForThisTask: JobDescriptorForThisTask<Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L4)

### NormalizedTaskRetryPolicy

**Signature**

```ts
declare const NormalizedTaskRetryPolicy: NormalizedTaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L5)

### RunResultOptions

**Signature**

```ts
declare const RunResultOptions: RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L6)

### ServerTriggerOptions

**Signature**

```ts
declare const ServerTriggerOptions: ServerTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L7)

### TaskAuthContext

**Signature**

```ts
declare const TaskAuthContext: TaskAuthContext<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L8)

### TaskCallerInput

**Signature**

```ts
declare const TaskCallerInput: TaskCallerInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L9)

### TaskCanonicalInput

**Signature**

```ts
declare const TaskCanonicalInput: TaskCanonicalInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L10)

### TaskConcurrency

**Signature**

```ts
declare const TaskConcurrency: TaskConcurrency<InputKey>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L11)

### TaskContext

**Signature**

```ts
declare const TaskContext: TaskContext<Execution, Dependencies, ProgressSchema, Streams, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L12)

### TaskContextBase

**Signature**

```ts
declare const TaskContextBase: TaskContextBase<Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L13)

### TaskDependencies

**Signature**

```ts
declare const TaskDependencies: TaskDependencies;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L14)

### TaskDescriptor

**Signature**

```ts
declare const TaskDescriptor: TaskDescriptor<
  Id,
  Version,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema,
  Streams,
  Execution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L15)

### TaskDescriptorAny

**Signature**

```ts
declare const TaskDescriptorAny: TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L16)

### TaskExecution

**Signature**

```ts
declare const TaskExecution: TaskExecution;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L17)

### TaskFailureHook

**Signature**

```ts
declare const TaskFailureHook: TaskFailureHook<Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L18)

### TaskHandler

**Signature**

```ts
declare const TaskHandler: TaskHandler<
  InputSchema,
  OutputSchema,
  Execution,
  Dependencies,
  Errors,
  ProgressSchema,
  Streams,
  Publishes
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L19)

### TaskHandlerResult

**Signature**

```ts
declare const TaskHandlerResult: TaskHandlerResult<Output, Errors>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L20)

### TaskHookContext

**Signature**

```ts
declare const TaskHookContext: TaskHookContext<Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L21)

### TaskInput

**Signature**

```ts
declare const TaskInput: TaskInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L22)

### TaskLogging

**Signature**

```ts
declare const TaskLogging: TaskLogging;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L23)

### TaskOutput

**Signature**

```ts
declare const TaskOutput: TaskOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L24)

### TaskProgressEmitter

**Signature**

```ts
declare const TaskProgressEmitter: TaskProgressEmitter<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L27)

### TaskProgressInput

**Signature**

```ts
declare const TaskProgressInput: TaskProgressInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L25)

### TaskProgressOutput

**Signature**

```ts
declare const TaskProgressOutput: TaskProgressOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L26)

### TaskRawHandlerOutput

**Signature**

```ts
declare const TaskRawHandlerOutput: TaskRawHandlerOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L42)

### TaskResources

**Signature**

```ts
declare const TaskResources: TaskResources;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L28)

### TaskRetryPolicy

**Signature**

```ts
declare const TaskRetryPolicy: TaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L29)

### TaskRunContext

**Signature**

```ts
declare const TaskRunContext: TaskRunContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L30)

### TaskSleepOptions

**Signature**

```ts
declare const TaskSleepOptions: TaskSleepOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L31)

### TaskStartHook

**Signature**

```ts
declare const TaskStartHook: TaskStartHook<InputSchema, Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L32)

### TaskStreamEmitter

**Signature**

```ts
declare const TaskStreamEmitter: TaskStreamEmitter<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L33)

### TaskStreamEmitters

**Signature**

```ts
declare const TaskStreamEmitters: TaskStreamEmitters<Streams>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L34)

### TaskStreamFrames

**Signature**

```ts
declare const TaskStreamFrames: TaskStreamFrames<Streams>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L35)

### TaskStreamInput

**Signature**

```ts
declare const TaskStreamInput: TaskStreamInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L37)

### TaskStreamItem

**Signature**

```ts
declare const TaskStreamItem: TaskStreamItem<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L36)

### TaskStreamOutput

**Signature**

```ts
declare const TaskStreamOutput: TaskStreamOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L38)

### TaskStreamSchemas

**Signature**

```ts
declare const TaskStreamSchemas: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L39)

### TaskSuccessHook

**Signature**

```ts
declare const TaskSuccessHook: TaskSuccessHook<OutputSchema, Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L40)

### TaskTriggerOptions

**Signature**

```ts
declare const TaskTriggerOptions: TaskTriggerOptions<Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L41)

### TaskValidatedOutput

**Signature**

```ts
declare const TaskValidatedOutput: TaskValidatedOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L43)

### TriggerOptions

**Signature**

```ts
declare const TriggerOptions: TriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L44)

### assertTaskDescriptor

**Signature**

```ts
declare const assertTaskDescriptor: (value: unknown) => asserts value is TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L1)

### defineTask

**Signature**

```ts
declare const defineTask: <
  const Id extends string,
  const Version extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Dependencies extends TaskDependencies = {},
  const Errors extends readonly ErrorDescriptorAny[] = readonly [],
  const Publishes extends readonly PublishedEventName[] = readonly [],
  const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  const Streams extends TaskStreamSchemas = {},
  const Execution extends TaskExecution = "durable",
>(
  options: DefineTaskOptions<
    Id,
    Version,
    InputSchema,
    OutputSchema,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema,
    Streams,
    Execution
  >,
) => TaskDescriptor<
  Id,
  Version,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema,
  Streams,
  Execution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L1)

### isTaskDescriptor

**Signature**

```ts
declare const isTaskDescriptor: (value: unknown) => value is TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tasks.ts#L1)

## `tools.ts`

### "@relkit/tools" (namespace export)

Re-exports all named exports from the "@relkit/tools" module.

**Signature**

```ts
export * from "@relkit/tools";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/app/src/tools.ts#L1)

## `agent-content.ts`

Browser-safe message snapshot shown for one agent run.

### AgentProgressScope (type alias)

Identifies whether progress belongs to a run or a particular tool call.

**Signature**

```ts
type AgentProgressScope =
  | { readonly scope: "run"; readonly toolCallId?: never; readonly toolId?: never }
  | { readonly scope: "tool"; readonly toolCallId: string; readonly toolId: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-content.ts#L36)

### BrowserMessage (interface)

Browser-safe message snapshot shown for one agent run.

**Signature**

```ts
export interface BrowserMessage {
  readonly messageId: string;
  readonly runId?: string;
  readonly role: "user" | "assistant" | "tool";
  readonly parts: readonly BrowserMessagePart[];
  readonly createdAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-content.ts#L2)

### BrowserMessagePart (type alias)

Text, tool, or progress content carried by a browser message.

**Signature**

```ts
type BrowserMessagePart =
  | {
      readonly partId: string;
      readonly kind: "text";
      readonly text: string;
      readonly state?: "streaming" | "complete";
    }
  | {
      readonly partId: string;
      readonly kind: "tool";
      readonly toolCallId: string;
      readonly toolId: string;
      readonly state: ToolPartState;
      readonly inputText?: string;
      readonly input?: unknown;
      readonly output?: unknown;
      readonly value?: unknown;
    }
  | ({
      readonly partId: string;
      readonly kind: "progress";
      readonly value: unknown;
    } & AgentProgressScope);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-content.ts#L11)

### ToolPartState (type alias)

Lifecycle state of a tool part in a streamed browser message.

**Signature**

```ts
type ToolPartState =
  | "started"
  | "input-streaming"
  | "input-ready"
  | "approval-required"
  | "running"
  | "succeeded"
  | "failed"
  | "denied";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-content.ts#L41)

## `agent-events.ts`

### AgentClientEvent (type alias)

All event variants understood by an agent client.

**Signature**

```ts
type AgentClientEvent =
  | (AgentClientEventBase & { readonly kind: "message-updated"; readonly message: BrowserMessage })
  | AgentProgressEvent
  | AgentToolEvent
  | (AgentClientEventBase & {
      readonly kind: "execution-event";
      readonly value: AgentExecutionEvent;
    })
  | (AgentClientEventBase & {
      readonly kind: "approval" | "control" | "run-finished" | "run-interrupted";
      readonly value: unknown;
    });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-events.ts#L40)

### AgentObservation (type alias)

Event, current snapshot, or continuity gap returned by observation.

**Signature**

```ts
type AgentObservation =
  | { readonly kind: "event"; readonly event: AgentClientEvent }
  | { readonly kind: "snapshot"; readonly snapshot: ThreadSnapshot }
  | {
      readonly kind: "gap";
      readonly reason: "expired" | "foreign" | "future" | "session" | "provider-reset";
      readonly snapshot: ThreadSnapshot;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-events.ts#L54)

### AgentProgressEvent (type alias)

Progress event scoped to a run or tool invocation.

**Signature**

```ts
type AgentProgressEvent = AgentClientEventBase & {
  readonly kind: "progress";
  readonly progressId: string;
  readonly messageId?: string;
  readonly value: unknown;
} & AgentProgressScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-events.ts#L32)

### AgentToolEvent (type alias)

Tool lifecycle event delivered to an agent client.

**Signature**

```ts
type AgentToolEvent = AgentClientEventBase & {
  readonly messageId: string;
  readonly partId: string;
  readonly toolCallId: string;
  readonly toolId: string;
} & (
    | { readonly kind: "tool-started" }
    | { readonly kind: "tool-input"; readonly input: string }
    | { readonly kind: "tool-input-ready"; readonly input: unknown }
    | { readonly kind: "tool-approval-required" }
    | { readonly kind: "tool-executing" }
    | { readonly kind: "tool-succeeded"; readonly output: unknown }
    | { readonly kind: "tool-failed" }
    | { readonly kind: "tool-denied" }
  );
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-events.ts#L15)

## `agent-execution.ts`

One ordered native execution event within an agent run.

### AgentExecutionEvent (interface)

One ordered native execution event within an agent run.

**Signature**

```ts
export interface AgentExecutionEvent {
  readonly nativeSequence: number;
  readonly kind: string;
  readonly scope: readonly string[];
  readonly occurredAt: string;
  readonly agent?: string;
  readonly parent?: {
    readonly kind: "tool";
    readonly toolCallId: string;
    readonly toolId: string;
  };
  readonly node?: string;
  readonly value?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-execution.ts#L2)

### AgentExecutionSnapshot (interface)

Latest public state of a native execution scope.

**Signature**

```ts
export interface AgentExecutionSnapshot {
  readonly scope: readonly string[];
  readonly agent?: string;
  readonly parent?: AgentExecutionEvent["parent"];
  readonly node?: string;
  readonly values?: unknown;
  readonly status: "running" | "waiting" | "succeeded" | "failed" | "cancelled";
  readonly lastEventSequence: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-execution.ts#L18)

## `agent-state-control-requests.types.ts`

Defines scoped control claims, settlement, and continuation admission requests.

### AcceptControlRequest (interface)

**Signature**

```ts
export interface AcceptControlRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly semanticDigest: string;
  readonly threadId: string;
  readonly runId: string;
  readonly kind: "steer" | "follow-up" | "stop" | "approve";
  readonly publicPayload: unknown;
  readonly acceptedAt: string;
  readonly receiptExpiresAt: string;
  readonly limits: ControlLimits;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L10)

### AdmitContinuationRequest (type alias)

**Signature**

```ts
type AdmitContinuationRequest = ContinuationAdmission &
  (
    | {
        readonly kind: "approval";
        readonly decisions: Readonly<Record<string, "approve" | "deny">>;
      }
    | { readonly kind: "resume"; readonly waitingRevision: string }
  );
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L108)

### ClaimControlRequest (interface)

**Signature**

```ts
export interface ClaimControlRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly operationId: OperationId;
  readonly workerId: string;
  readonly generationId: string;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L51)

### ContinuationIdentity (interface)

**Signature**

```ts
export interface ContinuationIdentity {
  readonly threadId: string;
  readonly interruptedRunId: string;
  readonly interruptSetDigest: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L95)

### ControlLimits (interface)

**Signature**

```ts
export interface ControlLimits {
  readonly maxQueuedPerRun: number;
  readonly maxQueuedPerApplication: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L5)

### ControlPage (interface)

**Signature**

```ts
export interface ControlPage {
  readonly operationIds: readonly OperationId[];
  readonly nextSequence: string;
  readonly hasMore: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L37)

### LookupContinuationReceiptRequest (interface)

**Signature**

```ts
export interface LookupContinuationReceiptRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly interruptedRunId?: string;
  readonly interruptSetDigest?: string;
  readonly semanticDigest: string;
  readonly now: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L117)

### LookupControlReceiptRequest (interface)

**Signature**

```ts
export interface LookupControlReceiptRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly semanticDigest: string;
  readonly now: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L22)

### MarkControlEffectStartedRequest (interface)

**Signature**

```ts
export interface MarkControlEffectStartedRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ControlClaim;
  readonly operationId: OperationId;
  readonly downstreamOperationId?: OperationId;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L67)

### ReadControlsRequest (interface)

**Signature**

```ts
export interface ReadControlsRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly afterSequence?: string;
  readonly limit: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L30)

### RecoverAbandonedControlRequest (interface)

**Signature**

```ts
export interface RecoverAbandonedControlRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly operationId: OperationId;
  readonly expectedClaimId: string;
  readonly expectedFence: number;
  readonly recoveredAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L86)

### RenewControlClaimRequest (interface)

**Signature**

```ts
export interface RenewControlClaimRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ControlClaim;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L60)

### SettleControlRequest (interface)

**Signature**

```ts
export interface SettleControlRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ControlClaim;
  readonly operationId: OperationId;
  readonly status: "applied" | "rejected" | "cancelled";
  readonly effect: "not-started" | "confirmed" | "unknown";
  readonly downstreamOperationId?: OperationId;
  readonly settledAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L75)

### WaitForControlsRequest (interface)

**Signature**

```ts
export interface WaitForControlsRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly afterSequence: string;
  readonly deadlineMs: number;
  readonly signal: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-control-requests.types.ts#L43)

## `agent-state-provider.types.ts`

Defines the SDK-independent durable thread, journal, control, and continuation provider port.

### AgentStateProvider (interface)

**Signature**

```ts
export interface AgentStateProvider {
  getEpoch(): Promise<string>;
  createThread(request: CreateThreadRequest): Promise<CreateThreadReceipt>;
  listThreads(request: ListThreadsRequest): Promise<ThreadList>;
  loadThread(request: LoadThreadRequest): Promise<ThreadSnapshot>;
  readSnapshotHistory(request: ReadSnapshotHistoryRequest): Promise<SnapshotHistoryPage>;
  acceptRun(request: AcceptRunRequest): Promise<AcceptRunReceipt>;
  lookupRunReceipt(request: LookupRunReceiptRequest): Promise<RunReceiptLookup>;
  readJournal(request: ReadJournalRequest): Promise<JournalPage>;
  waitForJournal(request: WaitForJournalRequest): Promise<void>;
  claimRun(request: ClaimRunRequest): Promise<ExecutionClaim>;
  renewRunClaim(request: RenewRunClaimRequest): Promise<ExecutionClaim>;
  appendJournal(request: AppendJournalRequest): Promise<JournalReceipt>;
  completeRun(request: CompleteRunRequest): Promise<CompletionReceipt>;
  suspendRun(request: SuspendRunRequest): Promise<SuspensionReceipt>;
  interruptOwnedRun(request: InterruptOwnedRunRequest): Promise<InterruptionReceipt>;
  acceptControl(request: AcceptControlRequest): Promise<ControlReceipt>;
  lookupControlReceipt(request: LookupControlReceiptRequest): Promise<ControlReceiptLookup>;
  readControls(request: ReadControlsRequest): Promise<ControlPage>;
  waitForControls(request: WaitForControlsRequest): Promise<void>;
  claimControl(request: ClaimControlRequest): Promise<ControlClaim>;
  renewControlClaim(request: RenewControlClaimRequest): Promise<ControlClaim>;
  markControlEffectStarted(request: MarkControlEffectStartedRequest): Promise<ControlReceipt>;
  settleControl(request: SettleControlRequest): Promise<ControlReceipt>;
  recoverAbandonedControl(request: RecoverAbandonedControlRequest): Promise<ControlReceipt>;
  admitContinuation(request: AdmitContinuationRequest): Promise<ContinuationReceipt>;
  lookupContinuationReceipt(
    request: LookupContinuationReceiptRequest,
  ): Promise<ContinuationReceiptLookup>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-provider.types.ts#L50)

## `agent-state-receipts.types.ts`

Defines durable thread, run, journal, control, and continuation operation receipts.

### AcceptRunReceipt (interface)

**Signature**

```ts
export interface AcceptRunReceipt {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly status: "accepted";
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L17)

### CompletionReceipt (interface)

**Signature**

```ts
export interface CompletionReceipt {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly status: Extract<RunStatus, "succeeded" | "failed" | "cancelled">;
  readonly checkpoint: JournalCheckpoint;
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L31)

### ContinuationReceipt (interface)

**Signature**

```ts
export interface ContinuationReceipt {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly interruptedRunId: string;
  readonly runId: string;
  readonly interruptSetDigest: string;
  readonly waitingRevision?: string;
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L65)

### ContinuationReceiptLookup (type alias)

**Signature**

```ts
type ContinuationReceiptLookup = ReceiptLookup<ContinuationReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L77)

### ControlReceipt (interface)

**Signature**

```ts
export interface ControlReceipt {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly status: ControlStatus;
  readonly effect: ControlEffectOutcome;
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L56)

### ControlReceiptLookup (type alias)

**Signature**

```ts
type ControlReceiptLookup = ReceiptLookup<ControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L76)

### CreateThreadReceipt (interface)

**Signature**

```ts
export interface CreateThreadReceipt {
  readonly threadId: string;
  readonly ownerScope: string;
  readonly createdAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L11)

### InterruptionReceipt (interface)

**Signature**

```ts
export interface InterruptionReceipt {
  readonly threadId: string;
  readonly runId: string;
  readonly status: "worker-interrupted";
  readonly checkpoint: JournalCheckpoint;
  readonly changed: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L40)

### JournalReceipt (interface)

**Signature**

```ts
export interface JournalReceipt {
  readonly recordId: string;
  readonly checkpoint: JournalCheckpoint;
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L25)

### RunReceiptLookup (type alias)

**Signature**

```ts
type RunReceiptLookup = ReceiptLookup<AcceptRunReceipt | CompletionReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L75)

### SuspensionReceipt (interface)

**Signature**

```ts
export interface SuspensionReceipt {
  readonly threadId: string;
  readonly runId: string;
  readonly status: "waiting";
  readonly checkpoint: JournalCheckpoint;
  readonly waiting: AgentWaitingState;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-receipts.types.ts#L48)

## `agent-state-thread-requests.types.ts`

Defines bounded thread, history, journal, and execution-claim requests for state providers.

### AcceptRunRequest (interface)

**Signature**

```ts
export interface AcceptRunRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly semanticDigest: string;
  readonly threadId: string;
  readonly owner: RunOwner;
  readonly input: unknown;
  readonly inputDigest: string;
  readonly acceptedAt: string;
  readonly receiptExpiresAt: string;
  readonly limits: AgentStateLimits;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L60)

### AgentStateLimits (interface)

**Signature**

```ts
export interface AgentStateLimits {
  readonly maxSnapshotBytes: number;
  readonly maxHistoryPageBytes: number;
  readonly maxJournalRecordBytes: number;
  readonly maxJournalBytesPerThread: number;
  readonly maxStateBytesPerApplication: number;
  readonly maxThreadsPerPrincipal: number;
  readonly maxActiveRunsPerPrincipal: number;
  readonly maxActiveRunsPerApplication: number;
  readonly terminalReserveBytes: number;
  readonly terminalReserveRecords: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L14)

### AppendJournalRequest (interface)

**Signature**

```ts
export interface AppendJournalRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ExecutionClaim;
  readonly operationId: OperationId;
  readonly semanticDigest: string;
  readonly record: Omit<JournalRecord, "checkpoint">;
  readonly limits: AgentStateLimits;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L116)

### ClaimRunRequest (interface)

**Signature**

```ts
export interface ClaimRunRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly workerId: string;
  readonly generationId: string;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L101)

### CompleteRunRequest (interface)

**Signature**

```ts
export interface CompleteRunRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly semanticDigest: string;
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ExecutionClaim;
  readonly outcome: "succeeded" | "failed" | "cancelled";
  readonly terminalRecord: Omit<JournalRecord, "checkpoint">;
  readonly settledAt: string;
  readonly receiptExpiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L126)

### CreateThreadRequest (interface)

**Signature**

```ts
export interface CreateThreadRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly semanticDigest: string;
  readonly now: string;
  readonly limits: AgentStateLimits;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L27)

### InterruptOwnedRunRequest (interface)

**Signature**

```ts
export interface InterruptOwnedRunRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly expectedOwner: RunOwner;
  readonly expectedClaimId: string;
  readonly expectedFence: number;
  readonly reason: "claim-expired" | "generation-unavailable" | "process-lost";
  readonly interruptedAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L147)

### JournalPage (interface)

**Signature**

```ts
export interface JournalPage {
  readonly records: readonly JournalRecord[];
  readonly checkpoint: JournalCheckpoint;
  readonly hasMore: boolean;
  readonly gap?: "expired" | "foreign" | "future" | "session" | "provider-reset";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L87)

### ListThreadsRequest (interface)

**Signature**

```ts
export interface ListThreadsRequest extends AgentRequestScope {
  readonly limit: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L40)

### LoadThreadRequest (interface)

**Signature**

```ts
export interface LoadThreadRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly maxEncodedBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L35)

### LookupRunReceiptRequest (interface)

**Signature**

```ts
export interface LookupRunReceiptRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId?: string;
  readonly runId?: string;
  readonly semanticDigest: string;
  readonly now: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L72)

### ReadJournalRequest (interface)

**Signature**

```ts
export interface ReadJournalRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly after: JournalCheckpoint;
  readonly limit: number;
  readonly maxEncodedBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L80)

### ReadSnapshotHistoryRequest (interface)

**Signature**

```ts
export interface ReadSnapshotHistoryRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly snapshotId: string;
  readonly cursor: string;
  readonly maxEncodedBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L48)

### RenewRunClaimRequest (interface)

**Signature**

```ts
export interface RenewRunClaimRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ExecutionClaim;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L109)

### SnapshotHistoryPage (interface)

**Signature**

```ts
export interface SnapshotHistoryPage {
  readonly messages: readonly BrowserMessage[];
  readonly nextCursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L55)

### SuspendRunRequest (interface)

**Signature**

```ts
export interface SuspendRunRequest extends AgentRequestScope {
  readonly operationId: OperationId;
  readonly threadId: string;
  readonly runId: string;
  readonly claim: ExecutionClaim;
  readonly waiting: Omit<AgentWaitingState, "revision">;
  readonly suspendedAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L138)

### ThreadList (interface)

**Signature**

```ts
export interface ThreadList {
  readonly threads: readonly ThreadListItem[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L44)

### WaitForJournalRequest (interface)

**Signature**

```ts
export interface WaitForJournalRequest extends AgentRequestScope {
  readonly threadId: string;
  readonly after: JournalCheckpoint;
  readonly deadlineMs: number;
  readonly signal: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state-thread-requests.types.ts#L94)

## `agent-state.ts`

### AgentRequestScope (interface)

Authorization and provider scope carried by an agent request.

**Signature**

```ts
export interface AgentRequestScope extends ExpectedClientIdentity {
  readonly applicationId: string;
  readonly environment: string;
  readonly profile: string;
  readonly providerEpoch: string;
  readonly agentId: string;
  readonly ownerScope: string;
  readonly authorizationGrantId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L143)

### AgentRunCompatibility (interface)

Compatibility level available when replaying a run.

**Signature**

```ts
export interface AgentRunCompatibility {
  readonly runtime: "native" | "ai-sdk";
  readonly access: "read-write" | "read-only";
  readonly resumableCheckpoint: boolean;
  readonly protocolVersion?: number;
  readonly schemaVersion?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L58)

### AgentWaitingRequest (interface)

Input and expected response for a paused execution node.

**Signature**

```ts
export interface AgentWaitingRequest {
  readonly node: string;
  readonly value?: unknown;
  readonly response: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L111)

### AgentWaitingState (interface)

Durable collection of requests awaiting external responses.

**Signature**

```ts
export interface AgentWaitingState {
  readonly revision: string;
  readonly runId: string;
  readonly response: JsonValue;
  readonly requests: readonly AgentWaitingRequest[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L117)

### ControlClaim (interface)

Fenced worker lease for applying one control request.

**Signature**

```ts
export interface ControlClaim {
  readonly claimId: string;
  readonly controlId: OperationId;
  readonly workerId: string;
  readonly generationId: string;
  readonly fence: number;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L162)

### ControlEffectOutcome (type alias)

Whether a control's external effect is known to have occurred.

**Signature**

```ts
type ControlEffectOutcome = "not-started" | "confirmed" | "unknown";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L77)

### ControlRecord (interface)

Durable idempotent control request and its application outcome.

**Signature**

```ts
export interface ControlRecord {
  readonly controlId: OperationId;
  readonly runId: string;
  readonly kind: "steer" | "follow-up" | "stop" | "approve";
  readonly semanticDigest: string;
  readonly publicPayload?: unknown;
  readonly status: ControlStatus;
  readonly effect: ControlEffectOutcome;
  readonly acceptedAt: string;
  readonly settledAt?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L79)

### ControlStatus (type alias)

Persistence lifecycle of a control request.

**Signature**

```ts
type ControlStatus = "accepted" | "processing" | "applied" | "rejected" | "cancelled";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L75)

### ExecutionClaim (interface)

Fenced worker lease for executing one run.

**Signature**

```ts
export interface ExecutionClaim {
  readonly claimId: string;
  readonly runId: string;
  readonly workerId: string;
  readonly generationId: string;
  readonly fence: number;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L153)

### JournalCheckpoint (interface)

Provider-scoped cursor for replaying the agent journal.

**Signature**

```ts
export interface JournalCheckpoint {
  readonly applicationId: string;
  readonly environment: string;
  readonly profile: string;
  readonly providerEpoch: string;
  readonly threadId: string;
  readonly sequence: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L91)

### JournalRecord (interface)

One encoded public record in the agent journal.

**Signature**

```ts
export interface JournalRecord {
  readonly recordId: string;
  readonly runId: string;
  readonly kind:
    "message" | "progress" | "approval" | "control" | "terminal" | "interruption" | "event";
  readonly publicValue: unknown;
  readonly checkpoint: JournalCheckpoint;
  readonly encodedBytes: number;
  readonly createdAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L100)

### RunOwner (interface)

Runtime generation and provider scope that own a run.

**Signature**

```ts
export interface RunOwner {
  readonly generationId: string;
  readonly publicFingerprint: string;
  readonly protocolVersion: number;
  readonly schemaVersion: number;
  readonly providerScope: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L21)

### RunStatus (type alias)

Persisted lifecycle state of an agent run.

**Signature**

```ts
type RunStatus =
  | "accepted"
  | "running"
  | "waiting"
  | "approval-interrupted"
  | "stopping"
  | "succeeded"
  | "failed"
  | "cancelled"
  | "worker-interrupted";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L10)

### StoredApproval (interface)

Durable approval decision associated with a run interruption.

**Signature**

```ts
export interface StoredApproval {
  readonly approvalId: string;
  readonly runId: string;
  readonly interruptSetDigest: string;
  readonly interruptSetSize?: number;
  readonly status: "open" | "approved" | "denied" | "cancelled";
  readonly publicRequest: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L66)

### StoredRun (interface)

Durable run state and idempotent submission identity.

**Signature**

```ts
export interface StoredRun extends StoredRunRouting {
  readonly operationId: OperationId;
  readonly status: RunStatus;
  readonly inputDigest: string;
  readonly acceptedAt: string;
  readonly settledAt?: string;
  readonly outcome?: "succeeded" | "failed" | "cancelled" | "worker-interrupted";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L49)

### StoredRunRouting (interface)

Minimal routing data needed to locate a stored run.

**Signature**

```ts
export interface StoredRunRouting {
  readonly runId: string;
  readonly threadId: string;
  readonly owner: RunOwner;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L29)

### StoredThread (interface)

Durable thread metadata stored by the state provider.

**Signature**

```ts
export interface StoredThread {
  readonly threadId: string;
  readonly agentId: string;
  readonly ownerScope: string;
  readonly status: ThreadStatus;
  readonly revision: string;
  readonly createdAt: string;
  readonly updatedAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L35)

### ThreadListItem (interface)

Thread metadata enriched with a client-facing preview.

**Signature**

```ts
export interface ThreadListItem extends StoredThread {
  readonly preview?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L45)

### ThreadSnapshot (interface)

Public thread view rebuilt from current state and journal data.

**Signature**

```ts
export interface ThreadSnapshot {
  readonly snapshotId: string;
  readonly thread: StoredThread;
  readonly activeRun: StoredRunRouting | undefined;
  readonly currentRuns: readonly StoredRun[];
  readonly currentMessages: readonly BrowserMessage[];
  readonly values?: unknown;
  readonly output?: unknown;
  readonly executions: readonly AgentExecutionSnapshot[];
  readonly approvals: readonly StoredApproval[];
  readonly controls: readonly ControlRecord[];
  readonly waiting?: AgentWaitingState;
  readonly checkpoint: JournalCheckpoint;
  readonly providerEpoch: string;
  readonly hasOlderHistory: boolean;
  readonly olderHistoryCursor?: string;
  readonly compatibility?: AgentRunCompatibility;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L124)

### ThreadStatus (type alias)

Current scheduling state of an agent thread.

**Signature**

```ts
type ThreadStatus =
  "idle" | "running" | "waiting" | "approval-interrupted" | "stopping" | "worker-interrupted";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-state.ts#L7)

## `agent-thread-transition.types.ts`

Defines agent-thread actions, accepted transitions, and stable rejection codes.

### AgentTransitionError (type alias)

Stable rejection codes returned for invalid thread actions.

**Signature**

```ts
type AgentTransitionError =
  | "AGENT_BUSY"
  | "AGENT_APPROVAL_REQUIRED"
  | "AGENT_STOPPING"
  | "AGENT_WORKER_INTERRUPTED"
  | "AGENT_INVALID_CONTROL";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-thread-transition.types.ts#L8)

### ThreadAction (type alias)

Actions that a caller may request for an agent thread.

**Signature**

```ts
type ThreadAction = "send" | "steer" | "follow-up" | "stop" | "approve" | "deny";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-thread-transition.types.ts#L5)

### ThreadTransition (type alias)

The accepted next state or the reason the current state cannot advance.

**Signature**

```ts
type ThreadTransition =
  | { readonly accepted: true; readonly nextStatus: ThreadStatus; readonly idempotent: boolean }
  | {
      readonly accepted: false;
      readonly status: ThreadStatus;
      readonly code: AgentTransitionError;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/agent-thread-transition.types.ts#L16)

## `jobs-access.ts`

### JobAccessGrant (interface)

Scope and optional expiry returned by the access provider.

**Signature**

```ts
export interface JobAccessGrant {
  readonly scope: string;
  readonly expiresAt?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-access.ts#L17)

### JobAccessRequest (interface)

Resource and optional input presented for job authorization.

**Signature**

```ts
export interface JobAccessRequest {
  readonly operation: JobClientOperation;
  readonly jobId: string;
  readonly runId?: string;
  readonly stream?: string;
  readonly input?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-access.ts#L8)

### JobClientOperation (type alias)

Client action requiring a job access grant.

**Signature**

```ts
type JobClientOperation = "trigger" | "get" | "list" | "watch" | "cancel" | "retry" | "stream";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-access.ts#L4)

### JobUnknownOutcome (interface)

Recoverable uncertainty after a job submission or control request.

**Signature**

```ts
export interface JobUnknownOutcome {
  readonly code: "RELKIT_JOB_SUBMISSION_UNKNOWN" | "RELKIT_JOB_CONTROL_UNKNOWN";
  readonly outcome: "unknown";
  readonly operationId: string;
  readonly idempotencyKey?: string;
  readonly recovery: {
    readonly action: "retry-with-same-key" | "inspect-native" | "unavailable";
    readonly expiresAt?: string;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-access.ts#L23)

## `jobs-progress.ts`

### ProgressEmitReceipt (interface)

Receipt returned after progress is persisted or sent.

**Signature**

```ts
export interface ProgressEmitReceipt {
  readonly outcome: ProgressOutcome;
  readonly sequence?: number;
  readonly generation?: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-progress.ts#L7)

### ProgressOutcome (type alias)

Delivery outcome of an emitted progress item.

**Signature**

```ts
type ProgressOutcome = "persisted" | "sent" | "dropped" | "unavailable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-progress.ts#L4)

### StreamItem (type alias)

JSON-safe item carried by a named job stream.

**Signature**

```ts
type StreamItem = JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-progress.ts#L21)

### StreamSchemaDescriptor (interface)

Name and version of a typed job stream schema.

**Signature**

```ts
export interface StreamSchemaDescriptor<Name extends string = string> {
  readonly name: Name;
  readonly schemaVersion: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-progress.ts#L15)

## `jobs-refs.ts`

### JobRef (interface)

Browser-safe reference to a job and its underlying task.

**Signature**

```ts
export interface JobRef<
  Id extends string = string,
  InputSchema = unknown,
  OutputSchema = unknown,
  Task extends TaskRef = TaskRef,
> {
  readonly ref: Ref<"job", Id>;
  readonly input: InputSchema;
  readonly output?: OutputSchema;
  readonly task?: Task;
  readonly name?: string;
  readonly profile?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L47)

### JobRefAny (type alias)

Job reference with unconstrained type parameters.

**Signature**

```ts
type JobRefAny = JobRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L62)

### SchemaInput (type alias)

Input type inferred from a structural Standard Schema reference.

**Signature**

```ts
type SchemaInput<S> = S extends {
  readonly "~standard": { readonly types?: SchemaTypeParameters<infer Input, unknown> };
}
  ? Input
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L17)

### SchemaLike (interface)

Structural schema shape used by browser-safe references.

**Signature**

```ts
export interface SchemaLike<Input = unknown, Output = Input> {
  readonly "~standard": {
    readonly types?: SchemaTypeParameters<Input, Output>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L10)

### SchemaOutput (type alias)

Output type inferred from a structural Standard Schema reference.

**Signature**

```ts
type SchemaOutput<S> = S extends {
  readonly "~standard": { readonly types?: SchemaTypeParameters<unknown, infer Output> };
}
  ? Output
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L24)

### SchemaTypeParameters (interface)

Standard Schema type parameters captured by a browser-safe reference.

**Signature**

```ts
export interface SchemaTypeParameters<Input = unknown, Output = Input> {
  readonly input: Input;
  readonly output: Output;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L4)

### TaskRef (interface)

Browser-safe reference to a task and its input, output, and errors.

**Signature**

```ts
export interface TaskRef<
  Id extends string = string,
  InputSchema = unknown,
  OutputSchema = unknown,
  Errors extends readonly unknown[] = readonly unknown[],
> {
  readonly ref: Ref<"task", Id>;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly errors?: Errors;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L31)

### TaskRefAny (type alias)

Task reference with unconstrained type parameters.

**Signature**

```ts
type TaskRefAny = TaskRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-refs.ts#L44)

## `jobs-run-stream.ts`

### NamedStreamFrame (type alias)

Lifecycle or item frame produced by a named job stream.

**Signature**

```ts
type NamedStreamFrame<Item = JsonValue> =
  | (StreamIdentity & { readonly kind: "start" })
  | (StreamIdentity & {
      readonly kind: "chunk";
      readonly sequence: number;
      readonly item: Item;
      readonly cursor?: string;
    })
  | (StreamIdentity & {
      readonly kind: "reset";
      readonly reason: "reconnected" | "cursor-expired" | "overflow";
    })
  | (StreamIdentity & { readonly kind: "end" });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run-stream.ts#L55)

### RunConnection (type alias)

Connection state reported while observing a job run.

**Signature**

```ts
type RunConnection =
  | "idle"
  | "connecting"
  | "connected"
  | "reconnecting"
  | "disconnected"
  | "completed"
  | "unauthorized"
  | "error"
  | "disposed";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run-stream.ts#L5)

### RunWatchFrame (type alias)

Snapshot, update, or continuity reset sent to a run watcher.

**Signature**

```ts
type RunWatchFrame<Run = RunSnapshot> =
  | {
      readonly kind: "snapshot";
      readonly run: Run;
      readonly observedAt: string;
      readonly epoch: string;
      readonly sequence: number;
      readonly cursor?: string;
      readonly continuity: "state" | "history";
    }
  | {
      readonly kind: "update";
      readonly run: Run;
      readonly observedAt: string;
      readonly epoch: string;
      readonly sequence: number;
      readonly cursor?: string;
    }
  | {
      readonly kind: "reset";
      readonly run: Run;
      readonly observedAt: string;
      readonly epoch: string;
      readonly sequence: number;
      readonly reason: "reconnected" | "cursor-expired" | "history-unavailable" | "overflow";
      readonly cursor?: string;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run-stream.ts#L17)

### StreamIdentity (interface)

Identity of a named stream within one run attempt and generation.

**Signature**

```ts
export interface StreamIdentity {
  readonly runId: string;
  readonly name: string;
  readonly attempt: number;
  readonly generation: string;
  readonly schemaVersion: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run-stream.ts#L46)

## `jobs-run.ts`

### JobErrorEnvelope (interface)

Public error details safe to return from a job run.

**Signature**

```ts
export interface JobErrorEnvelope {
  readonly code: string;
  readonly message: string;
  readonly details?: JsonValue;
  readonly retry?: "never" | "later";
  readonly afterMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L49)

### JobRunStatus (type alias)

Persisted lifecycle state of a job run.

**Signature**

```ts
type JobRunStatus =
  | "queued"
  | "delayed"
  | "running"
  | "sleeping"
  | "retrying"
  | "completed"
  | "failed"
  | "cancelled"
  | "timed-out"
  | "unknown";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L11)

### NamedStreamFrame

**Signature**

```ts
declare const NamedStreamFrame: NamedStreamFrame<Item>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L4)

### ResultAvailability (type alias)

Availability of a run result after retention and policy checks.

**Signature**

```ts
type ResultAvailability =
  | "pending"
  | "available"
  | "void"
  | "redacted"
  | "expired"
  | "not-selected"
  | "version-incompatible"
  | "unavailable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L26)

### RunAvailability (interface)

Per-service availability reported with a run page.

**Signature**

```ts
export interface RunAvailability {
  readonly service: string;
  readonly state: "available" | "unavailable";
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L137)

### RunCancellationReceipt (interface)

Outcome of requesting cancellation for a job run.

**Signature**

```ts
export interface RunCancellationReceipt {
  readonly runId: string;
  readonly operationId: string;
  readonly outcome: "requested" | "already-terminal" | "unsupported";
  readonly requestedAt?: string;
  readonly run?: RunSnapshot;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L58)

### RunConnection

**Signature**

```ts
declare const RunConnection: RunConnection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L5)

### RunHandle (interface)

Identity and acceptance metadata returned after triggering a run.

**Signature**

```ts
export interface RunHandle {
  readonly accepted: true;
  readonly runId: string;
  readonly jobId: string;
  readonly taskId: string;
  readonly taskVersion: string;
  readonly acceptedAt: string;
  readonly duplicate?: boolean;
  readonly idempotencyExpiresAt?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L37)

### RunListQuery (interface)

Filters and pagination inputs for listing job runs.

**Signature**

```ts
export interface RunListQuery {
  readonly status?: readonly JobRunStatus[];
  readonly jobId?: string;
  readonly taskId?: string;
  readonly taskVersion?: string;
  readonly buildId?: string;
  readonly service?: string;
  readonly acceptedFrom?: string;
  readonly acceptedTo?: string;
  readonly startedFrom?: string;
  readonly startedTo?: string;
  readonly completedFrom?: string;
  readonly completedTo?: string;
  readonly tags?: readonly string[];
  readonly tagMatch?: "all" | "any";
  readonly correlationId?: string;
  readonly parentRunId?: string;
  readonly runId?: string;
  readonly limit?: number;
  readonly cursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L114)

### RunPage (interface)

Paginated run results and provider availability.

**Signature**

```ts
export interface RunPage<Run = RunSnapshot> {
  readonly items: readonly Run[];
  readonly nextCursor?: string;
  readonly hasMore: boolean;
  readonly availability: readonly RunAvailability[];
  readonly count?: { readonly value: number; readonly accuracy: "exact" | "approximate" };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L144)

### RunRetryReceipt (interface)

Acceptance receipt linking a retry to its original run.

**Signature**

```ts
export interface RunRetryReceipt extends RunHandle {
  readonly retryOfRunId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L153)

### RunSnapshot (type alias)

Discriminated run snapshot whose output exists only when available.

**Signature**

```ts
type RunSnapshot<
  Input = unknown,
  Output = unknown,
  Progress = unknown,
  Failure = JobErrorEnvelope,
> =
  | (RunSnapshotBase<Input, Progress, Failure> & {
      readonly status: "completed";
      readonly resultAvailability: "available";
      readonly output: Output;
    })
  | (RunSnapshotBase<Input, Progress, Failure> & {
      readonly status: "completed";
      readonly resultAvailability: Exclude<ResultAvailability, "available">;
      readonly output?: never;
    })
  | (RunSnapshotBase<Input, Progress, Failure> & {
      readonly status: Exclude<JobRunStatus, "completed">;
      readonly output?: never;
    });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L92)

### RunStatus (type alias)

Backward-compatible alias for a job run status.

**Signature**

```ts
type RunStatus = JobRunStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L23)

### RunWatchFrame

**Signature**

```ts
declare const RunWatchFrame: RunWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L6)

### StreamIdentity

**Signature**

```ts
declare const StreamIdentity: StreamIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-run.ts#L7)

## `jobs-wire.types.ts`

### JobWireEnvelope (type alias)

Versioned result representation on the jobs wire.

**Signature**

```ts
type JobWireEnvelope = JsonWireEnvelope | VoidWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-wire.types.ts#L18)

### JsonWireEnvelope (interface)

Wire envelope carrying a JSON result.

**Signature**

```ts
export interface JsonWireEnvelope {
  readonly version: typeof JOBS_WIRE_VERSION;
  readonly kind: "json";
  readonly value: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-wire.types.ts#L5)

### VoidWireEnvelope (interface)

Wire envelope carrying no result value.

**Signature**

```ts
export interface VoidWireEnvelope {
  readonly version: typeof JOBS_WIRE_VERSION;
  readonly kind: "void";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs-wire.types.ts#L12)

## `jobs.ts`

### "./jobs-contracts.js" (namespace export)

Re-exports all named exports from the "./jobs-contracts.js" module.

**Signature**

```ts
export * from "./jobs-contracts.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L7)

### JOBS_MANIFEST_PROTOCOL

**Signature**

```ts
declare const JOBS_MANIFEST_PROTOCOL: "relkit.jobs-manifest";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L3)

### JOBS_MANIFEST_VERSION

**Signature**

```ts
declare const JOBS_MANIFEST_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L4)

### JOBS_PROTOCOL

**Signature**

```ts
declare const JOBS_PROTOCOL: "relkit.jobs";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L1)

### JOBS_PROTOCOL_VERSION

**Signature**

```ts
declare const JOBS_PROTOCOL_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L2)

### JOB_NAME_MAX_LENGTH

**Signature**

```ts
declare const JOB_NAME_MAX_LENGTH: 64;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/contracts/src/jobs.ts#L5)

---

# Better Auth API
Source: https://relkit.dev/docs/api/better-auth

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineBetterAuthService](/docs/api/better-auth#definebetterauthservice)

For configuration and examples, read [auth](/docs/modules/auth), [better auth](/docs/modules/auth/better-auth), [sessions](/docs/modules/auth/sessions).

For a complete workflow, follow [email password sign in](/guides/auth/email-password-sign-in).

## Frontend usage

[Sign in from the browser](/docs/modules/auth/clients) shows the client side of this capability.

## Public imports

- `@relkit/better-auth` — 7 exports
- `@relkit/better-auth/react` — 3 exports
- `@relkit/better-auth/drizzle` — 19 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                        | Kind  | Import from                                          | Example                                                                                                                |
| ---------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [activateBetterAuthService](/docs/api/better-auth#activatebetterauthservice)                               | Value | `@relkit/better-auth/drizzle`                        | [API example](/docs/api/better-auth#activatebetterauthservice)                                                         |
| [AuthConfiguration](/docs/api/better-auth#authconfiguration-interface)                                     | Type  | `@relkit/better-auth/drizzle`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/auth-test-layer.ts#L19)   |
| [AuthFactory](/docs/api/better-auth#authfactory-class)                                                     | Value | `@relkit/better-auth/drizzle`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/auth-test-layer.ts#L23)   |
| [AuthFactoryInterface](/docs/api/better-auth#authfactoryinterface-interface)                               | Type  | `@relkit/better-auth/drizzle`                        | [Module example](/docs/modules/auth)                                                                                   |
| [authFactoryLiveLayer](/docs/api/better-auth#authfactorylivelayer)                                         | Value | `@relkit/better-auth/drizzle`                        | [API example](/docs/api/better-auth#authfactorylivelayer)                                                              |
| [AuthFailure](/docs/api/better-auth#authfailure-class)                                                     | Value | `@relkit/better-auth/drizzle`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/auth-test.types.ts#L13)   |
| [authLiveLayer](/docs/api/better-auth#authlivelayer)                                                       | Value | `@relkit/better-auth/drizzle`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/examples.ts#L39)          |
| [AuthService](/docs/api/better-auth#authservice-class)                                                     | Value | `@relkit/better-auth/drizzle`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/acquisition.test.ts#L114) |
| [AuthServiceInterface](/docs/api/better-auth#authserviceinterface-interface)                               | Type  | `@relkit/better-auth/drizzle`                        | [Module example](/docs/modules/auth)                                                                                   |
| [authServiceLayer](/docs/api/better-auth#authservicelayer)                                                 | Value | `@relkit/better-auth/drizzle`                        | [API example](/docs/api/better-auth#authservicelayer)                                                                  |
| [BETTER_AUTH_HANDLER](/docs/api/better-auth#better_auth_handler-2)                                         | Value | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/service.test.ts#L31)           |
| [BetterAuthActivationOptions](/docs/api/better-auth#betterauthactivationoptions-interface)                 | Type  | `@relkit/better-auth/drizzle`                        | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthClientLike](/docs/api/better-auth#betterauthclientlike-interface)                               | Type  | `@relkit/better-auth/react`                          | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthHandler](/docs/api/better-auth#betterauthhandler-type-alias)                                    | Type  | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthRegistration](/docs/api/better-auth#betterauthregistration-interface)                           | Type  | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthRelkitClientProvider](/docs/api/better-auth#betterauthrelkitclientprovider)                     | Value | `@relkit/better-auth/react`                          | [API example](/docs/api/better-auth#betterauthrelkitclientprovider)                                                    |
| [BetterAuthRelkitClientProviderProps](/docs/api/better-auth#betterauthrelkitclientproviderprops-interface) | Type  | `@relkit/better-auth/react`                          | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthServiceDescriptor](/docs/api/better-auth#betterauthservicedescriptor-interface)                 | Type  | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthServiceOptions](/docs/api/better-auth#betterauthserviceoptions-type-alias-1)                    | Type  | `@relkit/better-auth`                                | [Module example](/docs/modules/auth)                                                                                   |
| [BetterAuthServiceOptions](/docs/api/better-auth#betterauthserviceoptions-type-alias)                      | Type  | `@relkit/better-auth/drizzle`                        | [Module example](/docs/modules/auth)                                                                                   |
| [defineBetterAuthService](/docs/api/better-auth#definebetterauthservice-1)                                 | Value | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [API example](/docs/api/better-auth#definebetterauthservice-1)                                                         |
| [generateBetterAuthOpenApi](/docs/api/better-auth#generatebetterauthopenapi-1)                             | Value | `@relkit/better-auth/drizzle`                        | [API example](/docs/api/better-auth#generatebetterauthopenapi-1)                                                       |
| [InferBetterAuthSession](/docs/api/better-auth#inferbetterauthsession-type-alias)                          | Type  | `@relkit/better-auth`, `@relkit/better-auth/drizzle` | [Module example](/docs/modules/auth)                                                                                   |

## `activation.ts`

Binds lazy auth declarations to shared or isolated managed native owners.
Failed shared acquisition is evicted; successful owners borrow the database lifecycle and preserve native settlement.

### activateBetterAuthService

Binds native auth to an acquired database and its declared ALL route.

**Example**

```ts
import {
  activateBetterAuthService,
  defineBetterAuthService,
  type AuthConfiguration,
} from "@relkit/better-auth/drizzle";
async function handleNativeAuth(database: AuthConfiguration["database"]): Promise<Response> {
  const service = defineBetterAuthService({ baseURL: "http://localhost" });
  const auth = await activateBetterAuthService(service, database, "/api/auth", { isolated: true });
  return auth.handler(new Request("http://localhost/api/auth/get-session"));
}
// The application retains database ownership until admitted work completes.
```

**Signature**

```ts
declare const activateBetterAuthService: <Options extends BetterAuthServiceOptions>(
  service: BetterAuthServiceDescriptor<Options>,
  database: AuthDatabase,
  basePath: string,
  options?: BetterAuthActivationOptions,
) => Promise<Auth<any>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/activation.ts#L42)

### authNativeAdapter

**Signature**

```ts
declare const authNativeAdapter: (
  owner: BetterAuthRuntime<BetterAuthServiceOptions>["activation"] & {},
  native: Auth<any>,
) => Auth<any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/activation.ts#L19)

### runAuthPromise

**Signature**

```ts
declare const runAuthPromise: <A, E, R, ER>(
  runtime: ManagedRuntime.ManagedRuntime<R, ER>,
  effect: Effect.Effect<A, E, R>,
  options?: Effect.RunOptions,
  operation?: string,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/activation.ts#L18)

## `activation.types.ts`

Acquisition policy for authentication bound to an independently owned database.

### BetterAuthActivationOptions (interface)

Acquisition policy for authentication bound to an independently owned database.

**Signature**

```ts
export interface BetterAuthActivationOptions {
  /** Creates native auth without replacing the descriptor's shared handler target. */
  readonly isolated?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/activation.types.ts#L2)

## `auth-database.ts`

Borrows database admission and resolves its existing native declaration brand.

### databaseServiceOf

Reads the established native brand; auth never acquires another database owner.

**Signature**

```ts
declare const databaseServiceOf: (
  activation: AuthDatabase,
) => Parameters<typeof drizzleRuntimeOf>[0];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth-database.ts#L12)

### withAuthWork

Keeps SQLite serialization and owner drain admission around the complete SDK call.

**Signature**

```ts
declare const withAuthWork: <A, E, R>(
  database: AuthDatabase,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, DrizzleFailure | E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth-database.ts#L7)

## `auth-native-adapter.ts`

Projects native SDK callables through the existing admitted auth service.

## `auth-run.ts`

Preserves auth failures, mixed causes and native leases at the Promise boundary.

## `auth.errors.ts`

### AuthFailure (class)

Typed authentication boundary failure retaining the original SDK exception.

**Signature**

```ts
declare class AuthFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.errors.ts#L4)

## `auth.factory.ts`

Constructs selected native Better Auth after metadata preflight at the SDK boundary.
Factory failures retain their native cause and redact secret-bearing arguments from operation telemetry.

### AuthFactory (class)

Replaceable native SDK factory; auth service acquisition owns async initialization.

**See**

- `authFactoryLiveLayer` for composition with the owned auth service.

**Signature**

```ts
declare class AuthFactory
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.factory.ts#L20)

### authFactoryLiveLayer

Production SDK construction layer; acquiring the factory does not create auth.

**Example**

```ts
import { Layer } from "effect";
import {
  authFactoryLiveLayer,
  authServiceLayer,
  type AuthConfiguration,
} from "@relkit/better-auth/drizzle";
function createAuthLayer(configuration: AuthConfiguration) {
  return authServiceLayer(configuration).pipe(Layer.provide(authFactoryLiveLayer));
}
```

**Signature**

```ts
declare const authFactoryLiveLayer: Layer.Layer<AuthFactory, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.factory.ts#L35)

### makeAuthFactory

Gives substituted factory implementations the same observable operation contract.

**See**

- `authFactoryLiveLayer` for factory provisioning at service acquisition.

**Signature**

```ts
declare const makeAuthFactory: (create: AuthFactoryInterface["create"]) => AuthFactoryInterface;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.factory.ts#L62)

## `auth.schemas.ts`

### AuthBasePath

Auth route prefixes exclude trailing slashes and dynamic route markers.

**Signature**

```ts
declare const AuthBasePath: Schema.String;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.schemas.ts#L4)

## `auth.service.ts`

Owns admitted native authentication acquisition, handler calls and API dispatch.
Database leases cover uncancellable SDK settlement; the database owner retains release authority.

### AuthService (class)

Native auth service; each method admits DB work and retains SDK completion.

**See**

- `authServiceLayer` for ownership and a checked composition example.

**Signature**

```ts
declare class AuthService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.service.ts#L24)

### authLiveLayer

Builds the production authentication service with the native Better Auth factory.

**See**

- `authServiceLayer` for the checked execution and ownership example.

**Signature**

```ts
declare const authLiveLayer: (
  configuration: AuthConfiguration,
) => Layer.Layer<AuthService, AuthFailure | DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.service.ts#L147)

### authServiceLayer

Acquires authentication against a borrowed Drizzle owner using a supplied factory.

**Example**

```ts
import { Effect } from "effect";
import { AuthService, authLiveLayer, type AuthConfiguration } from "@relkit/better-auth/drizzle";
async function handleAuth(configuration: AuthConfiguration): Promise<Response> {
  const program = Effect.flatMap(AuthService, (auth) =>
    auth.handler(new Request("http://localhost/api/auth/session")),
  );
  return Effect.runPromise(program.pipe(Effect.provide(authLiveLayer(configuration))));
}
```

**Signature**

```ts
declare const authServiceLayer: (
  configuration: AuthConfiguration,
) => Layer.Layer<AuthService, AuthFailure | DrizzleFailure, AuthFactory>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.service.ts#L44)

## `auth.types.ts`

Describes the selected Drizzle authentication bridge using actual native SDK contracts.
Portable lazy declarations remain in declaration.types so backend root consumers avoid this adapter closure.

### AuthConfiguration (interface)

Runtime dependencies captured once when constructing a native auth service.

**Signature**

```ts
export interface AuthConfiguration {
  readonly options: BetterAuthServiceOptions;
  readonly database: AuthDatabase;
  readonly basePath: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L31)

### AuthDatabase (type alias)

Borrowed database; its Drizzle owner remains solely responsible for disposal.

**Signature**

```ts
type AuthDatabase = DrizzleActivation<DrizzleServiceDescriptor<any, any, any, any>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L28)

### AuthFactoryInterface (interface)

Replaceable SDK construction contract; expected SDK failures retain their cause.

**Signature**

```ts
export interface AuthFactoryInterface {
  /**
   * Constructs native auth during service acquisition.
   * @param options - Native options including the owner-supplied database adapter.
   * @returns Lazy factory effect retaining expected SDK failures as AuthFailure.
   */
  readonly create: (options: BetterAuthOptions) => Effect.Effect<Auth<any>, AuthFailure>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L38)

### AuthServiceInterface (interface)

Effect-native operations sharing one native SDK instance and database admission.

**Signature**

```ts
export interface AuthServiceInterface {
  /**
   * Executes native routing while holding borrowed database admission.
   * @param request - Unmodified native Request, including its cancellation signal.
   * @returns Lazy response effect; SDK failures retain their original cause.
   */
  readonly handler: (request: Request) => Effect.Effect<Response, AuthFailure | DrizzleFailure>;

  /**
   * Executes a native endpoint with its original arguments and callable metadata.
   * @param method - Native API property; diagnostics normalize it to bounded labels.
   * @param args - Native arguments passed without inspecting sensitive payloads.
   * @returns Lazy opaque native result, with admission and SDK typed failures.
   */
  readonly api: (
    method: string,
    args: readonly unknown[],
  ) => Effect.Effect<unknown, AuthFailure | DrizzleFailure>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L48)

### BetterAuthHandler

**Signature**

```ts
declare const BetterAuthHandler: BetterAuthHandler<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L16)

### BetterAuthRegistration

**Signature**

```ts
declare const BetterAuthRegistration: BetterAuthRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L17)

### BetterAuthRuntime (interface)

Server-only declaration state: the managed owner, rather than a mutable Promise.

**Signature**

```ts
export interface BetterAuthRuntime<Options extends BetterAuthServiceOptions> {
  readonly options: Options;
  activation: ManagedRuntime.ManagedRuntime<AuthService, AuthFailure | DrizzleFailure> | undefined;
  handle: ((request: Request) => Promise<Response>) | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L72)

### BetterAuthServiceDescriptor

**Signature**

```ts
declare const BetterAuthServiceDescriptor: BetterAuthServiceDescriptor<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L18)

### BetterAuthServiceOptions (type alias)

Native options; RELKIT supplies database and the route-derived base path.

**Signature**

```ts
type BetterAuthServiceOptions = DeclarationOptions & {
  readonly drizzle?: Omit<DrizzleAdapterConfig, "provider">;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L23)

### InferBetterAuthSession

**Signature**

```ts
declare const InferBetterAuthSession: InferBetterAuthSession<Handler>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/auth.types.ts#L19)

## `declaration.types.ts`

Lazy authentication declarations independent of a database adapter or browser.

### BetterAuthDeclarationRuntime (interface)

Database-independent state populated by the explicitly selected server bridge.

**Signature**

```ts
export interface BetterAuthDeclarationRuntime<Options extends BetterAuthServiceOptions> {
  readonly options: Options;
  activation: object | undefined;
  handle: ((request: Request) => Promise<Response>) | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L38)

### BetterAuthHandler (type alias)

Native route handler retaining inferred session and user types.

**Signature**

```ts
type BetterAuthHandler<Session = unknown> = RawHttpHandler & {
  readonly [BETTER_AUTH_HANDLER]: BetterAuthRegistration;
  readonly __session?: Session;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L20)

### BetterAuthRegistration (interface)

Frozen registration used by route discovery without acquiring native auth.

**Signature**

```ts
export interface BetterAuthRegistration {
  readonly kind: "better-auth";
  readonly service: BetterAuthServiceDescriptor<any>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L14)

### BetterAuthServiceDescriptor (interface)

Lazy authoring declaration whose identity survives isolated activation.

**Signature**

```ts
export interface BetterAuthServiceDescriptor<
  Options extends BetterAuthServiceOptions,
> extends ReturnType<typeof createDescriptorBase<"service", string>> {
  readonly capability: { readonly kind: "better-auth" };
  readonly handler: BetterAuthHandler<Auth<Options>["$Infer"]["Session"]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L30)

### BetterAuthServiceOptions (type alias)

Native options; activation supplies the database and route-derived base path.

**Signature**

```ts
type BetterAuthServiceOptions = Omit<BetterAuthOptions, "database" | "basePath"> & {
  readonly database?: never;
  readonly basePath?: never;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L8)

### InferBetterAuthSession (type alias)

Projects the session inferred by a lazy authentication handler.

**Signature**

```ts
type InferBetterAuthSession<Handler> =
  Handler extends BetterAuthHandler<infer Session> ? Session : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/declaration.types.ts#L26)

## `dependencies.ts`

Checks selected native authentication requirements without evaluating the SDK.

### checkNativeAuthDependencies

Resolves peers from this installed adapter, independently of the invoking CLI cache.

**Signature**

```ts
declare const checkNativeAuthDependencies: () => Effect.Effect<void, AuthFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/dependencies.ts#L11)

## `drizzle.ts`

Native Better Auth borrowing the selected Drizzle owner's lifetime and admission.

### AuthConfiguration

**Signature**

```ts
declare const AuthConfiguration: AuthConfiguration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L15)

### AuthFactory

**Signature**

```ts
declare const AuthFactory: typeof AuthFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L6)

### AuthFactoryInterface

**Signature**

```ts
declare const AuthFactoryInterface: AuthFactoryInterface;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L17)

### AuthFailure

**Signature**

```ts
declare const AuthFailure: typeof AuthFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L5)

### AuthService

**Signature**

```ts
declare const AuthService: typeof AuthService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L7)

### AuthServiceInterface

**Signature**

```ts
declare const AuthServiceInterface: AuthServiceInterface;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L16)

### BETTER_AUTH_HANDLER

**Signature**

```ts
declare const BETTER_AUTH_HANDLER: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L2)

### BetterAuthActivationOptions

**Signature**

```ts
declare const BetterAuthActivationOptions: BetterAuthActivationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L8)

### BetterAuthHandler

**Signature**

```ts
declare const BetterAuthHandler: BetterAuthHandler<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L12)

### BetterAuthRegistration

**Signature**

```ts
declare const BetterAuthRegistration: BetterAuthRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L11)

### BetterAuthServiceDescriptor

**Signature**

```ts
declare const BetterAuthServiceDescriptor: BetterAuthServiceDescriptor<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L14)

### BetterAuthServiceOptions

**Signature**

```ts
declare const BetterAuthServiceOptions: BetterAuthServiceOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L10)

### InferBetterAuthSession

**Signature**

```ts
declare const InferBetterAuthSession: InferBetterAuthSession<Handler>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L13)

### activateBetterAuthService

**Signature**

```ts
declare const activateBetterAuthService: <Options extends BetterAuthServiceOptions>(
  service: BetterAuthServiceDescriptor<Options>,
  database: AuthDatabase,
  basePath: string,
  options?: BetterAuthActivationOptions,
) => Promise<Auth<any>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L3)

### authFactoryLiveLayer

**Signature**

```ts
declare const authFactoryLiveLayer: Layer<AuthFactory, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L6)

### authLiveLayer

**Signature**

```ts
declare const authLiveLayer: (
  configuration: AuthConfiguration,
) => Layer<AuthService, AuthFailure | DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L7)

### authServiceLayer

**Signature**

```ts
declare const authServiceLayer: (
  configuration: AuthConfiguration,
) => Layer<AuthService, AuthFailure | DrizzleFailure, AuthFactory>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L7)

### defineBetterAuthService

**Signature**

```ts
declare const defineBetterAuthService: <const Options extends BetterAuthServiceOptions>(
  options: Options,
) => BetterAuthServiceDescriptor<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L2)

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/auth-drizzle/src/services/auth/service.ts"
/** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
import { defineBetterAuthService } from "@relkit/better-auth";

export default defineBetterAuthService({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
  // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
  emailAndPassword: { enabled: true },
});
```

```ts title="examples/auth-drizzle/src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "@app/services/auth/service.js";

export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
});
```

**Frontend**

Once the service and `/api/auth` mount are running, use Better Auth's browser client for sign-in.
First complete the [frontend auth installation](/docs/modules/auth/clients#create-a-browser-auth-client):

```ts title="src/auth-client.ts — frontend"
import { createAuthClient } from "better-auth/client";

// Browser code: use the public backend origin, never the server secret or service.
export const authClient = createAuthClient({
  baseURL: "http://127.0.0.1:3000",
  basePath: "/api/auth",
  fetchOptions: { credentials: "include" },
});

export async function signIn(email: string, password: string) {
  const { data, error } = await authClient.signIn.email({ email, password });
  if (error !== null) throw new Error(error.message ?? "Sign-in failed");
  return data;
}
```

`emailAndPassword` on the service enables this `signIn.email` operation. Keep the public URL and
mount aligned with your backend, allow the browser to manage session cookies, and handle rejected
requests in the calling UI. These native auth endpoints are not RELKIT-generated RPC operations.
Never import the server service, database, or secret into the browser.

For application route hooks after sign-in, use
[`BetterAuthRelkitClientProvider`](/docs/api/better-auth#betterauthrelkitclientprovider) as shown in
[React authentication](/docs/modules/client/authentication). Follow the
[sign-in guide](/guides/auth/email-password-sign-in) for the complete flow.

### generateBetterAuthOpenApi

**Signature**

```ts
declare const generateBetterAuthOpenApi: (
  auth: Pick<Auth, "$context">,
  instrumentation?: Context<never>,
) => Promise<JsonValue>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/drizzle.ts#L4)

## `index.ts`

Lazy authentication authoring; select /drizzle for native database activation. @packageDocumentation

### defineBetterAuthService

Defines lazy authentication using the application's Drizzle database.

**Throws**

TypeError When options is not an object or specifies database/basePath.

**Example**

```ts
import { defineBetterAuthService } from "@relkit/better-auth";
const auth = defineBetterAuthService({
  baseURL: "http://127.0.0.1:3000",
  emailAndPassword: { enabled: true },
});
const handler = auth.handler;
```

**Signature**

```ts
declare const defineBetterAuthService: <const Options extends BetterAuthServiceOptions>(
  options: Options,
) => BetterAuthServiceDescriptor<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L43)

Since v0.0.5

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/auth-drizzle/src/services/auth/service.ts"
/** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
import { defineBetterAuthService } from "@relkit/better-auth";

export default defineBetterAuthService({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
  // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
  emailAndPassword: { enabled: true },
});
```

```ts title="examples/auth-drizzle/src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "@app/services/auth/service.js";

export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
});
```

**Frontend**

Once the service and `/api/auth` mount are running, use Better Auth's browser client for sign-in.
First complete the [frontend auth installation](/docs/modules/auth/clients#create-a-browser-auth-client):

```ts title="src/auth-client.ts — frontend"
import { createAuthClient } from "better-auth/client";

// Browser code: use the public backend origin, never the server secret or service.
export const authClient = createAuthClient({
  baseURL: "http://127.0.0.1:3000",
  basePath: "/api/auth",
  fetchOptions: { credentials: "include" },
});

export async function signIn(email: string, password: string) {
  const { data, error } = await authClient.signIn.email({ email, password });
  if (error !== null) throw new Error(error.message ?? "Sign-in failed");
  return data;
}
```

`emailAndPassword` on the service enables this `signIn.email` operation. Keep the public URL and
mount aligned with your backend, allow the browser to manage session cookies, and handle rejected
requests in the calling UI. These native auth endpoints are not RELKIT-generated RPC operations.
Never import the server service, database, or secret into the browser.

For application route hooks after sign-in, use
[`BetterAuthRelkitClientProvider`](/docs/api/better-auth#betterauthrelkitclientprovider) as shown in
[React authentication](/docs/modules/client/authentication). Follow the
[sign-in guide](/guides/auth/email-password-sign-in) for the complete flow.

### BETTER_AUTH_HANDLER

**Signature**

```ts
declare const BETTER_AUTH_HANDLER: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L13)

### BetterAuthHandler

**Signature**

```ts
declare const BetterAuthHandler: BetterAuthHandler<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L17)

### BetterAuthRegistration

**Signature**

```ts
declare const BetterAuthRegistration: BetterAuthRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L16)

### BetterAuthServiceDescriptor

**Signature**

```ts
declare const BetterAuthServiceDescriptor: BetterAuthServiceDescriptor<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L19)

### BetterAuthServiceOptions

**Signature**

```ts
declare const BetterAuthServiceOptions: BetterAuthServiceOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L15)

### InferBetterAuthSession

**Signature**

```ts
declare const InferBetterAuthSession: InferBetterAuthSession<Handler>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/index.ts#L18)

## `openapi-projection.ts`

Validates native schema JSON, prefixes mounted paths and component identities,
and removes token requirements from browser-session documentation. This pure
projection is called by AuthOpenApi; malformed metadata throws at that adapter.

### projectAuthOpenApi

Detaches and projects one native OpenAPI document without changing SDK metadata.

**Throws**

TypeError When the metadata is not JSON or lacks paths.

**Signature**

```ts
declare const projectAuthOpenApi: <Input>(document: Input, basePath?: string) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi-projection.ts#L16)

## `openapi-query.ts`

Documents each endpoint's real query contract. Better Auth's generator only reads
a top-level object schema and never marks a query field required, so wrapped
(`optional`, `default`) and union schemas publish no parameters at all.

### QueryEndpoint (interface)

The native endpoint fields this projection reads.

**Signature**

```ts
export interface QueryEndpoint {
  readonly path?: string;
  readonly options?: {
    readonly method?: string | readonly string[];
    readonly query?: unknown;
    readonly metadata?: object;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi-query.ts#L9)

### acceptedShapes

Lists the object shapes a union schema accepts, marking optional fields with `?`.

**Signature**

```ts
declare const acceptedShapes: (schema: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi-query.ts#L71)

### documentQueryParameters

Adds missing query parameters and required flags to Better Auth's generated paths.

**Signature**

```ts
declare const documentQueryParameters: (
  document: JsonValue,
  endpoints: Iterable<QueryEndpoint>,
) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi-query.ts#L30)

## `openapi.ts`

Generates native authentication documentation through a typed, observable
service. The activated SDK supplies endpoint metadata; projection does not
acquire a database or install the plugin's public schema/reference routes.
The exported Promise function is the server compatibility boundary.

### AuthOpenApi (class)

Native metadata projection with no request identity or database ownership.

**Signature**

```ts
declare class AuthOpenApi
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi.ts#L20)

### generateBetterAuthOpenApi

Projects native core and plugin endpoints for RELKIT's shared API reference.

**Example**

```ts
const schema = await generateBetterAuthOpenApi(auth);
```

**Signature**

```ts
declare const generateBetterAuthOpenApi: (
  auth: Pick<Auth, "$context">,
  instrumentation?: Context.Context<never>,
) => Promise<JsonValue>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/openapi.ts#L74)

## `react.ts`

### BetterAuthClientLike

**Signature**

```ts
declare const BetterAuthClientLike: BetterAuthClientLike<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/react.ts#L6)

### BetterAuthRelkitClientProvider

Remounts the RELKIT client whenever native authentication identity changes.

**Example**

```ts
import { createElement } from "react";
import { createAuthClient } from "better-auth/react";
import { BetterAuthRelkitClientProvider } from "@relkit/better-auth/react";
const authClient = createAuthClient();
const provider = createElement(BetterAuthRelkitClientProvider, { authClient, children: null });
```

**Signature**

```ts
declare const BetterAuthRelkitClientProvider: <Session>(
  props: BetterAuthRelkitClientProviderProps<Session>,
) => ReactNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/react.ts#L24)

### BetterAuthRelkitClientProviderProps

**Signature**

```ts
declare const BetterAuthRelkitClientProviderProps: BetterAuthRelkitClientProviderProps<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/react.ts#L6)

## `react.types.ts`

### BetterAuthClientLike (interface)

Browser SDK hook contract retaining the native inferred session type.

**Signature**

```ts
export interface BetterAuthClientLike<Session> {
  /**
   * Reads reactive authentication state; hook ownership stays with React.
   * @returns Native session data, loading state and optional SDK error.
   */
  useSession(): {
    readonly data: Session | null | undefined;
    readonly isPending: boolean;
    readonly error?: unknown;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/react.types.ts#L7)

### BetterAuthRelkitClientProviderProps (interface)

Client provider props with a native auth hook; no server runtime dependency.

**Signature**

```ts
export interface BetterAuthRelkitClientProviderProps<Session> extends RelkitClientProviderProps {
  readonly authClient: BetterAuthClientLike<Session>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/react.types.ts#L23)

## `symbols.ts`

Brands a stable route handler with its owning auth declaration.

### BETTER_AUTH_HANDLER

Brands a stable route handler with its owning auth declaration.

**Signature**

```ts
declare const BETTER_AUTH_HANDLER: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/symbols.ts#L2)

### BETTER_AUTH_RUNTIME

Stores server-only lazy activation state without exposing it publicly.

**Signature**

```ts
declare const BETTER_AUTH_RUNTIME: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/symbols.ts#L5)

## `validation-detail.ts`

Explains Better Auth input validation failures. better-call formats each Standard
Schema issue as `[location] message`, which reduces a union failure to
`[query] Invalid input` and drops why each accepted shape was rejected.

### ValidatedAuth (interface)

The native SDK fields this explanation reads.

**Signature**

```ts
export interface ValidatedAuth {
  readonly handler: (request: Request) => Promise<Response>;
  readonly api: object;
  readonly options: { readonly basePath?: string };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/validation-detail.ts#L9)

### ValidationDetail (interface)

One failing field; `option` numbers the accepted shape it belongs to, from 1.

**Signature**

```ts
export interface ValidationDetail {
  readonly path: string;
  readonly message: string;
  readonly option?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/validation-detail.ts#L33)

### handleWithValidationDetail

Runs the native handler and, for a validation failure, names every failing field.

**Signature**

```ts
declare const handleWithValidationDetail: (
  auth: ValidatedAuth,
  request: Request,
) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/src/validation-detail.ts#L47)

---

# Buckets API
Source: https://relkit.dev/docs/api/buckets

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineBucket](/docs/api/buckets#definebucket)

For configuration and examples, read [define](/docs/modules/storage/define), [organization](/docs/modules/service/organization), [uploads](/docs/modules/http/uploads).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/buckets` — 48 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                    | Kind  | Import from       | Example                                                               |
| -------------------------------------------------------------------------------------- | ----- | ----------------- | --------------------------------------------------------------------- |
| [asProvider](/docs/api/buckets#asprovider)                                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#asprovider)                           |
| [asProviderEffect](/docs/api/buckets#asprovidereffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#asprovidereffect)                     |
| [assertBucketDescriptor](/docs/api/buckets#assertbucketdescriptor)                     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#assertbucketdescriptor)               |
| [assertBucketDescriptorEffect](/docs/api/buckets#assertbucketdescriptoreffect)         | Value | `@relkit/buckets` | [API example](/docs/api/buckets#assertbucketdescriptoreffect)         |
| [BucketBridgeOptions](/docs/api/buckets#bucketbridgeoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketbridgeoptions-interface)        |
| [BucketCapabilities](/docs/api/buckets#bucketcapabilities-interface)                   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapabilities-interface)         |
| [BucketCapability](/docs/api/buckets#bucketcapability-type-alias)                      | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapability-type-alias)          |
| [BucketCapabilityError](/docs/api/buckets#bucketcapabilityerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketcapabilityerror-class)          |
| [BucketClient](/docs/api/buckets#bucketclient-interface)                               | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketclient-interface)               |
| [BucketClientOptions](/docs/api/buckets#bucketclientoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketclientoptions-interface)        |
| [BucketDependencyError](/docs/api/buckets#bucketdependencyerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdependencyerror-class)          |
| [BucketDescriptor](/docs/api/buckets#bucketdescriptor-interface)                       | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdescriptor-interface)           |
| [BucketDescriptorAny](/docs/api/buckets#bucketdescriptorany-type-alias)                | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketdescriptorany-type-alias)       |
| [BucketInvocationBridge](/docs/api/buckets#bucketinvocationbridge-interface)           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketinvocationbridge-interface)     |
| [BucketObjectMetadata](/docs/api/buckets#bucketobjectmetadata-interface)               | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketobjectmetadata-interface)       |
| [BucketObservedEdge](/docs/api/buckets#bucketobservededge-interface)                   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketobservededge-interface)         |
| [BucketOperation](/docs/api/buckets#bucketoperation-type-alias)                        | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperation-type-alias)           |
| [BucketOperationCancelledError](/docs/api/buckets#bucketoperationcancellederror-class) | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationcancellederror-class)  |
| [BucketOperationContext](/docs/api/buckets#bucketoperationcontext-interface)           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationcontext-interface)     |
| [BucketOperationObservation](/docs/api/buckets#bucketoperationobservation-interface)   | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationobservation-interface) |
| [BucketOperationOutcome](/docs/api/buckets#bucketoperationoutcome-type-alias)          | Type  | `@relkit/buckets` | [Module example](/docs/modules/storage/define)                        |
| [BucketOperationTimeoutError](/docs/api/buckets#bucketoperationtimeouterror-class)     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketoperationtimeouterror-class)    |
| [BucketProvider](/docs/api/buckets#bucketprovider-interface)                           | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketprovider-interface)             |
| [BucketProviderError](/docs/api/buckets#bucketprovidererror-class)                     | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketprovidererror-class)            |
| [BucketProviderFailureError](/docs/api/buckets#bucketproviderfailureerror-class)       | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketproviderfailureerror-class)     |
| [BucketPutOptions](/docs/api/buckets#bucketputoptions-interface)                       | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketputoptions-interface)           |
| [BucketRuntime](/docs/api/buckets#bucketruntime-class)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketruntime-class)                  |
| [bucketRuntimeLayer](/docs/api/buckets#bucketruntimelayer)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketruntimelayer)                   |
| [BucketTelemetry](/docs/api/buckets#buckettelemetry-class)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#buckettelemetry-class)                |
| [BucketTelemetryLive](/docs/api/buckets#buckettelemetrylive)                           | Value | `@relkit/buckets` | [API example](/docs/api/buckets#buckettelemetrylive)                  |
| [BucketValidationError](/docs/api/buckets#bucketvalidationerror-class)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#bucketvalidationerror-class)          |
| [BucketVisibility](/docs/api/buckets#bucketvisibility-type-alias)                      | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#bucketvisibility-type-alias)          |
| [createBucketClient](/docs/api/buckets#createbucketclient)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketclient)                   |
| [createBucketClientEffect](/docs/api/buckets#createbucketclienteffect)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketclienteffect)             |
| [createBucketReadUrlEffect](/docs/api/buckets#createbucketreadurleffect)               | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketreadurleffect)            |
| [createBucketWriteUrlEffect](/docs/api/buckets#createbucketwriteurleffect)             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#createbucketwriteurleffect)           |
| [defineBucket](/docs/api/buckets#definebucket)                                         | Value | `@relkit/buckets` | [API example](/docs/api/buckets#definebucket)                         |
| [defineBucketEffect](/docs/api/buckets#definebucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#definebucketeffect)                   |
| [DefineBucketOptions](/docs/api/buckets#definebucketoptions-interface)                 | Type  | `@relkit/buckets` | [API example](/docs/api/buckets#definebucketoptions-interface)        |
| [deleteBucketEffect](/docs/api/buckets#deletebucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#deletebucketeffect)                   |
| [existsBucketEffect](/docs/api/buckets#existsbucketeffect)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#existsbucketeffect)                   |
| [getBucketEffect](/docs/api/buckets#getbucketeffect)                                   | Value | `@relkit/buckets` | [API example](/docs/api/buckets#getbucketeffect)                      |
| [headBucketEffect](/docs/api/buckets#headbucketeffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#headbucketeffect)                     |
| [isBucketDescriptor](/docs/api/buckets#isbucketdescriptor)                             | Value | `@relkit/buckets` | [API example](/docs/api/buckets#isbucketdescriptor)                   |
| [isBucketDescriptorEffect](/docs/api/buckets#isbucketdescriptoreffect)                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#isbucketdescriptoreffect)             |
| [listBucketEffect](/docs/api/buckets#listbucketeffect)                                 | Value | `@relkit/buckets` | [API example](/docs/api/buckets#listbucketeffect)                     |
| [observeBucket](/docs/api/buckets#observebucket)                                       | Value | `@relkit/buckets` | [API example](/docs/api/buckets#observebucket)                        |
| [putBucketEffect](/docs/api/buckets#putbucketeffect)                                   | Value | `@relkit/buckets` | [API example](/docs/api/buckets#putbucketeffect)                      |

## `bucket-validation-error.ts`

### BucketValidationError (class)

Invalid bucket authoring input, retained in the Effect error channel.

**Example**

```ts
Effect.catchTag(defineBucketEffect(input), "BucketValidationError", () => Effect.void);
```

**Signature**

```ts
declare class BucketValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/bucket-validation-error.ts#L7)

## `client-abort.ts`

### runAbortableEffect

Runs provider work with a scoped abort listener and deadline.

**Example**

```ts
Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, Effect.succeed(1)));
```

**Signature**

```ts
declare const runAbortableEffect: <A, E, R>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | BucketOperationCancelledError | BucketOperationTimeoutError, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-abort.ts#L11)

## `client-effects.ts`

### createBucketReadUrlEffect

Creates a signed read URL when supported.

**Example**

```ts
Effect.provide(createBucketReadUrlEffect("a"), layer);
```

**Signature**

```ts
declare const createBucketReadUrlEffect: (
  key: string,
) => Effect.Effect<
  string,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L141)

### createBucketWriteUrlEffect

Creates a signed write URL when supported.

**Example**

```ts
Effect.provide(createBucketWriteUrlEffect("a"), layer);
```

**Signature**

```ts
declare const createBucketWriteUrlEffect: (
  key: string,
) => Effect.Effect<
  string,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L162)

### deleteBucketEffect

Deletes one key.

**Example**

```ts
Effect.provide(deleteBucketEffect("a"), layer);
```

**Signature**

```ts
declare const deleteBucketEffect: (
  key: string,
) => Effect.Effect<
  void,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L84)

### existsBucketEffect

Checks whether one key exists.

**Example**

```ts
Effect.provide(existsBucketEffect("a"), layer);
```

**Signature**

```ts
declare const existsBucketEffect: (
  key: string,
) => Effect.Effect<
  boolean,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L103)

### getBucketEffect

Reads bytes for one key.

**Example**

```ts
Effect.provide(getBucketEffect("a"), layer);
```

**Signature**

```ts
declare const getBucketEffect: (
  key: string,
) => Effect.Effect<
  Uint8Array<ArrayBufferLike> | undefined,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L46)

### headBucketEffect

Reads metadata for one key.

**Example**

```ts
Effect.provide(headBucketEffect("a"), layer);
```

**Signature**

```ts
declare const headBucketEffect: (
  key: string,
) => Effect.Effect<
  BucketObjectMetadata | undefined,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L65)

### listBucketEffect

Lists keys under an optional prefix.

**Example**

```ts
Effect.provide(listBucketEffect("images/"), layer);
```

**Signature**

```ts
declare const listBucketEffect: (
  prefix?: string | undefined,
) => Effect.Effect<
  ReadonlyArray<string>,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L122)

### putBucketEffect

Stores bytes under a portable key.

**Example**

```ts
Effect.provide(putBucketEffect("a", new Uint8Array()), layer);
```

**Signature**

```ts
declare const putBucketEffect: (
  key: string,
  bytes: Uint8Array<ArrayBufferLike>,
  options?: BucketPutOptions | undefined,
) => Effect.Effect<
  void,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketValidationError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-effects.ts#L23)

## `client-errors.ts`

### BucketCapabilityError (class)

An operation requires a capability absent from the provider.

**Example**

```ts
new BucketCapabilityError("signedReadUrl", "createReadUrl");
```

**Signature**

```ts
declare class BucketCapabilityError {
  constructor(capability: BucketCapability, operation: BucketOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L9)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_CAPABILITY_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L13)

### BucketDependencyError (class)

A function used a bucket without declaring its dependency.

**Example**

```ts
new BucketDependencyError("assets");
```

**Signature**

```ts
declare class BucketDependencyError {
  constructor(bucketId: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L26)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L30)

### BucketOperationCancelledError (class)

The caller's signal cancelled a bucket operation.

**Example**

```ts
new BucketOperationCancelledError();
```

**Signature**

```ts
declare class BucketOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L62)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L66)

### BucketOperationTimeoutError (class)

A deadline expired before a bucket operation completed.

**Example**

```ts
new BucketOperationTimeoutError();
```

**Signature**

```ts
declare class BucketOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L81)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L85)

### BucketProviderError (class)

A provider omitted a requested operation.

**Example**

```ts
new BucketProviderError("get");
```

**Signature**

```ts
declare class BucketProviderError {
  constructor(operation: BucketOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L43)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L47)

### BucketProviderFailureError (class)

Provider rejection or malformed provider output.

**Example**

```ts
new BucketProviderFailureError({ operation: "get", cause: "offline" });
```

**Signature**

```ts
declare class BucketProviderFailureError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-errors.ts#L101)

## `client-key.ts`

### assertKey

Synchronous compatibility key assertion.

**Throws**

TypeError when invalid.

**Example**

```ts
assertKey("images/logo.png");
```

**Signature**

```ts
declare const assertKey: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L45)

### assertPrefix

Synchronous compatibility prefix assertion.

**Throws**

TypeError when invalid.

**Example**

```ts
assertPrefix("images/");
```

**Signature**

```ts
declare const assertPrefix: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L55)

### validateKeyEffect

Validate a portable object key in Effect.

**Example**

```ts
Effect.runSync(validateKeyEffect("images/logo.png"));
```

**Signature**

```ts
declare const validateKeyEffect: (
  value: string,
) => Effect.Effect<void, BucketValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L9)

### validatePrefixEffect

Validate a portable prefix in Effect.

**Example**

```ts
Effect.runSync(validatePrefixEffect("images/"));
```

**Signature**

```ts
declare const validatePrefixEffect: (
  value: string,
) => Effect.Effect<void, BucketValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L18)

### validateTextIdEffect

Validate nonempty identifying text in Effect.

**Example**

```ts
Effect.runSync(validateTextIdEffect("assets", "bucketId"));
```

**Signature**

```ts
declare const validateTextIdEffect: (
  value: string,
  name: string,
) => Effect.Effect<void, BucketValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-key.ts#L28)

## `client-observability.ts`

### BucketTelemetry (class)

Injectable observer for bucket Effect operations.

**Example**

```ts
Effect.provide(getBucketEffect("a"), BucketTelemetryLive);
```

**Signature**

```ts
declare class BucketTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L8)

### BucketTelemetryLive

Live bucket spans and bounded Effect metrics.

**Example**

```ts
Effect.provide(getBucketEffect("a"), BucketTelemetryLive);
```

**Signature**

```ts
declare const BucketTelemetryLive: Layer.Layer<BucketTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L15)

### observeBucket

Measures an operation using fixed operation labels.

**Example**

```ts
observeBucket("get", Effect.succeed(undefined));
```

**Signature**

```ts
declare const observeBucket: <A, E, R>(
  operation:
    | BucketOperation
    | "define"
    | "isDescriptor"
    | "assertDescriptor"
    | "createClient"
    | "asProvider",
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.ts#L29)

## `client-observability.types.ts`

### BucketTelemetryService (interface)

Substitutable observation boundary for bucket operations.

**Example**

```ts
const telemetry: BucketTelemetryService = { observe: (_operation, effect) => effect };
```

**Signature**

```ts
export interface BucketTelemetryService {
  /** Wrap an operation with spans and metrics.
   * @param operation - Fixed operation name.
   * @param effect - Effect to observe.
   * @returns Effect with the same success and error channels.
   * @example telemetry.observe("get", Effect.succeed(undefined));
   */
  readonly observe: <A, E, R>(
    operation:
      | BucketOperation
      | "define"
      | "isDescriptor"
      | "assertDescriptor"
      | "createClient"
      | "asProvider",
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-observability.types.ts#L7)

## `client-operation.ts`

### runBucketOperation

Executes a bucket operation through its injectable provider and telemetry boundary.

**Example**

```ts
Effect.provide(
  runBucketOperation({
    operation: "get",
    input: { key: "a" },
    work: (p) => p.get!("a"),
    validate: (v) => v,
  }),
  bucketRuntimeLayer(options),
);
```

**Signature**

```ts
declare const runBucketOperation: <A>(
  invocation: BucketInvocation<A>,
) => Effect.Effect<
  A,
  | BucketOperationCancelledError
  | BucketOperationTimeoutError
  | BucketDependencyError
  | BucketCapabilityError
  | BucketProviderError
  | BucketProviderFailureError,
  BucketRuntime
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-operation.ts#L19)

## `client-operation.types.ts`

### BucketInvocation (interface)

Complete arguments for one provider invocation.

**Example**

```ts
const invocation: BucketInvocation<boolean> = {
  operation: "exists",
  input: { key: "a" },
  work: (p) => p.exists!("a"),
  validate: Effect.succeed,
};
```

**Signature**

```ts
export interface BucketInvocation<A> {
  readonly operation: BucketOperation;
  readonly input: unknown;
  readonly capability?: "signedReadUrl" | "signedWriteUrl";
  readonly work: (provider: BucketProvider, context: BucketOperationContext) => Promise<A> | A;
  readonly validate: (value: A) => Effect.Effect<A, BucketProviderFailureError>;
  readonly context?: BucketOperationContext;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-operation.types.ts#L8)

## `client-provider.types.ts`

### BucketCapabilities (interface)

Provider capability flags.

**Example**

```ts
const capabilities: BucketCapabilities = { signedReadUrl: true };
```

**Signature**

```ts
export interface BucketCapabilities {
  readonly signedReadUrl?: boolean;
  readonly signedWriteUrl?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L17)

### BucketCapability (type alias)

Optional signed URL capabilities advertised by a provider.

**Example**

```ts
const capability: BucketCapability = "signedReadUrl";
```

**Signature**

```ts
type BucketCapability = "signedReadUrl" | "signedWriteUrl";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L12)

### BucketObjectMetadata (interface)

Portable object metadata returned by a provider.

**Example**

```ts
const metadata: BucketObjectMetadata = { etag: "sha256:abc", size: 3 };
```

**Signature**

```ts
export interface BucketObjectMetadata {
  readonly etag: string;
  /** Strong content digest when the provider can calculate one. */
  readonly contentHash?: string;
  readonly contentType?: string;
  readonly size?: number;
  readonly metadata?: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L34)

### BucketOperation (type alias)

Fixed names for provider operations; safe as telemetry labels.

**Example**

```ts
const operation: BucketOperation = "get";
```

**Signature**

```ts
type BucketOperation =
  "put" | "get" | "head" | "delete" | "exists" | "list" | "createReadUrl" | "createWriteUrl";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L6)

### BucketOperationContext (interface)

Per-call context passed to providers.

**Example**

```ts
const signal = context.signal;
```

**Signature**

```ts
export interface BucketOperationContext {
  readonly operation: BucketOperation;
  readonly signal: AbortSignal;
  readonly deadlineMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L25)

### BucketProvider (interface)

Provider implementation; omitted operations fail with BucketProviderError.

**Example**

```ts
const provider: BucketProvider = { get: () => undefined };
```

**Signature**

```ts
export interface BucketProvider {
  readonly capabilities?: BucketCapabilities | readonly BucketCapability[];
  /** Store an object.
   * @param key - Portable object key.
   * @param bytes - Object content.
   * @param options - Optional content metadata.
   * @param context - Cancellation and deadline context.
   * @returns Completion or a provider rejection.
   * @example await provider.put?.("a", new Uint8Array());
   */
  readonly put?: (
    key: string,
    bytes: Uint8Array,
    options?: BucketPutOptions,
    context?: BucketOperationContext,
  ) => MaybePromise<void>;
  /** Read an object.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Bytes, undefined, or a provider rejection.
   * @example await provider.get?.("a");
   */
  readonly get?: (
    key: string,
    context?: BucketOperationContext,
  ) => MaybePromise<Uint8Array | undefined>;
  /** Read object metadata.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Metadata, undefined, or a provider rejection.
   * @example await provider.head?.("a");
   */
  readonly head?: (
    key: string,
    context?: BucketOperationContext,
  ) => MaybePromise<BucketObjectMetadata | undefined>;
  /** Remove an object.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Completion or a provider rejection.
   * @example await provider.delete?.("a");
   */
  readonly delete?: (key: string, context?: BucketOperationContext) => MaybePromise<void>;
  /** Check whether an object exists.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns Existence or a provider rejection.
   * @example await provider.exists?.("a");
   */
  readonly exists?: (key: string, context?: BucketOperationContext) => MaybePromise<boolean>;
  /** List keys in provider order.
   * @param prefix - Optional portable prefix.
   * @param context - Cancellation and deadline context.
   * @returns Ordered keys or a provider rejection.
   * @example await provider.list?.("images/");
   */
  readonly list?: (
    prefix: string | undefined,
    context?: BucketOperationContext,
  ) => MaybePromise<readonly string[]>;
  /** Create a signed read URL.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns URL text or a provider rejection.
   * @example await provider.createReadUrl?.("a");
   */
  readonly createReadUrl?: (key: string, context?: BucketOperationContext) => MaybePromise<string>;
  /** Create a signed write URL.
   * @param key - Portable object key.
   * @param context - Cancellation and deadline context.
   * @returns URL text or a provider rejection.
   * @example await provider.createWriteUrl?.("a");
   */
  readonly createWriteUrl?: (key: string, context?: BucketOperationContext) => MaybePromise<string>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L54)

### BucketPutOptions (interface)

Metadata and content type supplied when storing bytes.

**Example**

```ts
const options: BucketPutOptions = { contentType: "image/png" };
```

**Signature**

```ts
export interface BucketPutOptions extends Readonly<Record<string, unknown>> {
  readonly contentType?: string;
  readonly metadata?: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-provider.types.ts#L46)

## `client-results.ts`

### validateBooleanEffect

Check an existence result.

**Example**

```ts
Effect.runSync(validateBooleanEffect(true));
```

**Signature**

```ts
declare const validateBooleanEffect: (
  value: boolean,
) => Effect.Effect<boolean, BucketProviderFailureError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L40)

### validateBytesEffect

Check bytes returned by a provider.

**Example**

```ts
Effect.runSync(validateBytesEffect(new Uint8Array()));
```

**Signature**

```ts
declare const validateBytesEffect: (
  value: Uint8Array<ArrayBufferLike> | undefined,
) => Effect.Effect<Uint8Array<ArrayBufferLike> | undefined, BucketProviderFailureError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L14)

### validateKeysEffect

Check listed keys while retaining provider order.

**Example**

```ts
Effect.runSync(validateKeysEffect(["a", "b"]));
```

**Signature**

```ts
declare const validateKeysEffect: (
  value: ReadonlyArray<string>,
) => Effect.Effect<Array<string>, BucketProviderFailureError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L53)

### validateMetadataEffect

Check metadata returned by a provider.

**Example**

```ts
Effect.runSync(validateMetadataEffect({ etag: "abc" }));
```

**Signature**

```ts
declare const validateMetadataEffect: (
  value: BucketObjectMetadata | undefined,
) => Effect.Effect<BucketObjectMetadata | undefined, BucketProviderFailureError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L27)

### validateUrlEffect

Check a signed URL result.

**Example**

```ts
Effect.runSync(validateUrlEffect("https://example.test/a", "createReadUrl"));
```

**Signature**

```ts
declare const validateUrlEffect: (
  value: string,
  operation: "createReadUrl" | "createWriteUrl",
) => Effect.Effect<string, BucketProviderFailureError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-results.ts#L67)

## `client-runtime.ts`

### BucketRuntime (class)

Injectable provider and invocation configuration.

**Example**

```ts
Effect.provide(getBucketEffect("a"), bucketRuntimeLayer(options));
```

**Signature**

```ts
declare class BucketRuntime
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L10)

### asProvider

Converts an optional source to a provider while retaining legacy validation.

**Throws**

BucketProviderError for non-object sources.

**Example**

```ts
asProvider(undefined);
```

**Signature**

```ts
declare const asProvider: (value: unknown) => BucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L50)

### asProviderEffect

Converts an optional source to a provider in Effect.

**Example**

```ts
Effect.runSync(asProviderEffect(undefined));
```

**Signature**

```ts
declare const asProviderEffect: (
  value: unknown,
) => Effect.Effect<BucketProvider, BucketProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L33)

### bucketRuntimeLayer

Creates a live runtime Layer from compatibility client options.

**Example**

```ts
bucketRuntimeLayer({ ownerId: "job", bucketId: "assets", source: {} });
```

**Signature**

```ts
declare const bucketRuntimeLayer: (
  options: BucketClientOptions,
) => Layer.Layer<BucketRuntime, BucketProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.ts#L19)

## `client-runtime.types.ts`

### BucketRuntimeService (interface)

Provider and invocation configuration supplied to bucket Effects.

**Example**

```ts
const runtime: BucketRuntimeService = { options, provider };
```

**Signature**

```ts
export interface BucketRuntimeService {
  readonly options: BucketClientOptions;
  readonly provider: BucketProvider;
  readonly bridgeOwned?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-runtime.types.ts#L6)

## `client-utils.ts`

### classifyEffect

Classifies a provider or cancellation failure in Effect.

**Example**

```ts
Effect.runSync(classifyEffect(new BucketOperationCancelledError()));
```

**Signature**

```ts
declare const classifyEffect: (
  value: unknown,
) => Effect.Effect<BucketOperationOutcome, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L67)

### notifyEffect

Calls an advisory hook without letting it affect provider behavior.

**Example**

```ts
Effect.runSync(notifyEffect((value) => console.log(value), "ready"));
```

**Signature**

```ts
declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L84)

### required

Synchronous compatibility adapter for a required provider method.

**Throws**

BucketProviderError when absent.

**Example**

```ts
required(provider.get, "get")("a");
```

**Signature**

```ts
declare const required: <A>(
  value: ((...args: any[]) => MaybePromise<A>) | undefined,
  operation: BucketOperation,
) => (...args: any[]) => MaybePromise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L37)

### requiredEffect

Requires an optional provider method in Effect.

**Example**

```ts
Effect.runSync(requiredEffect(provider.get, "get"));
```

**Signature**

```ts
declare const requiredEffect: <A>(
  value: ((...args: any[]) => MaybePromise<A>) | undefined,
  operation: BucketOperation,
) => Effect.Effect<(...args: any[]) => MaybePromise<A>, BucketProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L22)

### supportsEffect

Checks provider-advertised capabilities in Effect.

**Example**

```ts
Effect.runSync(supportsEffect(provider.capabilities, "signedReadUrl"));
```

**Signature**

```ts
declare const supportsEffect: (
  value: BucketCapabilities | ReadonlyArray<BucketCapability> | undefined,
  capability: BucketCapability,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client-utils.ts#L52)

## `client.ts`

### "./client.types.js" (namespace export)

Re-exports all named exports from the "./client.types.js" module.

**Signature**

```ts
export * from "./client.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L35)

### BucketCapabilityError

**Signature**

```ts
declare const BucketCapabilityError: typeof BucketCapabilityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L28)

### BucketDependencyError

**Signature**

```ts
declare const BucketDependencyError: typeof BucketDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L29)

### BucketOperationCancelledError

**Signature**

```ts
declare const BucketOperationCancelledError: typeof BucketOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L30)

### BucketOperationTimeoutError

**Signature**

```ts
declare const BucketOperationTimeoutError: typeof BucketOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L31)

### BucketProviderError

**Signature**

```ts
declare const BucketProviderError: typeof BucketProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L32)

### BucketProviderFailureError

**Signature**

```ts
declare const BucketProviderFailureError: typeof BucketProviderFailureError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L33)

### createBucketClient

Creates the Promise compatibility client over the Effect bucket operations.

**Throws**

TypeError for invalid owner or bucket identifiers; BucketProviderError for a malformed source.

**Example**

```ts
createBucketClient({ ownerId: "job", bucketId: "assets", source: provider }).get("a");
```

**Signature**

```ts
declare const createBucketClient: (options: BucketClientOptions) => BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L43)

### createBucketClientEffect

Creates the compatibility client inside Effect with tagged construction failures.

**Example**

```ts
Effect.runSync(createBucketClientEffect({ ownerId: "job", bucketId: "assets", source: {} }));
```

**Signature**

```ts
declare const createBucketClientEffect: (
  options: BucketClientOptions,
) => Effect.Effect<BucketClient, BucketValidationError | BucketProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.ts#L56)

## `client.types.ts`

### "./client-provider.types.js" (namespace export)

Re-exports all named exports from the "./client-provider.types.js" module.

**Signature**

```ts
export * from "./client-provider.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L8)

### BucketBridgeOptions (interface)

Metadata passed to an optional invocation bridge.

**Example**

```ts
const name = bridgeOptions.name;
```

**Signature**

```ts
export interface BucketBridgeOptions {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L71)

### BucketClient (interface)

Promise adapter used by existing RELKIT application code.

**Example**

```ts
await client.get("images/logo.png");
```

**Signature**

```ts
export interface BucketClient {
  /** Store content.
   * @param key - Portable key.
   * @param bytes - Content.
   * @param options - Optional metadata.
   * @returns Completion Promise or provider failure.
   * @example await client.put("a", new Uint8Array());
   */
  put(key: string, bytes: Uint8Array, options?: BucketPutOptions): Promise<void>;
  /** Read content.
   * @param key - Portable key.
   * @returns Bytes or undefined, or a rejected Promise.
   * @example await client.get("a");
   */
  get(key: string): Promise<Uint8Array | undefined>;
  /** Read metadata.
   * @param key - Portable key.
   * @returns Metadata or undefined, or a rejected Promise.
   * @example await client.head("a");
   */
  head(key: string): Promise<BucketObjectMetadata | undefined>;
  /** Delete content.
   * @param key - Portable key.
   * @returns Completion Promise or provider failure.
   * @example await client.delete("a");
   */
  delete(key: string): Promise<void>;
  /** Test for a key.
   * @param key - Portable key.
   * @returns Existence flag or a rejected Promise.
   * @example await client.exists("a");
   */
  exists(key: string): Promise<boolean>;
  /** List keys in provider order.
   * @param prefix - Optional portable prefix.
   * @returns Keys or a rejected Promise.
   * @example await client.list("images/");
   */
  list(prefix?: string): Promise<readonly string[]>;
  /** Request a signed download URL.
   * @param key - Portable key.
   * @returns URL or a rejected Promise.
   * @example await client.createReadUrl("a");
   */
  createReadUrl(key: string): Promise<string>;
  /** Request a signed upload URL.
   * @param key - Portable key.
   * @returns URL or a rejected Promise.
   * @example await client.createWriteUrl("a");
   */
  createWriteUrl(key: string): Promise<string>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L16)

### BucketClientOptions (interface)

Configuration for a Promise bucket client.

**Example**

```ts
const options: BucketClientOptions = { ownerId: "job", bucketId: "assets", source: {} };
```

**Signature**

```ts
export interface BucketClientOptions {
  readonly ownerId: string;
  readonly bucketId: string;
  readonly source: unknown;
  readonly bridge?: BucketInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly declared?: boolean;
  readonly onObservedEdge?: (edge: BucketObservedEdge) => void;
  readonly onOperation?: (operation: BucketOperationObservation) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L110)

### BucketInvocationBridge (interface)

Bridge that owns external invocation instrumentation.

**Example**

```ts
const bridge: BucketInvocationBridge = { run: async (operation) => operation() };
```

**Signature**

```ts
export interface BucketInvocationBridge {
  /** Invoke an operation through the bridge's tracing and cancellation boundary.
   * @param operation - Provider work to run.
   * @param options - Invocation name, attributes, signal, and input.
   * @returns The operation result or a rejected Promise.
   * @example await bridge.run(() => provider.get!("a"), { name: "bucket.get", attributes: {}, signal });
   */
  readonly run: <A>(operation: () => MaybePromise<A>, options?: BucketBridgeOptions) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L80)

### BucketObservedEdge (interface)

Observed function-to-bucket dependency edge.

**Example**

```ts
const edge: BucketObservedEdge = { relationship: "uses-bucket", from: "job", to: "assets" };
```

**Signature**

```ts
export interface BucketObservedEdge {
  readonly relationship: "uses-bucket";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L92)

### BucketOperationObservation (interface)

Advisory completion signal emitted after a bucket operation.

**Example**

```ts
const outcome = observation.outcome;
```

**Signature**

```ts
export interface BucketOperationObservation {
  readonly capability: "buckets";
  readonly operation: BucketOperation;
  readonly ownerId: string;
  readonly bucketId: string;
  readonly outcome: BucketOperationOutcome;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L100)

### BucketOperationOutcome (type alias)

Bounded outcome classification emitted to observation hooks.

**Signature**

```ts
type BucketOperationOutcome =
  "success" | "provider-failure" | "cancelled" | "timeout" | "unsupported";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/client.types.ts#L11)

## `define-bucket.ts`

### defineBucket

Defines a managed object store with explicit visibility and bounded upload policy.

**Throws**

TypeError when the authoring input is invalid.

**Example**

```ts
import { defineBucket } from "@relkit/buckets";
const assets = defineBucket({
  id: "assets",
  visibility: "public",
  maxObjectBytes: 1_048_576,
});
```

**Signature**

```ts
declare const defineBucket: <const Id extends string>(
  options: DefineBucketOptions<Id>,
) => BucketDescriptor<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L36)

Since v0.1.0

### "./define-bucket.types.js" (namespace export)

Re-exports all named exports from the "./define-bucket.types.js" module.

**Signature**

```ts
export * from "./define-bucket.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L17)

### BucketValidationError

**Signature**

```ts
declare const BucketValidationError: typeof BucketValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L18)

### assertBucketDescriptor

Narrows a value to BucketDescriptorAny or throws a compatibility TypeError.

**Throws**

TypeError when value is invalid.

**Example**

```ts
assertBucketDescriptor(defineBucket({ id: "assets", visibility: "private" }));
```

**Signature**

```ts
declare const assertBucketDescriptor: (value: unknown) => asserts value is BucketDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L177)

### assertBucketDescriptorEffect

Validates a bucket descriptor with a tagged Effect failure.

**Example**

```ts
Effect.runSync(assertBucketDescriptorEffect(defineBucket({ id: "a", visibility: "private" })));
```

**Signature**

```ts
declare const assertBucketDescriptorEffect: (
  value: unknown,
) => Effect.Effect<void, BucketValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L186)

### defineBucketEffect

Defines a bucket in Effect, exposing invalid input as a tagged error.

**Example**

```ts
Effect.runSync(defineBucketEffect({ id: "assets", visibility: "private" }));
```

**Signature**

```ts
declare const defineBucketEffect: <const Id extends string>(
  options: DefineBucketOptions<Id>,
) => Effect.Effect<BucketDescriptor<Id>, BucketValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L47)

### isBucketDescriptor

Checks whether a value is a well-formed bucket descriptor.

**Example**

```ts
isBucketDescriptor(defineBucket({ id: "assets", visibility: "private" }));
```

**Signature**

```ts
declare const isBucketDescriptor: (value: unknown) => value is BucketDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L124)

### isBucketDescriptorEffect

Effectful descriptor predicate for composition inside workflows.

**Example**

```ts
Effect.runSync(isBucketDescriptorEffect({}));
```

**Signature**

```ts
declare const isBucketDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.ts#L133)

## `define-bucket.types.ts`

### BucketDescriptor (interface)

Immutable authored bucket descriptor.

**Example**

```ts
const bucket: BucketDescriptor<"assets"> = defineBucket({ id: "assets", visibility: "private" });
```

**Signature**

```ts
export interface BucketDescriptor<Id extends string> extends DescriptorBase<"bucket", Id> {
  readonly profile?: string;
  readonly visibility: BucketVisibility;
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L11)

### BucketDescriptorAny (type alias)

Bucket descriptor with an arbitrary stable identifier.

**Example**

```ts
const bucket: BucketDescriptorAny = defineBucket({ id: "assets", visibility: "private" });
```

**Signature**

```ts
type BucketDescriptorAny = BucketDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L21)

### BucketVisibility (type alias)

Visibility policy for a bucket.

**Example**

```ts
const visibility: BucketVisibility = "private";
```

**Signature**

```ts
type BucketVisibility = "private" | "public";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L6)

### DefineBucketOptions (interface)

Input accepted when defining a bucket.

**Example**

```ts
const options: DefineBucketOptions<"assets"> = { id: "assets", visibility: "private" };
```

**Signature**

```ts
export interface DefineBucketOptions<Id extends string> extends DescriptorMetadata {
  readonly id: Id;
  readonly profile?: string;
  readonly visibility: BucketVisibility;
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/define-bucket.types.ts#L26)

## `index.ts`

### "./bucket-validation-error.js" (namespace export)

Re-exports all named exports from the "./bucket-validation-error.js" module.

**Signature**

```ts
export * from "./bucket-validation-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L2)

### "./client-effects.js" (namespace export)

Re-exports all named exports from the "./client-effects.js" module.

**Signature**

```ts
export * from "./client-effects.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L4)

### "./client-observability.js" (namespace export)

Re-exports all named exports from the "./client-observability.js" module.

**Signature**

```ts
export * from "./client-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L6)

### "./client-runtime.js" (namespace export)

Re-exports all named exports from the "./client-runtime.js" module.

**Signature**

```ts
export * from "./client-runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L5)

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L3)

### "./define-bucket.js" (namespace export)

Re-exports all named exports from the "./define-bucket.js" module.

**Signature**

```ts
export * from "./define-bucket.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/buckets/src/index.ts#L1)

---

# Cache API
Source: https://relkit.dev/docs/api/cache

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineCache](/docs/api/cache#definecache)

For configuration and examples, read [define](/docs/modules/caching/define), [organization](/docs/modules/service/organization), [rate limits](/docs/modules/http/rate-limits).

For a complete workflow, follow [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/cache` — 50 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                    | Kind  | Import from     | Example                                                             |
| -------------------------------------------------------------------------------------- | ----- | --------------- | ------------------------------------------------------------------- |
| [assertCacheDescriptor](/docs/api/cache#assertcachedescriptor)                         | Value | `@relkit/cache` | [API example](/docs/api/cache#assertcachedescriptor)                |
| [assertCacheDescriptorEffect](/docs/api/cache#assertcachedescriptoreffect)             | Value | `@relkit/cache` | [API example](/docs/api/cache#assertcachedescriptoreffect)          |
| [CacheBridgeOptions](/docs/api/cache#cachebridgeoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachebridgeoptions-interface)         |
| [CacheCapabilities](/docs/api/cache#cachecapabilities-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachecapabilities-interface)          |
| [CacheCapability](/docs/api/cache#cachecapability-type-alias)                          | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachecapability-type-alias)           |
| [CacheCapabilityError](/docs/api/cache#cachecapabilityerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachecapabilityerror-class)           |
| [CacheClient](/docs/api/cache#cacheclient-type-alias)                                  | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclient-type-alias)               |
| [CacheClientBase](/docs/api/cache#cacheclientbase-interface)                           | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclientbase-interface)            |
| [CacheClientOptions](/docs/api/cache#cacheclientoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheclientoptions-interface)         |
| [CacheDependencyError](/docs/api/cache#cachedependencyerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachedependencyerror-class)           |
| [CacheDescriptor](/docs/api/cache#cachedescriptor-interface)                           | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptor-interface)            |
| [CacheDescriptorAny](/docs/api/cache#cachedescriptorany-type-alias)                    | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorany-type-alias)        |
| [CacheDescriptorError](/docs/api/cache#cachedescriptorerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorerror-class)           |
| [CacheDescriptorPolicy](/docs/api/cache#cachedescriptorpolicy-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachedescriptorpolicy-interface)      |
| [CacheEffectClient](/docs/api/cache#cacheeffectclient-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheeffectclient-interface)          |
| [CacheIncrementUnsupportedError](/docs/api/cache#cacheincrementunsupportederror-class) | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheincrementunsupportederror-class) |
| [CacheInvocationBridge](/docs/api/cache#cacheinvocationbridge-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheinvocationbridge-interface)      |
| [CacheNumericClient](/docs/api/cache#cachenumericclient-type-alias)                    | Type  | `@relkit/cache` | [API example](/docs/api/cache#cachenumericclient-type-alias)        |
| [CacheObservedEdge](/docs/api/cache#cacheobservededge-interface)                       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheobservededge-interface)          |
| [CacheOperation](/docs/api/cache#cacheoperation-type-alias)                            | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperation-type-alias)            |
| [CacheOperationCancelledError](/docs/api/cache#cacheoperationcancellederror-class)     | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationcancellederror-class)   |
| [CacheOperationContext](/docs/api/cache#cacheoperationcontext-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationcontext-interface)      |
| [CacheOperationError](/docs/api/cache#cacheoperationerror-type-alias)                  | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationerror-type-alias)       |
| [CacheOperationObservation](/docs/api/cache#cacheoperationobservation-interface)       | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationobservation-interface)  |
| [CacheOperationOptions](/docs/api/cache#cacheoperationoptions-interface)               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationoptions-interface)      |
| [CacheOperationOutcome](/docs/api/cache#cacheoperationoutcome-type-alias)              | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationoutcome-type-alias)     |
| [CacheOperationTimeoutError](/docs/api/cache#cacheoperationtimeouterror-class)         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheoperationtimeouterror-class)     |
| [CacheProvider](/docs/api/cache#cacheprovider-interface)                               | Type  | `@relkit/cache` | [API example](/docs/api/cache#cacheprovider-interface)              |
| [CacheProviderError](/docs/api/cache#cacheprovidererror-class)                         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheprovidererror-class)             |
| [CacheProviderFailureError](/docs/api/cache#cacheproviderfailureerror-class)           | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheproviderfailureerror-class)      |
| [CacheRuntime](/docs/api/cache#cacheruntime-class)                                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheruntime-class)                   |
| [cacheRuntimeLayer](/docs/api/cache#cacheruntimelayer)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheruntimelayer)                    |
| [CacheSchemaValidationError](/docs/api/cache#cacheschemavalidationerror-class)         | Value | `@relkit/cache` | [API example](/docs/api/cache#cacheschemavalidationerror-class)     |
| [CacheTelemetry](/docs/api/cache#cachetelemetry-class)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#cachetelemetry-class)                 |
| [CacheTelemetryLive](/docs/api/cache#cachetelemetrylive)                               | Value | `@relkit/cache` | [API example](/docs/api/cache#cachetelemetrylive)                   |
| [CacheTtlPolicyError](/docs/api/cache#cachettlpolicyerror-class)                       | Value | `@relkit/cache` | [API example](/docs/api/cache#cachettlpolicyerror-class)            |
| [CacheValidationError](/docs/api/cache#cachevalidationerror-class)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#cachevalidationerror-class)           |
| [createCacheClient](/docs/api/cache#createcacheclient)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#createcacheclient)                    |
| [createCacheClientEffect](/docs/api/cache#createcacheclienteffect)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#createcacheclienteffect)              |
| [defineCache](/docs/api/cache#definecache)                                             | Value | `@relkit/cache` | [API example](/docs/api/cache#definecache)                          |
| [defineCacheEffect](/docs/api/cache#definecacheeffect)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#definecacheeffect)                    |
| [DefineCacheOptions](/docs/api/cache#definecacheoptions-interface)                     | Type  | `@relkit/cache` | [API example](/docs/api/cache#definecacheoptions-interface)         |
| [deleteCacheEffect](/docs/api/cache#deletecacheeffect)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#deletecacheeffect)                    |
| [getCacheEffect](/docs/api/cache#getcacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#getcacheeffect)                       |
| [getOrSetCacheEffect](/docs/api/cache#getorsetcacheeffect)                             | Value | `@relkit/cache` | [API example](/docs/api/cache#getorsetcacheeffect)                  |
| [hasCacheEffect](/docs/api/cache#hascacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#hascacheeffect)                       |
| [incrementCacheEffect](/docs/api/cache#incrementcacheeffect)                           | Value | `@relkit/cache` | [API example](/docs/api/cache#incrementcacheeffect)                 |
| [isCacheDescriptor](/docs/api/cache#iscachedescriptor)                                 | Value | `@relkit/cache` | [API example](/docs/api/cache#iscachedescriptor)                    |
| [isCacheDescriptorEffect](/docs/api/cache#iscachedescriptoreffect)                     | Value | `@relkit/cache` | [API example](/docs/api/cache#iscachedescriptoreffect)              |
| [setCacheEffect](/docs/api/cache#setcacheeffect)                                       | Value | `@relkit/cache` | [API example](/docs/api/cache#setcacheeffect)                       |

## `client-abort.ts`

### runAbortableEffect

Guards provider work with a scoped abort listener and an absolute deadline.

**Example**

```ts
Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, Effect.succeed(1)));
```

**Signature**

```ts
declare const runAbortableEffect: <A, E, R>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | CacheOperationCancelledError | CacheOperationTimeoutError, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-abort.ts#L10)

## `client-effects.ts`

### deleteCacheEffect

Deletes one key.

**Example**

```ts
Effect.provide(deleteCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const deleteCacheEffect: (
  key: unknown,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L77)

### getCacheEffect

Reads a decoded cache value.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const getCacheEffect: (
  key: unknown,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L17)

### getOrSetCacheEffect

Reads or produces and stores one value through the provider.

**Example**

```ts
Effect.provide(
  getOrSetCacheEffect("sku", () => 1),
  cacheRuntimeLayer(options),
);
```

**Signature**

```ts
declare const getOrSetCacheEffect: (
  key: unknown,
  produce: () => MaybePromise<unknown>,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L126)

### hasCacheEffect

Checks key presence.

**Example**

```ts
Effect.provide(hasCacheEffect("sku"), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const hasCacheEffect: (
  key: unknown,
) => Effect.Effect<boolean, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L100)

### setCacheEffect

Writes a validated key and value.

**Example**

```ts
Effect.provide(setCacheEffect("sku", 1), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const setCacheEffect: (
  key: unknown,
  value: unknown,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-effects.ts#L46)

## `client-errors.ts`

### CacheCapabilityError (class)

The provider lacks a declared cache capability.

**Example**

```ts
new CacheCapabilityError("increment", "increment");
```

**Signature**

```ts
declare class CacheCapabilityError {
  constructor(capability: CacheCapability, operation: CacheOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L9)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_CAPABILITY_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L13)

### CacheDependencyError (class)

A function used an undeclared cache.

**Example**

```ts
new CacheDependencyError("prices");
```

**Signature**

```ts
declare class CacheDependencyError {
  constructor(cacheId: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L25)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L29)

### CacheIncrementUnsupportedError (class)

Increment needs a numeric value contract.

**Example**

```ts
new CacheIncrementUnsupportedError();
```

**Signature**

```ts
declare class CacheIncrementUnsupportedError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L86)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_INCREMENT_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L90)

### CacheOperationCancelledError (class)

Caller cancellation of an operation.

**Example**

```ts
new CacheOperationCancelledError();
```

**Signature**

```ts
declare class CacheOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L101)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L105)

### CacheOperationTimeoutError (class)

Deadline expiration of an operation.

**Example**

```ts
new CacheOperationTimeoutError();
```

**Signature**

```ts
declare class CacheOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L119)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L123)

### CacheProviderError (class)

The provider omits an operation.

**Example**

```ts
new CacheProviderError("get");
```

**Signature**

```ts
declare class CacheProviderError {
  constructor(operation: CacheOperation);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L41)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L45)

### CacheProviderFailureError (class)

Provider rejection with its original cause retained.

**Example**

```ts
new CacheProviderFailureError({ operation: "get", cause: "offline" });
```

**Signature**

```ts
declare class CacheProviderFailureError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L138)

### CacheSchemaValidationError (class)

A tagged schema failure retaining its legacy TypeError classification.

**Example**

```ts
new CacheSchemaValidationError("key", [{ message: "Invalid key" }]);
```

**Signature**

```ts
declare class CacheSchemaValidationError { constructor(
    readonly phase: "key" | "value",
    readonly issues: readonly StandardIssue[],
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L58)

### \_tag (property)

**Signature**

```ts
readonly _tag: "CacheSchemaValidationError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L59)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_SCHEMA_VALIDATION"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L60)

### CacheTtlPolicyError (class)

A tagged TTL violation retaining its legacy RangeError classification.

**Example**

```ts
new CacheTtlPolicyError("Cache ttlMs must be a positive integer");
```

**Signature**

```ts
declare class CacheTtlPolicyError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L73)

### \_tag (property)

**Signature**

```ts
readonly _tag: "CacheTtlPolicyError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L74)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_TTL_POLICY"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L75)

### reason (property)

**Signature**

```ts
readonly reason: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L76)

### CacheValidationError (class)

Invalid non-schema input or provider result.

**Example**

```ts
new CacheValidationError({ reason: "Cache has must return a boolean" });
```

**Signature**

```ts
declare class CacheValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-errors.ts#L146)

## `client-increment.ts`

### incrementCacheEffect

Increments a numeric cache value.

**Example**

```ts
Effect.provide(incrementCacheEffect("sku", 2), cacheRuntimeLayer(options));
```

**Signature**

```ts
declare const incrementCacheEffect: (
  key: unknown,
  delta?: any,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<number, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-increment.ts#L19)

## `client-observability.ts`

### CacheTelemetry (class)

Injectable telemetry for cache Effect operations.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), CacheTelemetryLive);
```

**Signature**

```ts
declare class CacheTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L9)

### CacheTelemetryLive

Default spans and bounded Effect metrics.

**Example**

```ts
Effect.provide(getCacheEffect("sku"), CacheTelemetryLive);
```

**Signature**

```ts
declare const CacheTelemetryLive: Layer.Layer<CacheTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L15)

### observeCache

Observes an operation through an optional test Layer or default telemetry.

**Example**

```ts
observeCache("get", Effect.succeed(undefined));
```

**Signature**

```ts
declare const observeCache: <A, E, R>(
  operation: CacheObservedOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.ts#L27)

## `client-observability.types.ts`

### CacheObservedEdge (interface)

A declared dependency edge observed without any cache key or value.

**Example**

```ts
const edge: CacheObservedEdge = { relationship: "uses-cache", from: "orders", to: "prices" };
```

**Signature**

```ts
export interface CacheObservedEdge {
  readonly relationship: "uses-cache";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L12)

### CacheObservedOperation (type alias)

Names of observed public cache operations.

**Example**

```ts
const operation: CacheObservedOperation = "get";
```

**Signature**

```ts
type CacheObservedOperation =
  CacheOperation | "define" | "isDescriptor" | "assertDescriptor" | "createClient";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L7)

### CacheOperationObservation (interface)

One operation outcome with bounded, input-free fields.

**Example**

```ts
const event: CacheOperationObservation = {
  capability: "cache",
  operation: "get",
  ownerId: "orders",
  cacheId: "prices",
  outcome: "success",
};
```

**Signature**

```ts
export interface CacheOperationObservation {
  readonly capability: "cache";
  readonly operation: CacheOperation;
  readonly ownerId: string;
  readonly cacheId: string;
  readonly outcome: CacheOperationOutcome;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L20)

### CacheTelemetryService (interface)

Replaceable telemetry boundary for cache Effect calls.

**Example**

```ts
const telemetry: CacheTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface CacheTelemetryService {
  /** Wraps an operation with tracing and metrics.
   * @param operation - Stable operation name.
   * @param effect - Work to observe.
   * @returns The same Effect success and error channels.
   * @example telemetry.observe("get", Effect.succeed(undefined));
   */
  readonly observe: <A, E, R>(
    operation: CacheObservedOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-observability.types.ts#L30)

## `client-operation.ts`

### invokeProvider

Invokes an optional provider method in the typed error channel.

**Example**

```ts
Effect.runPromise(invokeProvider("get", async () => 1, ["sku"]));
```

**Signature**

```ts
declare const invokeProvider: <A>(
  operation: CacheOperation,
  method: ((...args: any[]) => A | PromiseLike<A>) | undefined,
  args: Array<unknown>,
) => Effect.Effect<Awaited<A>, CacheOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.ts#L30)

### runCacheOperation

Executes provider work with injectable runtime, bridge, cancellation, and hooks.

**Example**

```ts
Effect.provide(
  runCacheOperation({ operation: "get", input: {}, work: () => Effect.succeed(1) }),
  layer,
);
```

**Signature**

```ts
declare const runCacheOperation: <A>(
  invocation: CacheInvocation<A>,
) => Effect.Effect<A, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.ts#L50)

## `client-operation.types.ts`

### CacheCapabilities (interface)

Provider-declared feature support.

**Example**

```ts
const capabilities: CacheCapabilities = { increment: true };
```

**Signature**

```ts
export interface CacheCapabilities {
  readonly increment?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L34)

### CacheCapability (type alias)

Provider feature negotiated before executing an operation.

**Example**

```ts
const capability: CacheCapability = "increment";
```

**Signature**

```ts
type CacheCapability = "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L11)

### CacheInvocation (interface)

Provider invocation and its typed Effect work.

**Example**

```ts
const invocation: CacheInvocation<number> = {
  operation: "get",
  input: {},
  work: () => Effect.succeed(1),
};
```

**Signature**

```ts
export interface CacheInvocation<A> {
  readonly operation: CacheOperation;
  readonly input: unknown;
  readonly capability?: "increment";
  /** Builds validated provider work inside the cache runtime.
   * @param provider - Injected provider.
   * @param context - Cancellation and deadline context.
   * @returns Effect of the operation result or a typed cache failure.
   * @example invocation.work(provider, context);
   */
  readonly work: (
    provider: CacheProvider,
    context: CacheOperationContext,
  ) => Effect.Effect<A, CacheOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L112)

### CacheOperation (type alias)

Fixed cache method names used for spans and metrics.

**Example**

```ts
const operation: CacheOperation = "get";
```

**Signature**

```ts
type CacheOperation = "get" | "set" | "delete" | "has" | "getOrSet" | "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L7)

### CacheOperationContext (interface)

Cancellation and deadline data passed to a provider call.

**Example**

```ts
const context: CacheOperationContext = { operation: "get", signal: new AbortController().signal };
```

**Signature**

```ts
export interface CacheOperationContext {
  readonly operation: CacheOperation;
  readonly signal: AbortSignal;
  readonly deadlineMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L26)

### CacheOperationOptions (interface)

Optional write or increment TTL in milliseconds.

**Example**

```ts
const options: CacheOperationOptions = { ttlMs: 1000 };
```

**Signature**

```ts
export interface CacheOperationOptions {
  readonly ttlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L20)

### CacheOperationOutcome (type alias)

Stable operation outcomes for RELKIT observations.

**Example**

```ts
const outcome: CacheOperationOutcome = "success";
```

**Signature**

```ts
type CacheOperationOutcome =
  "success" | "provider-failure" | "cancelled" | "timeout" | "unsupported" | "validation-error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L15)

### CacheProvider (interface)

Optional provider methods; missing methods fail with CacheProviderError.

**Example**

```ts
const provider: CacheProvider = { get: async () => undefined };
```

**Signature**

```ts
export interface CacheProvider {
  readonly capabilities?: CacheCapabilities | readonly CacheCapability[];
  /** Reads one key.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Stored value or undefined.
   * @example await provider.get?.("sku", context);
   */
  readonly get?: (
    key: unknown,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown | undefined>;
  /** Writes one entry.
   * @param key - Provider key.
   * @param value - Validated value.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Completion.
   * @example await provider.set?.("sku", 1);
   */
  readonly set?: (
    key: unknown,
    value: unknown,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<void>;
  /** Deletes one key.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Completion.
   * @example await provider.delete?.("sku");
   */
  readonly delete?: (key: unknown, context?: CacheOperationContext) => MaybePromise<void>;
  /** Tests key presence.
   * @param key - Provider key.
   * @param context - Cancellation and deadline context.
   * @returns Presence.
   * @example await provider.has?.("sku");
   */
  readonly has?: (key: unknown, context?: CacheOperationContext) => MaybePromise<boolean>;
  /** Reads or fills a key.
   * @param key - Provider key.
   * @param produce - Miss producer.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Stored or produced value.
   * @example await provider.getOrSet?.("sku", () => 1);
   */
  readonly getOrSet?: (
    key: unknown,
    produce: () => MaybePromise<unknown>,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown>;
  /** Increments a numeric entry.
   * @param key - Provider key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @param context - Cancellation and deadline context.
   * @returns Updated numeric value.
   * @example await provider.increment?.("sku", 2);
   */
  readonly increment?: (
    key: unknown,
    delta: number,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => MaybePromise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-operation.types.ts#L40)

## `client-runtime.ts`

### CacheRuntime (class)

Substitutable provider and invocation configuration.

**Example**

```ts
Effect.provide(
  getCacheEffect("sku"),
  cacheRuntimeLayer({ ownerId: "orders", cacheId: "prices", source: {} }),
);
```

**Signature**

```ts
declare class CacheRuntime
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L12)

### asProviderEffect

Validates the provider source in Effect.

**Example**

```ts
Effect.runSync(asProviderEffect(undefined));
```

**Signature**

```ts
declare const asProviderEffect: (
  value: unknown,
) => Effect.Effect<CacheProvider, CacheProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L36)

### cacheRuntimeLayer

Creates the live provider Layer from client options.

**Example**

```ts
cacheRuntimeLayer({ ownerId: "orders", cacheId: "prices", source: {} });
```

**Signature**

```ts
declare const cacheRuntimeLayer: (
  options: CacheClientOptions,
) => Layer.Layer<
  CacheRuntime,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.ts#L20)

## `client-runtime.types.ts`

### CacheBridgeOptions (interface)

Metadata sent to an invocation bridge.

**Example**

```ts
const options: CacheBridgeOptions = {
  name: "cache.get",
  attributes: {},
  signal: new AbortController().signal,
};
```

**Signature**

```ts
export interface CacheBridgeOptions {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L7)

### CacheInvocationBridge (interface)

Existing invocation bridge contract.

**Example**

```ts
const bridge: CacheInvocationBridge = { run: async (operation) => operation() };
```

**Signature**

```ts
export interface CacheInvocationBridge {
  /** Runs one operation in the existing invocation boundary.
   * @param operation - Deferred operation callback.
   * @param options - Span metadata, signal, and input.
   * @returns Operation value or rejection.
   * @example bridge.run(() => Promise.resolve(1));
   */
  readonly run: <A>(operation: () => MaybePromise<A>, options?: CacheBridgeOptions) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L16)

### CacheRuntimeService (interface)

Provider and options supplied to cache Effect operations.

**Example**

```ts
const runtime: CacheRuntimeService = { options, provider };
```

**Signature**

```ts
export interface CacheRuntimeService {
  readonly options: CacheClientOptions;
  readonly provider: CacheProvider;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-runtime.types.ts#L28)

## `client-validation-effect.ts`

### normalizeTtlEffect

Normalizes a requested TTL against the configured policy.

**Example**

```ts
Effect.runSync(normalizeTtlEffect(undefined, 1000, 5000));
```

**Signature**

```ts
declare const normalizeTtlEffect: (
  value: unknown,
  defaultTtlMs: number | undefined,
  maxTtlMs: number | undefined,
) => Effect.Effect<{ ttlMs: number } | undefined, CacheTtlPolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L91)

### validateBooleanEffect

Validates a provider has result.

**Example**

```ts
Effect.runSync(validateBooleanEffect(true));
```

**Signature**

```ts
declare const validateBooleanEffect: (
  value: unknown,
) => Effect.Effect<boolean, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L125)

### validateClientIdentityEffect

Validates client identity before a provider is acquired.

**Example**

```ts
Effect.runSync(validateClientIdentityEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const validateClientIdentityEffect: (
  options: CacheClientOptions<
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>
  >,
) => Effect.Effect<undefined, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L14)

### validateClientPolicyEffect

Validates schemas and TTL policy after the provider source.

**Example**

```ts
Effect.runSync(validateClientPolicyEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const validateClientPolicyEffect: (
  options: CacheClientOptions<
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>
  >,
) => Effect.Effect<undefined, CacheTtlPolicyError | CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L27)

### validateIncrementDeltaEffect

Validates a finite increment delta.

**Example**

```ts
Effect.runSync(validateIncrementDeltaEffect(2));
```

**Signature**

```ts
declare const validateIncrementDeltaEffect: (
  value: unknown,
) => Effect.Effect<number, CacheValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L135)

### validatePolicyEffect

Validates configured policy numbers.

**Example**

```ts
Effect.runSync(validatePolicyEffect(1000, "defaultTtlMs"));
```

**Signature**

```ts
declare const validatePolicyEffect: (
  value: number | undefined,
  name: string,
) => Effect.Effect<undefined, CacheTtlPolicyError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L113)

### validateSchemaEffect

Validates a value through Standard Schema in the typed error channel.

**Example**

```ts
Effect.runPromise(validateSchemaEffect(undefined, "sku", "key"));
```

**Signature**

```ts
declare const validateSchemaEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  value: unknown,
  phase: "value" | "key",
) => Effect.Effect<unknown, CacheSchemaValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client-validation-effect.ts#L69)

## `client.ts`

### "./client.types.js" (namespace export)

Re-exports all named exports from the "./client.types.js" module.

**Signature**

```ts
export * from "./client.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L31)

### CacheCapabilityError

**Signature**

```ts
declare const CacheCapabilityError: typeof CacheCapabilityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L20)

### CacheDependencyError

**Signature**

```ts
declare const CacheDependencyError: typeof CacheDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L21)

### CacheIncrementUnsupportedError

**Signature**

```ts
declare const CacheIncrementUnsupportedError: typeof CacheIncrementUnsupportedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L22)

### CacheOperationCancelledError

**Signature**

```ts
declare const CacheOperationCancelledError: typeof CacheOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L23)

### CacheOperationTimeoutError

**Signature**

```ts
declare const CacheOperationTimeoutError: typeof CacheOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L24)

### CacheProviderError

**Signature**

```ts
declare const CacheProviderError: typeof CacheProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L25)

### CacheProviderFailureError

**Signature**

```ts
declare const CacheProviderFailureError: typeof CacheProviderFailureError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L26)

### CacheRuntime

**Signature**

```ts
declare const CacheRuntime: typeof CacheRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L40)

### CacheSchemaValidationError

**Signature**

```ts
declare const CacheSchemaValidationError: typeof CacheSchemaValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L27)

### CacheTelemetry

**Signature**

```ts
declare const CacheTelemetry: typeof CacheTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L41)

### CacheTelemetryLive

**Signature**

```ts
declare const CacheTelemetryLive: Layer.Layer<CacheTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L41)

### CacheTtlPolicyError

**Signature**

```ts
declare const CacheTtlPolicyError: typeof CacheTtlPolicyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L28)

### CacheValidationError

**Signature**

```ts
declare const CacheValidationError: typeof CacheValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L29)

### cacheRuntimeLayer

**Signature**

```ts
declare const cacheRuntimeLayer: (
  options: CacheClientOptions,
) => Layer.Layer<
  CacheRuntime,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L40)

### createCacheClient

Constructs the existing Promise cache client from its Effect implementation.

**Throws**

TypeError for invalid configuration, or a tagged cache policy/provider error.

**Example**

```ts
createCacheClient({ ownerId: "orders", cacheId: "prices", source: {} });
```

**Signature**

```ts
declare const createCacheClient: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: CacheClientOptions<KeySchema, ValueSchema>,
) => CacheClient<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L92)

### createCacheClientEffect

Constructs an Effect-first cache client with a validated provider.

**Example**

```ts
Effect.runSync(createCacheClientEffect({ ownerId: "orders", cacheId: "prices", source: {} }));
```

**Signature**

```ts
declare const createCacheClientEffect: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: CacheClientOptions<KeySchema, ValueSchema>,
) => Effect.Effect<
  CacheEffectClient<InferInput<KeySchema>, InferOutput<ValueSchema>>,
  CacheProviderError | CacheTtlPolicyError | CacheValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L47)

### deleteCacheEffect

**Signature**

```ts
declare const deleteCacheEffect: (
  key: unknown,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L33)

### getCacheEffect

**Signature**

```ts
declare const getCacheEffect: (
  key: unknown,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L34)

### getOrSetCacheEffect

**Signature**

```ts
declare const getOrSetCacheEffect: (
  key: unknown,
  produce: () => MaybePromise<unknown>,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<unknown, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L35)

### hasCacheEffect

**Signature**

```ts
declare const hasCacheEffect: (
  key: unknown,
) => Effect.Effect<boolean, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L36)

### incrementCacheEffect

**Signature**

```ts
declare const incrementCacheEffect: (
  key: unknown,
  delta?: any,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<number, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L39)

### setCacheEffect

**Signature**

```ts
declare const setCacheEffect: (
  key: unknown,
  value: unknown,
  settings?: { ttlMs?: number } | undefined,
) => Effect.Effect<void, CacheOperationError, CacheRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.ts#L37)

## `client.types.ts`

### CacheBridgeOptions

**Signature**

```ts
declare const CacheBridgeOptions: CacheBridgeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L162)

### CacheCapabilities

**Signature**

```ts
declare const CacheCapabilities: CacheCapabilities;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L21)

### CacheCapability

**Signature**

```ts
declare const CacheCapability: "increment";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L20)

### CacheClient (type alias)

Promise client with increment exposed only for numeric value types.

**Example**

```ts
const value = await client.get("sku");
```

**Signature**

```ts
type CacheClient<Key, Value> = CacheClientBase<Key, Value> &
  ([Value] extends [number] ? CacheNumericClient<Key, Value> : object);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L87)

### CacheClientBase (interface)

Promise methods retained for existing callers.

**Example**

```ts
const value = await client.get("sku");
```

**Signature**

```ts
export interface CacheClientBase<Key, Value> {
  /** Reads one decoded value.
   * @param key - Cache key.
   * @returns Value or undefined, or a rejected cache error.
   * @example await client.get("sku");
   */
  get(key: Key): Promise<Value | undefined>;
  /** Writes a value.
   * @param key - Cache key.
   * @param value - Value to store.
   * @param options - Optional TTL.
   * @returns Completion or a rejected cache error.
   * @example await client.set("sku", 1);
   */
  set(key: Key, value: Value, options?: CacheOperationOptions): Promise<void>;
  /** Removes one entry.
   * @param key - Cache key.
   * @returns Completion or a rejected cache error.
   * @example await client.delete("sku");
   */
  delete(key: Key): Promise<void>;
  /** Tests whether a key exists.
   * @param key - Cache key.
   * @returns Presence or a rejected cache error.
   * @example await client.has("sku");
   */
  has(key: Key): Promise<boolean>;
  /** Reads or produces one value.
   * @param key - Cache key.
   * @param produce - Called only on a cache miss.
   * @param options - Optional TTL.
   * @returns Value or a rejected cache error.
   * @example await client.getOrSet("sku", () => 1);
   */
  getOrSet(
    key: Key,
    produce: () => MaybePromise<Value>,
    options?: CacheOperationOptions,
  ): Promise<Value>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L31)

### CacheClientOptions (interface)

Client configuration and advisory observation hooks.

**Example**

```ts
const options: CacheClientOptions = { ownerId: "orders", cacheId: "prices", source: {} };
```

**Signature**

```ts
export interface CacheClientOptions<
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly ownerId: string;
  readonly cacheId: string;
  readonly source: unknown;
  readonly keySchema?: KeySchema;
  readonly valueSchema?: ValueSchema;
  readonly key?: KeySchema;
  readonly value?: ValueSchema;
  readonly descriptor?: CacheDescriptorPolicy;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly bridge?: CacheInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly declared?: boolean;
  readonly onObservedEdge?: (edge: CacheObservedEdge) => void;
  readonly onOperation?: (operation: CacheOperationObservation) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L176)

### CacheDescriptorPolicy (interface)

Descriptor schema and TTL defaults used by a client.

**Example**

```ts
const policy: CacheDescriptorPolicy = { defaultTtlMs: 1000 };
```

**Signature**

```ts
export interface CacheDescriptorPolicy {
  readonly key?: StandardSchemaV1;
  readonly value?: StandardSchemaV1;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L167)

### CacheEffectClient (interface)

Effect-first cache operations; each call can be composed or provided with a test Layer.

**Example**

```ts
const value = await Effect.runPromise(client.get("sku"));
```

**Signature**

```ts
export interface CacheEffectClient<Key, Value> {
  /** Reads a key.
   * @param key - Cache key.
   * @returns Effect of value, undefined, or CacheOperationError.
   * @example client.get("sku");
   */
  get(key: Key): Effect.Effect<Value | undefined, CacheOperationError>;
  /** Writes a value.
   * @param key - Cache key.
   * @param value - Value to store.
   * @param options - Optional TTL.
   * @returns Effect of void or CacheOperationError.
   * @example client.set("sku", 1);
   */
  set(
    key: Key,
    value: Value,
    options?: CacheOperationOptions,
  ): Effect.Effect<void, CacheOperationError>;
  /** Deletes one key.
   * @param key - Cache key.
   * @returns Effect of void or CacheOperationError.
   * @example client.delete("sku");
   */
  delete(key: Key): Effect.Effect<void, CacheOperationError>;
  /** Tests for a key.
   * @param key - Cache key.
   * @returns Effect of boolean or CacheOperationError.
   * @example client.has("sku");
   */
  has(key: Key): Effect.Effect<boolean, CacheOperationError>;
  /** Reads or produces a value.
   * @param key - Cache key.
   * @param produce - Miss producer.
   * @param options - Optional TTL.
   * @returns Effect of value or CacheOperationError.
   * @example client.getOrSet("sku", () => 1);
   */
  getOrSet(
    key: Key,
    produce: () => MaybePromise<Value>,
    options?: CacheOperationOptions,
  ): Effect.Effect<Value, CacheOperationError>;
  /** Increments a numeric value.
   * @param key - Cache key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @returns Effect of number or CacheOperationError.
   * @example client.increment("sku", 2);
   */
  increment(
    key: Key,
    delta?: number,
    options?: CacheOperationOptions,
  ): Effect.Effect<number, CacheOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L106)

### CacheInvocationBridge

**Signature**

```ts
declare const CacheInvocationBridge: CacheInvocationBridge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L162)

### CacheNumericClient (type alias)

Increment method exposed for numeric value contracts.

**Example**

```ts
await numericClient.increment("sku", 2);
```

**Signature**

```ts
type CacheNumericClient<Key, Value extends number> = {
  /** Increments a numeric value.
   * @param key - Cache key.
   * @param delta - Finite increment.
   * @param options - Optional TTL.
   * @returns Updated value or a rejected cache error.
   * @example await numericClient.increment("sku", 2);
   */
  increment(key: Key, delta?: number, options?: CacheOperationOptions): Promise<Value>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L74)

### CacheObservedEdge

**Signature**

```ts
declare const CacheObservedEdge: CacheObservedEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L163)

### CacheOperation

**Signature**

```ts
declare const CacheOperation: CacheOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L22)

### CacheOperationContext

**Signature**

```ts
declare const CacheOperationContext: CacheOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L23)

### CacheOperationError (type alias)

Expected failures from a cache Effect operation.

**Example**

```ts
Effect.catchTag("CacheProviderError", (error) => Effect.log(error.message));
```

**Signature**

```ts
type CacheOperationError =
  | CacheCapabilityError
  | CacheDependencyError
  | CacheIncrementUnsupportedError
  | CacheOperationCancelledError
  | CacheOperationTimeoutError
  | CacheProviderError
  | CacheProviderFailureError
  | CacheSchemaValidationError
  | CacheTtlPolicyError
  | CacheValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L92)

### CacheOperationObservation

**Signature**

```ts
declare const CacheOperationObservation: CacheOperationObservation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L163)

### CacheOperationOptions

**Signature**

```ts
declare const CacheOperationOptions: CacheOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L24)

### CacheOperationOutcome

**Signature**

```ts
declare const CacheOperationOutcome: CacheOperationOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L25)

### CacheProvider

**Signature**

```ts
declare const CacheProvider: CacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/client.types.ts#L26)

## `define-cache-compat.ts`

### runDescriptor

Runs a descriptor Effect and restores established synchronous errors.

**Throws**

The original shared-contract error or TypeError for invalid input.

**Example**

```ts
runDescriptor(Effect.succeed(1));
```

**Signature**

```ts
declare const runDescriptor: <A>(effect: Effect.Effect<A, CacheDescriptorError>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache-compat.ts#L10)

## `define-cache-error.ts`

### CacheDescriptorError (class)

Invalid descriptor input, with its original cause when a dependency threw.

**Example**

```ts
new CacheDescriptorError({ reason: "Invalid cache descriptor" });
```

**Signature**

```ts
declare class CacheDescriptorError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache-error.ts#L6)

## `define-cache.ts`

### defineCache

Defines a typed cache contract with existing synchronous behavior.

**Throws**

TypeError for invalid options and IDs.

**Example**

```ts
import { defineCache } from "@relkit/cache";
import { z } from "@relkit/schema";
const prices = defineCache({ id: "prices", key: z.string(), value: z.number() });
```

**Signature**

```ts
declare const defineCache: <
  const Id extends string,
  const KeySchema extends StandardSchemaV1,
  const ValueSchema extends StandardSchemaV1,
>(
  options: DefineCacheOptions<Id, KeySchema, ValueSchema>,
) => CacheDescriptor<Id, InferInput<KeySchema>, InferOutput<ValueSchema>, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L94)

Since v0.1.0

### CacheDescriptor

**Signature**

```ts
declare const CacheDescriptor: CacheDescriptor<Id, Key, Value, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L13)

### CacheDescriptorAny

**Signature**

```ts
declare const CacheDescriptorAny: CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L14)

### CacheDescriptorError

**Signature**

```ts
declare const CacheDescriptorError: typeof CacheDescriptorError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L17)

### DefineCacheOptions

**Signature**

```ts
declare const DefineCacheOptions: DefineCacheOptions<Id, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L15)

### assertCacheDescriptor

Asserts a cache descriptor synchronously.

**Throws**

TypeError when the candidate is invalid.

**Example**

```ts
assertCacheDescriptor(value);
```

**Signature**

```ts
declare const assertCacheDescriptor: (value: unknown) => asserts value is CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L142)

### assertCacheDescriptorEffect

Asserts a cache descriptor in Effect.

**Example**

```ts
Effect.runSync(assertCacheDescriptorEffect(value));
```

**Signature**

```ts
declare const assertCacheDescriptorEffect: (
  value: unknown,
) => Effect.Effect<undefined, CacheDescriptorError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L127)

### defineCacheEffect

Defines a typed, frozen cache contract in Effect.

**Example**

```ts
Effect.runSync(defineCacheEffect({ id: "prices", key: z.string(), value: z.number() }));
```

**Signature**

```ts
declare const defineCacheEffect: <
  const Id extends string,
  const KeySchema extends StandardSchemaV1,
  const ValueSchema extends StandardSchemaV1,
>(
  options: DefineCacheOptions<Id, KeySchema, ValueSchema>,
) => Effect.Effect<
  CacheDescriptor<Id, InferInput<KeySchema>, InferOutput<ValueSchema>, KeySchema, ValueSchema>,
  CacheDescriptorError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L23)

### isCacheDescriptor

Checks a possible cache descriptor synchronously.

**Example**

```ts
if (isCacheDescriptor(value)) console.log(value.id);
```

**Signature**

```ts
declare const isCacheDescriptor: (value: unknown) => value is CacheDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L119)

### isCacheDescriptorEffect

Checks a possible descriptor without throwing.

**Example**

```ts
Effect.runSync(isCacheDescriptorEffect(value));
```

**Signature**

```ts
declare const isCacheDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.ts#L108)

## `define-cache.types.ts`

### CacheDescriptor (interface)

Frozen cache descriptor with phantom key and value types.

**Example**

```ts
const descriptor = defineCache({ id: "prices", key: z.string(), value: z.number() });
```

**Signature**

```ts
export interface CacheDescriptor<
  Id extends string,
  Key,
  Value,
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorBase<"cache", Id> {
  readonly profile?: string;
  readonly key: KeySchema;
  readonly value: ValueSchema;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly __key?: Key;
  readonly __value?: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L6)

### CacheDescriptorAny (type alias)

Any cache descriptor when schema type parameters are not known.

**Example**

```ts
const value: CacheDescriptorAny = defineCache(options);
```

**Signature**

```ts
type CacheDescriptorAny = CacheDescriptor<string, unknown, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L24)

### DefineCacheOptions (interface)

Inputs used to define one typed cache contract.

**Example**

```ts
const options: DefineCacheOptions<"prices", typeof key, typeof value> = {
  id: "prices",
  key,
  value,
};
```

**Signature**

```ts
export interface DefineCacheOptions<
  Id extends string,
  KeySchema extends StandardSchemaV1,
  ValueSchema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly profile?: string;
  readonly key: KeySchema;
  readonly value: ValueSchema;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/define-cache.types.ts#L28)

## `index.ts`

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/index.ts#L2)

### "./define-cache.js" (namespace export)

Re-exports all named exports from the "./define-cache.js" module.

**Signature**

```ts
export * from "./define-cache.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cache/src/index.ts#L1)

---

# CLI reference
Source: https://relkit.dev/docs/api/cli

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For guided setup and everyday workflows, start with the [CLI module](/docs/modules/cli) or follow [Create and build an API](/guides/cli/create-and-build-an-api). This page lists exact command arguments and options.

The command model below is shared with the Effect CLI runtime, so nested help and this page cannot drift.

## `relkit <command>`

Convention-first TypeScript application framework

| Option | Value   | Description                  |
| ------ | ------- | ---------------------------- |
| --json | boolean | Emit machine-readable output |

### Examples

`relkit` — Convention-first TypeScript application framework

### `relkit create [name]`

Create a new RELKIT application

| Argument | Value    | Description                      |
| -------- | -------- | -------------------------------- |
| name     | optional | npm package and application name |

| Option                  | Value                                            | Description                                           |
| ----------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| --template              | minimal, api, agent, fullstack                   | Candidate template; certified tuples only             |
| --cloud                 | aws, none                                        | Candidate cloud selection; certified tuples only      |
| --deploy                | pulumi, none                                     | Candidate deployment selection; certified tuples only |
| --jobs                  | inngest-docker, effect-mq-docker, trigger-docker | Candidate jobs service; certified native tuples only  |
| --directory             | string                                           | Destination directory                                 |
| --install               | boolean                                          | Install generated project setup                       |
| --no-install            | boolean                                          | No install generated project setup                    |
| --git                   | boolean                                          | Git generated project setup                           |
| --no-git                | boolean                                          | No git generated project setup                        |
| --examples              | boolean                                          | Examples generated project setup                      |
| --no-examples           | boolean                                          | No examples generated project setup                   |
| --force-empty-directory | boolean                                          | Allow an existing empty destination                   |

#### Examples

`relkit create` — Create a new RELKIT application

### `relkit add <kind>`

Add a compile-ready artifact

#### Examples

`relkit add` — Add a compile-ready artifact

#### `relkit add service [name]`

Create a domain service

| Argument | Value    | Description  |
| -------- | -------- | ------------ |
| name     | optional | Service name |

| Option           | Value                                                                                                   | Description                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                                                                                                  | Application directory (defaults to cwd)                                                          |
| --service        | string                                                                                                  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                                                                                                  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                                                                                                 | Do not install newly required packages                                                           |
| --full           | boolean                                                                                                 | Create the complete deterministic domain bundle; exclusive with --include                        |
| --include        | function, task, error, event, event-function, job, cache, bucket, tool, prompt, agent, constants, route | Artifact kind to include; repeatable                                                             |

##### Examples

`relkit add service` — Create a domain service

#### `relkit add function [name]`

Create a callable function

| Argument | Value    | Description   |
| -------- | -------- | ------------- |
| name     | optional | Function name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --internal       | boolean | Keep the artifact out of the public service API                                                  |

##### Examples

`relkit add function` — Create a callable function

#### `relkit add task [name]`

Create a task artifact

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Task name   |

| Option           | Value              | Description                                                                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| --project-root   | string             | Application directory (defaults to cwd)                                                          |
| --service        | string             | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string             | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean            | Do not install newly required packages                                                           |
| --version        | string             | Task semantic version (default: 1)                                                               |
| --execution      | durable, retryable | Task execution model (default: durable)                                                          |

##### Examples

`relkit add task` — Create a task artifact

#### `relkit add error [name]`

Create an internal typed error

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Error name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add error` — Create an internal typed error

#### `relkit add event [name]`

Create an event contract

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Event name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --internal       | boolean | Keep the artifact out of the public service API                                                  |
| --profile        | string  | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add event` — Create an event contract

#### `relkit add event-function [name]`

Create an event-only function

| Argument | Value    | Description         |
| -------- | -------- | ------------------- |
| name     | optional | Event function name |

| Option           | Value              | Description                                                                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------ |
| --project-root   | string             | Application directory (defaults to cwd)                                                          |
| --service        | string             | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string             | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean            | Do not install newly required packages                                                           |
| --event          | string             | Event ID, binding, or filename                                                                   |
| --delivery       | transient, durable | Delivery mode (default: durable)                                                                 |
| --profile        | string             | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add event-function` — Create an event-only function

#### `relkit add job [name]`

Create an unscheduled single-attempt job

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Job name    |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --target         | string  | Task ID; legacy callable function targets remain readable                                        |
| --profile        | string  | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |

##### Examples

`relkit add job` — Create an unscheduled single-attempt job

#### `relkit add cache [name]`

Create a cache descriptor and compatible profile

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Cache name  |

| Option           | Value                  | Description                                                                                      |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                 | Application directory (defaults to cwd)                                                          |
| --service        | string                 | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                 | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                | Do not install newly required packages                                                           |
| --profile        | string                 | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |
| --provider       | redis, cloudflare-kv   | Cache provider                                                                                   |
| --source         | docker, connected, aws | Provider source                                                                                  |

##### Examples

`relkit add cache` — Create a cache descriptor and compatible profile

#### `relkit add bucket [name]`

Create a bucket descriptor and compatible profile

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Bucket name |

| Option           | Value                  | Description                                                                                      |
| ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                 | Application directory (defaults to cwd)                                                          |
| --service        | string                 | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                 | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                | Do not install newly required packages                                                           |
| --profile        | string                 | Compatible profile name; otherwise reuse a default/unique profile or scaffold a local profile    |
| --provider       | s3, cloudflare-r2      | Bucket provider                                                                                  |
| --source         | docker, connected, aws | Provider source                                                                                  |

##### Examples

`relkit add bucket` — Create a bucket descriptor and compatible profile

#### `relkit add tool [name]`

Expose a callable function as an agent tool

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Tool name   |

| Option            | Value                       | Description                                                                                      |
| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root    | string                      | Application directory (defaults to cwd)                                                          |
| --service         | string                      | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service  | string                      | Create and use a new generic service for a domain artifact or service route                      |
| --no-install      | boolean                     | Do not install newly required packages                                                           |
| --target          | string                      | Existing callable function; exclusive with --create-function                                     |
| --create-function | string                      | Create a callable function; exclusive with --target                                              |
| --side-effect     | none, read, write, external | Tool side-effect class (default: read)                                                           |
| --approval        | never, on-write, always     | Tool approval policy (default: never)                                                            |

##### Examples

`relkit add tool` — Expose a callable function as an agent tool

#### `relkit add prompt [name]`

Create a reusable prompt

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Prompt name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --text           | string  | Prompt text; repeatable                                                                          |

##### Examples

`relkit add prompt` — Create a reusable prompt

#### `relkit add agent [name]`

Create an agent with a model, tools, and instructions

| Argument | Value    | Description |
| -------- | -------- | ----------- |
| name     | optional | Agent name  |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --model          | string  | Existing native model profile; omitted uses an offline model                                     |
| --tool           | string  | Tool ID, binding, or filename; repeatable                                                        |
| --prompt         | string  | Service prompt ID, binding, or filename; exclusive with --instructions                           |
| --instructions   | string  | Inline instructions; exactly one of --prompt or --instructions is required                       |

##### Examples

`relkit add agent` — Create an agent with a model, tools, and instructions

#### `relkit add constants [name]`

Create a constants descriptor

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| name     | optional | Constants name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add constants` — Create a constants descriptor

#### `relkit add route [path]`

Create a route or service route

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| path     | optional | URL route path |

| Option           | Value                | Description                                                                                      |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string               | Application directory (defaults to cwd)                                                          |
| --service        | string               | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string               | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean              | Do not install newly required packages                                                           |
| --mode           | route, service-route | Required headlessly: raw GET route or public service-member mappings                             |
| --map            | key=value            | METHOD=member mapping; repeatable                                                                |

##### Examples

`relkit add route` — Create a route or service route

#### `relkit add middleware [name]`

Create pass-through route middleware

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| name     | optional | Middleware name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |
| --path           | string  | Validated middleware route scope                                                                 |

##### Examples

`relkit add middleware` — Create pass-through route middleware

#### `relkit add transform [name]`

Create a string request transform

| Argument | Value    | Description    |
| -------- | -------- | -------------- |
| name     | optional | Transform name |

| Option           | Value   | Description                                                                                      |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string  | Application directory (defaults to cwd)                                                          |
| --service        | string  | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string  | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean | Do not install newly required packages                                                           |

##### Examples

`relkit add transform` — Create a string request transform

#### `relkit add database`

Create the singleton Drizzle database service

| Option           | Value                     | Description                                                                                      |
| ---------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root   | string                    | Application directory (defaults to cwd)                                                          |
| --service        | string                    | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service | string                    | Create and use a new generic service for a domain artifact or service route                      |
| --no-install     | boolean                   | Do not install newly required packages                                                           |
| --orm            | drizzle                   | Database ORM                                                                                     |
| --dialect        | sqlite, postgresql, mysql | Database dialect (default: sqlite)                                                               |

##### Examples

`relkit add database` — Create the singleton Drizzle database service

#### `relkit add auth`

Create Better Auth and its catch-all route

| Option             | Value                     | Description                                                                                      |
| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------ |
| --project-root     | string                    | Application directory (defaults to cwd)                                                          |
| --service          | string                    | Existing generic service for domain artifacts or service routes; exclusive with --create-service |
| --create-service   | string                    | Create and use a new generic service for a domain artifact or service route                      |
| --no-install       | boolean                   | Do not install newly required packages                                                           |
| --adapter          | better-auth               | Authentication adapter                                                                           |
| --database-dialect | sqlite, postgresql, mysql | Database dialect when one must be created (default: sqlite)                                      |
| --base-path        | string                    | Auth base path (default: /api/auth)                                                              |

##### Examples

`relkit add auth` — Create Better Auth and its catch-all route

#### `relkit add inspector`

Enable the inspector bridge and its local UI

| Option         | Value   | Description                             |
| -------------- | ------- | --------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd) |
| --no-install   | boolean | Do not install @relkit/inspector        |

##### Examples

`relkit add inspector` — Enable the inspector bridge and its local UI

### `relkit migrate <command>`

Preview and apply source layout migrations

#### Examples

`relkit migrate` — Preview and apply source layout migrations

#### `relkit migrate layout`

Move flat services into src/services with guarded rollback

| Option         | Value   | Description                                                   |
| -------------- | ------- | ------------------------------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd)                       |
| --write        | boolean | Validate and apply; stop development first                    |
| --rollback     | string  | Restore a local migration receipt; conflicts refuse overwrite |

##### Examples

`relkit migrate layout` — Move flat services into src/services with guarded rollback

### `relkit db <command>`

Manage application database migrations

#### Examples

`relkit db` — Manage application database migrations

#### `relkit db migrate`

Apply pending migrations using the application's installed tools

| Option   | Value  | Description                                                                                        |
| -------- | ------ | -------------------------------------------------------------------------------------------------- |
| --config | string | Application Drizzle config; defaults to drizzle.config.ts. Relative paths use the application root |

##### Examples

`relkit db migrate` — Apply pending migrations using the application's installed tools

### `relkit dev`

Run the app and its selected development features

| Option           | Value                                             | Description                                                                  |
| ---------------- | ------------------------------------------------- | ---------------------------------------------------------------------------- |
| --project-root   | string                                            | Application directory (defaults to cwd)                                      |
| --prepare        | boolean                                           | Prepare a validated dev snapshot and exit without a server                   |
| --port           | integer                                           | Application port                                                             |
| --inspector-port | integer                                           | Retired; configure inspector.connection.port, or run relkit inspector --port |
| --local          | on, off                                           | Start required local services                                                |
| --log-level      | all, trace, debug, info, warn, error, fatal, none | Minimum terminal severity (default: info)                                    |
| --verbose        | boolean                                           | Show debug events and full retained diagnostics                              |
| --no-color       | boolean                                           | Disable terminal colors                                                      |

#### Examples

`relkit dev` — Run the app and its selected development features

### `relkit inspector`

Run the project-local development inspector UI

| Option         | Value   | Description                                 |
| -------------- | ------- | ------------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd)     |
| --port         | integer | Inspector UI port (default: 3210)           |
| --hostname     | string  | Inspector UI bind host (default: 127.0.0.1) |

#### Examples

`relkit inspector` — Run the project-local development inspector UI

### `relkit check`

Compile descriptors, infer eligible IDs, and validate the application

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

#### Examples

`relkit check` — Compile descriptors, infer eligible IDs, and validate the application

### `relkit build`

Build the checked graph, manifest, OpenAPI, and client

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

#### Examples

`relkit build` — Build the checked graph, manifest, OpenAPI, and client

### `relkit start`

Start a built application

| Option         | Value   | Description                             |
| -------------- | ------- | --------------------------------------- |
| --project-root | string  | Application directory (defaults to cwd) |
| --port         | integer | Application port                        |

#### Examples

`relkit start` — Start a built application

### `relkit graph <command>`

Inspect deterministic application graphs

#### Examples

`relkit graph` — Inspect deterministic application graphs

#### `relkit graph print [graph]`

Print a canonical graph with services and resolved source IDs

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| graph    | optional | Graph JSON path |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

##### Examples

`relkit graph print` — Print a canonical graph with services and resolved source IDs

#### `relkit graph check [graph]`

Validate a graph and optional hash

| Argument | Value    | Description     |
| -------- | -------- | --------------- |
| graph    | optional | Graph JSON path |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |
| --hash         | string | Expected sha256 graph hash              |

##### Examples

`relkit graph check` — Validate a graph and optional hash

#### `relkit graph diff <before> <after>`

Compare graph compatibility, including inferred identity moves

| Argument | Value    | Description         |
| -------- | -------- | ------------------- |
| before   | required | Previous graph path |
| after    | required | Next graph path     |

| Option         | Value  | Description                             |
| -------------- | ------ | --------------------------------------- |
| --project-root | string | Application directory (defaults to cwd) |

##### Examples

`relkit graph diff` — Compare graph compatibility, including inferred identity moves

### `relkit env <command>`

Inspect value-free environment contracts

#### Examples

`relkit env` — Inspect value-free environment contracts

#### `relkit env check`

Validate environment values

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env check` — Validate environment values

#### `relkit env list`

List environment value status

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env list` — List environment value status

#### `relkit env explain <name>`

Explain one environment variable

| Argument | Value    | Description               |
| -------- | -------- | ------------------------- |
| name     | required | Environment variable name |

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |

##### Examples

`relkit env explain` — Explain one environment variable

#### `relkit env example`

Render or write a safe .env example

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --path / --file       | string  | Output path                             |
| --write               | boolean | Write the rendered example              |

##### Examples

`relkit env example` — Render or write a safe .env example

### `relkit local <command>`

Manage project-scoped local services

#### Examples

`relkit local` — Manage project-scoped local services

#### `relkit local up`

Start all declared local services

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --service             | string  | Limit to one service binding            |
| --detach              | boolean | Keep services running after exit        |

##### Examples

`relkit local up` — Start all declared local services

#### `relkit local status`

Show local service and lease status

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Limit to one service binding            |

##### Examples

`relkit local status` — Show local service and lease status

#### `relkit local stop`

Stop project local containers and preserve volumes

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Limit to one service binding            |

##### Examples

`relkit local stop` — Stop project local containers and preserve volumes

#### `relkit local reset`

Remove project local containers, volumes, and state

| Option                | Value   | Description                                |
| --------------------- | ------- | ------------------------------------------ |
| --project-root        | string  | Application directory (defaults to cwd)    |
| --environment / --env | string  | Provider environment configuration         |
| --service             | string  | Limit to one service binding               |
| --yes                 | boolean | Confirm reset without prompting            |
| --dry-run             | boolean | Show owned resources without removing them |

##### Examples

`relkit local reset` — Remove project local containers, volumes, and state

### `relkit jobs <command>`

Inspect and operate task-backed jobs

#### Examples

`relkit jobs` — Inspect and operate task-backed jobs

#### `relkit jobs list`

List compiled job definitions

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |

##### Examples

`relkit jobs list` — List compiled job definitions

#### `relkit jobs runs <command>`

Inspect accepted job runs

##### Examples

`relkit jobs runs` — Inspect accepted job runs

##### `relkit jobs runs list`

List runs with native filters

| Option                | Value                                                                          | Description                             |
| --------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| --project-root        | string                                                                         | Application directory (defaults to cwd) |
| --environment / --env | string                                                                         | Provider environment configuration      |
| --service             | string                                                                         | Jobs service profile                    |
| --job                 | string                                                                         | Job name or ID                          |
| --task-id             | string                                                                         | Task ID                                 |
| --status              | accepted, running, sleeping, retrying, completed, failed, cancelled, timed-out | Run status                              |
| --from                | string                                                                         | Lower time bound                        |
| --to                  | string                                                                         | Upper time bound                        |
| --tag                 | string                                                                         | Run tag; repeatable                     |
| --tag-match           | all, any                                                                       | Tag matching mode                       |
| --limit               | integer                                                                        | Rows (1-100)                            |
| --cursor              | string                                                                         | Opaque page cursor                      |

###### Examples

`relkit jobs runs list` — List runs with native filters

##### `relkit jobs runs get`

Read one run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |

###### Examples

`relkit jobs runs get` — Read one run

##### `relkit jobs runs watch`

Watch one run as newline-delimited frames

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --after               | string | Resume cursor                           |

###### Examples

`relkit jobs runs watch` — Watch one run as newline-delimited frames

#### `relkit jobs trigger`

Submit validated task input

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --job                 | string | Job name or ID                          |
| --input-file          | string | JSON input file                         |
| --idempotency-key     | string | External idempotency key                |
| --operation-id        | string | Stable operation ID                     |
| --delay               | string | Readable delay                          |
| --at                  | string | RFC3339 scheduled time                  |

##### Examples

`relkit jobs trigger` — Submit validated task input

#### `relkit jobs cancel`

Cancel one run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --operation-id        | string | Required control operation ID           |
| --reason              | string | Cancellation reason                     |

##### Examples

`relkit jobs cancel` — Cancel one run

#### `relkit jobs retry`

Retry one terminal run

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --run-id              | string | Opaque run locator                      |
| --operation-id        | string | Required control operation ID           |

##### Examples

`relkit jobs retry` — Retry one terminal run

#### `relkit jobs capabilities`

Show provider capability reports

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |

##### Examples

`relkit jobs capabilities` — Show provider capability reports

#### `relkit jobs schedules <command>`

Administer native schedules

##### Examples

`relkit jobs schedules` — Administer native schedules

##### `relkit jobs schedules list`

List schedules

| Option                | Value   | Description                             |
| --------------------- | ------- | --------------------------------------- |
| --project-root        | string  | Application directory (defaults to cwd) |
| --environment / --env | string  | Provider environment configuration      |
| --service             | string  | Jobs service profile                    |
| --job                 | string  | Job name or ID                          |
| --limit               | integer | Rows (1-100)                            |
| --cursor              | string  | Opaque page cursor                      |

###### Examples

`relkit jobs schedules list` — List schedules

##### `relkit jobs schedules get`

Read one schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |

###### Examples

`relkit jobs schedules get` — Read one schedule

##### `relkit jobs schedules upsert`

Create or update a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --definition-file     | string | JSON definition file                    |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules upsert` — Create or update a schedule

##### `relkit jobs schedules pause`

Pause a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules pause` — Pause a schedule

##### `relkit jobs schedules resume`

Resume a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules resume` — Resume a schedule

##### `relkit jobs schedules delete`

Delete a schedule

| Option                | Value  | Description                             |
| --------------------- | ------ | --------------------------------------- |
| --project-root        | string | Application directory (defaults to cwd) |
| --environment / --env | string | Provider environment configuration      |
| --service             | string | Jobs service profile                    |
| --schedule-id         | string | Schedule ID                             |
| --operation-id        | string | Stable operation ID                     |

###### Examples

`relkit jobs schedules delete` — Delete a schedule

### `relkit doctor`

Check local prerequisites and ports

| Option           | Value   | Description                                                             |
| ---------------- | ------- | ----------------------------------------------------------------------- |
| --project-root   | string  | Application directory (defaults to cwd)                                 |
| --port           | integer | Application port                                                        |
| --inspector-port | integer | Retired; configure inspector.connection.port for the application bridge |
| --no-ports       | boolean | Skip port availability checks                                           |
| --pulumi         | boolean | Require Pulumi                                                          |
| --no-pulumi      | boolean | Skip Pulumi requirements                                                |

#### Examples

`relkit doctor` — Check local prerequisites and ports

### `relkit deploy <command>`

Manage Pulumi deployments

#### Examples

`relkit deploy` — Manage Pulumi deployments

#### `relkit deploy init`

Init the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy init` — Init the Pulumi stack

#### `relkit deploy preview`

Preview the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy preview` — Preview the Pulumi stack

#### `relkit deploy up`

Up the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy up` — Up the Pulumi stack

#### `relkit deploy refresh`

Refresh the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy refresh` — Refresh the Pulumi stack

#### `relkit deploy outputs`

Outputs the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy outputs` — Outputs the Pulumi stack

#### `relkit deploy destroy`

Destroy the Pulumi stack

| Option                    | Value     | Description                               |
| ------------------------- | --------- | ----------------------------------------- |
| --project-root            | string    | Application directory (defaults to cwd)   |
| --stack                   | string    | Pulumi stack name (default: development)  |
| --backend                 | string    | cloud, local, or object-storage URL       |
| --config                  | key=value | Set a non-secret Pulumi value; repeatable |
| --config-secret           | key=value | Set a secret Pulumi value; repeatable     |
| --non-interactive / --yes | boolean   | Approve protected operations              |

##### Examples

`relkit deploy destroy` — Destroy the Pulumi stack

### `relkit client <command>`

Generate a client from a running application

#### Examples

`relkit client` — Generate a client from a running application

#### `relkit client pull <baseUrl> --out <directory>`

Pull a versioned client contract

| Argument | Value    | Description                    |
| -------- | -------- | ------------------------------ |
| baseUrl  | required | Running RELKIT application URL |

| Option | Value  | Description      |
| ------ | ------ | ---------------- |
| --out  | string | Output directory |

##### Examples

`relkit client pull` — Pull a versioned client contract

#### `relkit client check <baseUrl> --out <directory>`

Check a pulled client for contract drift

| Argument | Value    | Description                    |
| -------- | -------- | ------------------------------ |
| baseUrl  | required | Running RELKIT application URL |

| Option | Value  | Description      |
| ------ | ------ | ---------------- |
| --out  | string | Output directory |

##### Examples

`relkit client check` — Check a pulled client for contract drift

---

# CLI automation API
Source: https://relkit.dev/docs/api/cli-api

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [automation](/docs/modules/cli/automation).

## Public imports

- `@relkit/cli` — 37 exports
- `@relkit/cli/help` — 6 exports
- `@relkit/cli/editor` — 1 exports
- `@relkit/cli/scaffolding` — 156 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                            | Kind  | Import from                       | Example                                                                                                                                    |
| ---------------------------------------------------------------------------------------------- | ----- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [acquireDevSessionEffect](/docs/api/cli-api#acquiredevsessioneffect)                           | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ADD_FAILURE_CODES](/docs/api/create-relkit#add_failure_codes)                                 | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches-asset.cases.ts#L67)         |
| [ADD_KINDS](/docs/api/create-relkit#add_kinds)                                                 | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddCommandResult](/docs/api/cli-api#addcommandresult-interface)                               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [addFactoryObjectMember](/docs/api/cli-api#addfactoryobjectmember)                             | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/project-discovery.edits.cases.ts#L12)                         |
| [AddFailureCode](/docs/api/create-relkit#addfailurecode-type-alias)                            | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddKind](/docs/api/create-relkit#addkind-type-alias)                                          | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddRequest](/docs/api/create-relkit#addrequest-type-alias)                                    | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddRequestBase](/docs/api/create-relkit#addrequestbase-interface)                             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddResolution](/docs/api/cli-api#addresolution-class)                                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [addResolutionLive](/docs/api/cli-api#addresolutionlive)                                       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddResult](/docs/api/create-relkit#addresult-interface)                                       | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddScaffoldError](/docs/api/create-relkit#addscaffolderror-class)                             | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/native-transaction.fixture.ts#L99)             |
| [addSourceExport](/docs/api/cli-api#addsourceexport)                                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/project-discovery.edits.cases.ts#L86)                         |
| [addSourceImport](/docs/api/cli-api#addsourceimport-1)                                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/project-discovery.edits.cases.ts#L11)                         |
| [ApplyScaffoldContext](/docs/api/cli-api#applyscaffoldcontext-interface)                       | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-runner.fixture.ts#L92)             |
| [applyScaffoldPlan](/docs/api/cli-api#applyscaffoldplan)                                       | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches-rollback.cases.ts#L26)      |
| [applyScaffoldPlanEffect](/docs/api/cli-api#applyscaffoldplaneffect)                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L43)            |
| [assertCreateCapability](/docs/api/create-relkit#assertcreatecapability)                       | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L22)                 |
| [CatalogManifest](/docs/api/create-relkit#catalogmanifest-type-alias)                          | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ChoicePromptOptions](/docs/api/create-relkit#choicepromptoptions-interface)                   | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CLI_EXIT_CODES](/docs/api/cli-api#cli_exit_codes)                                             | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CLI_VERSION](/docs/api/cli-api#cli_version)                                                   | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliCommandContext](/docs/api/cli-api#clicommandcontext-interface)                             | Type  | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/commands/inspector.test.ts#L53)                            |
| [CliFailure](/docs/api/cli-api#clifailure-type-alias)                                          | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliHelpArgument](/docs/api/cli-api#clihelpargument-interface)                                 | Type  | `@relkit/cli`, `@relkit/cli/help` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliHelpCommand](/docs/api/cli-api#clihelpcommand-interface)                                   | Type  | `@relkit/cli`, `@relkit/cli/help` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliHelpModel](/docs/api/cli-api#clihelpmodel-interface)                                       | Type  | `@relkit/cli`, `@relkit/cli/help` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliHelpOption](/docs/api/cli-api#clihelpoption-interface)                                     | Type  | `@relkit/cli`, `@relkit/cli/help` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliIo](/docs/api/cli-api#cliio-interface)                                                     | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliLogger](/docs/api/cli-api#clilogger-type-alias)                                            | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliReporter](/docs/api/cli-api#clireporter-interface)                                         | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CliRuntime](/docs/api/cli-api#cliruntime-interface)                                           | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_CAPABILITY_TABLE](/docs/api/create-relkit#create_capability_table)                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L12)                 |
| [CREATE_CLOUDS](/docs/api/create-relkit#create_clouds)                                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_DEPLOYMENTS](/docs/api/create-relkit#create_deployments)                               | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_JOBS](/docs/api/create-relkit#create_jobs)                                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_OPTION_DEFAULTS](/docs/api/create-relkit#create_option_defaults)                       | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/fixtures/inspector/generated-app.ts#L18)                                |
| [CREATE_TEMPLATES](/docs/api/create-relkit#create_templates)                                   | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix.test.ts#L21)                                    |
| [CreateCapabilityEvidence](/docs/api/create-relkit#createcapabilityevidence-interface)         | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCapabilityIdentity](/docs/api/create-relkit#createcapabilityidentity-interface)         | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCapabilityTuple](/docs/api/create-relkit#createcapabilitytuple-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [createClackPromptDriver](/docs/api/create-relkit#createclackpromptdriver)                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCloud](/docs/api/create-relkit#createcloud-type-alias)                                  | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateDeployment](/docs/api/create-relkit#createdeployment-type-alias)                        | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [createGenerateNextSteps](/docs/api/create-relkit#creategeneratenextsteps)                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/generation-output.effect.test.ts#L12)            |
| [CreateJobs](/docs/api/create-relkit#createjobs-type-alias)                                    | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateOptions](/docs/api/create-relkit#createoptions-interface)                               | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix-fixture.ts#L25)                                 |
| [CreateOptionsContext](/docs/api/create-relkit#createoptionscontext-interface)                 | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateOptionsError](/docs/api/create-relkit#createoptionserror-class)                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateRelkitGeneratorApi](/docs/api/cli-api#createrelkitgeneratorapi-interface)               | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [createReporter](/docs/api/cli-api#createreporter)                                             | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateScaffoldPlan](/docs/api/create-relkit#createscaffoldplan-interface)                     | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateTemplate](/docs/api/create-relkit#createtemplate-type-alias)                            | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateValidationContext](/docs/api/create-relkit#createvalidationcontext-interface)           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateValidationError](/docs/api/create-relkit#createvalidationerror-class)                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [currentCreateCapabilityIdentity](/docs/api/create-relkit#currentcreatecapabilityidentity)     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L23)                 |
| [DatabaseDialect](/docs/api/create-relkit#databasedialect-type-alias)                          | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [default](/docs/api/cli-api#initialize)                                                        | Value | `@relkit/cli/editor`              | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DependencySection](/docs/api/create-relkit#dependencysection-type-alias)                      | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DevActivationFingerprint](/docs/api/cli-api#devactivationfingerprint-type-alias)              | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DevLocalServices](/docs/api/cli-api#devlocalservices-interface)                               | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DevLog](/docs/api/cli-api#devlog-type-alias)                                                  | Type  | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DevLogEvent](/docs/api/cli-api#devlogevent-interface)                                         | Type  | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/commands/dev-ready.test.ts#L9)                             |
| [DevOptions](/docs/api/cli-api#devoptions-interface)                                           | Type  | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/fixtures/cli/dev-fixture.ts#L83)                                        |
| [DevSession](/docs/api/cli-api#devsession-class)                                               | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/services/dev-supervisor.test.ts#L91)                       |
| [DiscoveredArtifact](/docs/api/cli-api#discoveredartifact-interface)                           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DiscoveredProfile](/docs/api/cli-api#discoveredprofile-interface)                             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DiscoveredService](/docs/api/cli-api#discoveredservice-interface)                             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DiscoveredServiceMember](/docs/api/cli-api#discoveredservicemember-interface)                 | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [discoverProject](/docs/api/cli-api#discoverproject)                                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/project-discovery.metadata.cases.ts#L14)                      |
| [discoverProjectEffect](/docs/api/cli-api#discoverprojecteffect)                               | Value | `@relkit/cli/scaffolding`         | [API example](/docs/api/cli-api#discoverprojecteffect)                                                                                     |
| [domainError](/docs/api/create-relkit#domainerror)                                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [domainTry](/docs/api/create-relkit#domaintry)                                                 | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/observation.effect.test.ts#L83)                  |
| [errorMessage](/docs/api/cli-api#errormessage)                                                 | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [errorMessage](/docs/api/create-relkit#errormessage)                                           | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [fail](/docs/api/cli-api#fail)                                                                 | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [failSignal](/docs/api/cli-api#failsignal)                                                     | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/invocation/signals.test.ts#L86)                            |
| [findCliHelp](/docs/api/cli-api#findclihelp)                                                   | Value | `@relkit/cli`, `@relkit/cli/help` | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts#L19)                                 |
| [formatAddResult](/docs/api/cli-api#formataddresult)                                           | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [formatCreatePlan](/docs/api/create-relkit#formatcreateplan)                                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [formatGenerateResult](/docs/api/create-relkit#formatgenerateresult)                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/generation-output.effect.test.ts#L14)            |
| [formatScaffoldPlan](/docs/api/cli-api#formatscaffoldplan)                                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GenerateCommandResult](/docs/api/create-relkit#generatecommandresult-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GenerateCommandRunner](/docs/api/create-relkit#generatecommandrunner-type-alias)              | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GenerateFailurePoint](/docs/api/create-relkit#generatefailurepoint-type-alias)                | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L14)                                  |
| [GenerateNextSteps](/docs/api/create-relkit#generatenextsteps-interface)                       | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generateProject](/docs/api/create-relkit#generateproject)                                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/dependency-patch-generation.test.ts#L20)         |
| [GenerateProjectContext](/docs/api/create-relkit#generateprojectcontext-interface)             | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L101)                                 |
| [generateProjectEffect](/docs/api/create-relkit#generateprojecteffect)                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L45)            |
| [GenerateProjectError](/docs/api/create-relkit#generateprojecterror-class)                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L29)                                  |
| [GenerateProjectResult](/docs/api/create-relkit#generateprojectresult-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorCleanupFailure](/docs/api/create-relkit#generatorcleanupfailure-interface)           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorCleanupFailures](/docs/api/create-relkit#generatorcleanupfailures)                   | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-lifecycle.effect.test.ts#L69)      |
| [GeneratorCommandResult](/docs/api/create-relkit#generatorcommandresult-interface)             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorCommandRunner](/docs/api/create-relkit#generatorcommandrunner-type-alias)            | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorDirectoryEntry](/docs/api/create-relkit#generatordirectoryentry-interface)           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorDomainError](/docs/api/create-relkit#generatordomainerror-class)                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorEntryKind](/docs/api/create-relkit#generatorentrykind-type-alias)                    | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorFileMetadata](/docs/api/create-relkit#generatorfilemetadata-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorFileSystem](/docs/api/create-relkit#generatorfilesystem-class)                       | Value | `@relkit/cli/scaffolding`         | [API example](/docs/api/create-relkit#generatorfilesystem-class)                                                                           |
| [generatorFileSystemLive](/docs/api/create-relkit#generatorfilesystemlive)                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L67)            |
| [GeneratorFileSystemService](/docs/api/create-relkit#generatorfilesystemservice-interface)     | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-services-directories.fixture.ts#L14) |
| [GeneratorIoError](/docs/api/create-relkit#generatorioerror-class)                             | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-services.fixture.ts#L51)             |
| [GeneratorPaths](/docs/api/create-relkit#generatorpaths-class)                                 | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/contributor/workspace.fixture.ts#L74)                      |
| [generatorPathsLive](/docs/api/create-relkit#generatorpathslive)                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L69)            |
| [GeneratorPathsService](/docs/api/create-relkit#generatorpathsservice-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorProcess](/docs/api/create-relkit#generatorprocess-class)                             | Value | `@relkit/cli/scaffolding`         | [API example](/docs/api/create-relkit#generatorprocess-class)                                                                              |
| [GeneratorProcessError](/docs/api/create-relkit#generatorprocesserror-class)                   | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-lifecycle.effect.test.ts#L99)      |
| [generatorProcessLayer](/docs/api/create-relkit#generatorprocesslayer)                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorProcessLive](/docs/api/create-relkit#generatorprocesslive)                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L68)            |
| [GeneratorProcessService](/docs/api/create-relkit#generatorprocessservice-interface)           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorPrompt](/docs/api/create-relkit#generatorprompt-class)                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L48)            |
| [GeneratorPromptError](/docs/api/create-relkit#generatorprompterror-class)                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorPromptLayer](/docs/api/create-relkit#generatorpromptlayer)                           | Value | `@relkit/cli/scaffolding`         | [API example](/docs/api/create-relkit#generatorpromptlayer)                                                                                |
| [GeneratorPromptService](/docs/api/create-relkit#generatorpromptservice-interface)             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [getCliHelpModel](/docs/api/cli-api#getclihelpmodel)                                           | Value | `@relkit/cli`, `@relkit/cli/help` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [hasErrno](/docs/api/create-relkit#haserrno)                                                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [helpPayload](/docs/api/cli-api#helppayload)                                                   | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [helpText](/docs/api/cli-api#helptext)                                                         | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [installSignals](/docs/api/cli-api#installsignals)                                             | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/invocation/signals.test.ts#L75)                            |
| [isGeneratorApi](/docs/api/cli-api#isgeneratorapi)                                             | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [isValidPackageName](/docs/api/create-relkit#isvalidpackagename)                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix-destinations.test.ts#L32)                       |
| [loadCreateRelkit](/docs/api/cli-api#loadcreaterelkit)                                         | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [loadCreateRelkitEffect](/docs/api/cli-api#loadcreaterelkiteffect)                             | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [main](/docs/api/cli-api#main)                                                                 | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [normalizeAddRequest](/docs/api/cli-api#normalizeaddrequest)                                   | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L35)            |
| [normalizeArtifactName](/docs/api/cli-api#normalizeartifactname)                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/add-options.test.ts#L40)                                      |
| [normalizeCreateOptions](/docs/api/create-relkit#normalizecreateoptions)                       | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts#L9)                                  |
| [NormalizedArtifactName](/docs/api/cli-api#normalizedartifactname-interface)                   | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [planAdd](/docs/api/cli-api#planadd)                                                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/add-acceptance-fixture.ts#L116)                               |
| [planAddEffect](/docs/api/cli-api#planaddeffect)                                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L35)            |
| [PlanBuilder](/docs/api/cli-api#planbuilder-class)                                             | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches.fixture.ts#L39)             |
| [planCreate](/docs/api/create-relkit#plancreate)                                               | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts#L16)                                 |
| [planCreateEffect](/docs/api/create-relkit#plancreateeffect)                                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ProjectDiscovery](/docs/api/cli-api#projectdiscovery-interface)                               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [projectDiscoveryLive](/docs/api/cli-api#projectdiscoverylive)                                 | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L32)            |
| [ProjectDiscoveryServiceTag](/docs/api/cli-api#projectdiscoveryservicetag-class)               | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ProjectGeneration](/docs/api/create-relkit#projectgeneration-class)                           | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [projectGenerationLive](/docs/api/create-relkit#projectgenerationlive)                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L66)            |
| [PromptDriver](/docs/api/create-relkit#promptdriver-interface)                                 | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/invocation/interaction.test.ts#L14)                        |
| [PromptOption](/docs/api/create-relkit#promptoption-interface)                                 | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [publicFailure](/docs/api/create-relkit#publicfailure)                                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/planning.effect.test.ts#L129)                  |
| [readFactoryObject](/docs/api/cli-api#readfactoryobject)                                       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [readFactoryStringProperty](/docs/api/cli-api#readfactorystringproperty)                       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [recordCleanupFailure](/docs/api/create-relkit#recordcleanupfailure)                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/observation.effect.test.ts#L94)                  |
| [renderDatabase](/docs/api/cli-api#renderdatabase)                                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [renderDatabaseEffect](/docs/api/cli-api#renderdatabaseeffect)                                 | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [RenderedDatabase](/docs/api/cli-api#rendereddatabase-interface)                               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolveAddContext](/docs/api/cli-api#resolveaddcontext-interface)                             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveAddRequest](/docs/api/cli-api#resolveaddrequest)                                       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveAddRequestDetails](/docs/api/cli-api#resolveaddrequestdetails)                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/add-resolver.add.cases.ts#L14)                                |
| [resolveAddRequestDetailsEffect](/docs/api/cli-api#resolveaddrequestdetailseffect)             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCatalogVersion](/docs/api/create-relkit#resolvecatalogversion)                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolveCreateContext](/docs/api/create-relkit#resolvecreatecontext-interface)                 | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateDestination](/docs/api/create-relkit#resolvecreatedestination)                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateDestinationEffect](/docs/api/create-relkit#resolvecreatedestinationeffect)       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateOptions](/docs/api/create-relkit#resolvecreateoptions)                           | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateOptionsDetails](/docs/api/create-relkit#resolvecreateoptionsdetails)             | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/add-resolver.creation.cases.ts#L32)                           |
| [resolveCreateOptionsDetailsEffect](/docs/api/create-relkit#resolvecreateoptionsdetailseffect) | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolvedAddRequest](/docs/api/cli-api#resolvedaddrequest-interface)                           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolvedCreateOptions](/docs/api/create-relkit#resolvedcreateoptions-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveProjectDependencies](/docs/api/cli-api#resolveprojectdependencies)                     | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/project-catalog.test.ts#L28)                   |
| [resolveProjectDependenciesEffect](/docs/api/cli-api#resolveprojectdependencieseffect)         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveTemplateRoot](/docs/api/create-relkit#resolvetemplateroot)                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveTemplateRootEffect](/docs/api/create-relkit#resolvetemplaterooteffect)                 | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [RouteMethod](/docs/api/create-relkit#routemethod-type-alias)                                  | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [runCli](/docs/api/cli-api#runcli)                                                             | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/database/cancellation.test.ts#L35)                         |
| [runDev](/docs/api/cli-api#rundev)                                                             | Value | `@relkit/cli`                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [SCAFFOLD_DEPENDENCIES](/docs/api/create-relkit#scaffold_dependencies)                         | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches-selection.cases.ts#L67)     |
| [scaffoldDependency](/docs/api/create-relkit#scaffolddependency-1)                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldDependency](/docs/api/create-relkit#scaffolddependency-interface)                     | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldDependencyName](/docs/api/create-relkit#scaffolddependencyname-type-alias)            | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches.fixture.ts#L38)             |
| [scaffoldErrors](/docs/api/create-relkit#scaffolderrors)                                       | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldFileOperation](/docs/api/create-relkit#scaffoldfileoperation-interface)               | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldPlan](/docs/api/create-relkit#scaffoldplan-interface)                                 | Type  | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L27)            |
| [ScaffoldPlanning](/docs/api/cli-api#scaffoldplanning-class)                                   | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [scaffoldPlanningLive](/docs/api/cli-api#scaffoldplanninglive)                                 | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L39)            |
| [ScaffoldTransaction](/docs/api/cli-api#scaffoldtransaction-class)                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [scaffoldTransactionLive](/docs/api/cli-api#scaffoldtransactionlive)                           | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-lifecycle.effect.test.ts#L109)     |
| [ScaffoldVerification](/docs/api/create-relkit#scaffoldverification-type-alias)                | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldWarning](/docs/api/create-relkit#scaffoldwarning-interface)                           | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ServiceInclude](/docs/api/create-relkit#serviceinclude-type-alias)                            | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [startDev](/docs/api/cli-api#startdev)                                                         | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/services/source-watch-synchronous.test.ts#L18)             |
| [staticPropertyName](/docs/api/cli-api#staticpropertyname)                                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [supported](/docs/api/create-relkit#supported)                                                 | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [supportedCreateTemplates](/docs/api/create-relkit#supportedcreatetemplates)                   | Value | `@relkit/cli/scaffolding`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L24)                 |
| [TextPromptOptions](/docs/api/create-relkit#textpromptoptions-interface)                       | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [toFailure](/docs/api/cli-api#tofailure)                                                       | Value | `@relkit/cli`                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/invocation/signals.test.ts#L69)                            |
| [transferCleanupFailures](/docs/api/create-relkit#transfercleanupfailures)                     | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validateCreateOptions](/docs/api/create-relkit#validatecreateoptions)                         | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validateCreateOptionsEffect](/docs/api/create-relkit#validatecreateoptionseffect)             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ValidatedCreateOptions](/docs/api/create-relkit#validatedcreateoptions-interface)             | Type  | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validatePackageName](/docs/api/create-relkit#validatepackagename)                             | Value | `@relkit/cli/scaffolding`         | [Module example](/docs/modules/cli/automation)                                                                                             |

## `cli-help-model.ts`

Static CLI help metadata; rendering never evaluates projects or starts support services.

### "./cli-help-model.types.js" (namespace export)

Re-exports all named exports from the "./cli-help-model.types.js" module.

**Signature**

```ts
export * from "./cli-help-model.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.ts#L14)

### findCliHelp

Resolves a command path in the static tree without executing the command.

**Signature**

```ts
declare const findCliHelp: (path: readonly string[]) => CliHelpCommand | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.ts#L134)

### getCliHelpModel

Returns a frozen static help tree without acquiring command services.

**Signature**

```ts
declare const getCliHelpModel: (version: string) => CliHelpModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.ts#L126)

## `cli-help-model.types.ts`

One static option contract consumed by terminal and documentation renderers.

### CliHelpArgument (interface)

Positional argument metadata; this describes syntax without parsing input.

**Signature**

```ts
export interface CliHelpArgument {
  readonly name: string;
  readonly required: boolean;
  readonly description: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.types.ts#L12)

### CliHelpCommand (interface)

Pure command tree shared by generated documentation and CLI help.

**Signature**

```ts
export interface CliHelpCommand {
  readonly name: string;
  readonly description: string;
  readonly usage: string;
  readonly examples: readonly { readonly command: string; readonly description: string }[];
  readonly options: readonly CliHelpOption[];
  readonly arguments: readonly CliHelpArgument[];
  readonly commands: readonly CliHelpCommand[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.types.ts#L19)

### CliHelpModel (interface)

Versioned root command; returned instances are deeply frozen.

**Signature**

```ts
export interface CliHelpModel extends CliHelpCommand {
  readonly version: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.types.ts#L30)

### CliHelpOption (interface)

One static option contract consumed by terminal and documentation renderers.

**Signature**

```ts
export interface CliHelpOption {
  readonly name: string;
  readonly aliases?: readonly string[];
  readonly type: "boolean" | "string" | "integer" | "choice" | "key=value";
  readonly description: string;
  readonly values?: readonly string[];
  readonly repeatable?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/cli-help-model.types.ts#L2)

## `dev-session.ts`

Owns development session state and its public synchronous/Promise facade over scoped native operations.

### DevSession (class)

Public Promise/synchronous facade over one native session owner.

**Signature**

```ts
declare class DevSession {
  constructor(options: DevOptions);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L14)

### attach (method)

Captures the acquired engine for the public compatibility facade. @param engine - Scoped operations.

**Signature**

```ts
declare const attach: (engine: DevSessionEngine) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L75)

### start (method)

Acquires the manual public owner once; concurrent callers share startup.

**Signature**

```ts
declare const start: () => Promise<this>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L83)

### activate (method)

Joins one requested source activation through the captured engine.

**Signature**

```ts
declare const activate: (version?: number, files?: readonly string[]) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L91)

### notifySourceChange (method)

Forwards an explicit source version to the serialized activation owner.

**Signature**

```ts
declare const notifySourceChange: (version: number, files?: readonly string[]) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L100)

### waitForShutdown (method)

Joins the captured session's shared shutdown completion.

**Signature**

```ts
declare const waitForShutdown: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L106)

### stop (method)

Closes the manual public owner and joins its shared release.

**Signature**

```ts
declare const stop: <Reason>(reason?: Reason | Error) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L115)

### drain (method)

Joins a retired generation's drain through the captured engine.

**Signature**

```ts
declare const drain: (
  previous: StartedCandidate,
  active: SupervisorCandidateToken,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L163)

### resolveShutdownPromise (method)

Completes the retained synchronous compatibility shutdown latch.

**Signature**

```ts
declare const resolveShutdownPromise: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L167)

### clearSignals (method)

Closes the captured signal registration and its synchronous facade.

**Signature**

```ts
declare const clearSignals: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L181)

### markStopping (method)

Closes synchronous startup and activation admission.

**Signature**

```ts
declare const markStopping: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L186)

### runSynchronous (method)

Executes the retained synchronous watcher edge.

**Signature**

```ts
declare const runSynchronous: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L196)

### projectRoot (property)

**Signature**

```ts
readonly projectRoot: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L15)

### options (property)

**Signature**

```ts
readonly options: DevOptions
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L16)

### inspectionIdentity (property)

**Signature**

```ts
readonly inspectionIdentity: { readonly sessionId: string; readonly token: string; }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L17)

### abortController (property)

**Signature**

```ts
readonly abortController: AbortController
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L18)

### state (property)

**Signature**

```ts
readonly state: Ref.Ref<DevSessionState>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L19)

### log (property)

**Signature**

```ts
readonly log: DevLog
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L32)

### observability (property)

**Signature**

```ts
readonly observability: SupervisorObservability
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L33)

### stateMachine (property)

**Signature**

```ts
readonly stateMachine: SupervisorStateMachine
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L34)

### proxy (property)

**Signature**

```ts
readonly proxy: SupervisorProxy
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev-session.ts#L35)

## `dev.ts`

### DevActivationFingerprint

**Signature**

```ts
declare const DevActivationFingerprint: DevActivationFingerprint;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L8)

### DevLocalServices

**Signature**

```ts
declare const DevLocalServices: DevLocalServices;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L11)

### DevLog

**Signature**

```ts
declare const DevLog: DevLog;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L9)

### DevLogEvent

**Signature**

```ts
declare const DevLogEvent: DevLogEvent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L10)

### DevOptions

**Signature**

```ts
declare const DevOptions: DevOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L12)

### DevSession

**Signature**

```ts
declare const DevSession: typeof DevSession;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L14)

### acquireDevSessionEffect

Acquires a session in the caller's native lifetime.

**Signature**

```ts
declare const acquireDevSessionEffect: (
  _options: DevOptions,
) => Effect.Effect<
  DevSession,
  CliAdapterError,
  | Scope
  | CliDevSupervisor
  | CliFileSystem
  | CliCleanup
  | CliPortProbe
  | CliSourceWatch
  | CliInspectorSupport
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L21)

### runDev

Runs development until the session's scoped shutdown completes.

**Signature**

```ts
declare const runDev: (options: DevOptions) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L42)

### startDev

Starts and returns the manually owned public development session.

**Signature**

```ts
declare const startDev: (options: DevOptions) => Promise<DevSession>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.ts#L35)

## `dev.types.ts`

Explicit development policy keeps resourceful work in the session's Effect scope.

### DevActivationFingerprint (type alias)

Full activation identity or an explicit foreign identity provider.

**Signature**

```ts
type DevActivationFingerprint =
  | RuntimeActivationFingerprint
  | ((
      candidate: StartedCandidate,
    ) => RuntimeActivationFingerprint | PromiseLike<RuntimeActivationFingerprint>);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.types.ts#L31)

### DevLocalServices (interface)

Existing manually owned local service compatibility boundary.

**Signature**

```ts
export interface DevLocalServices {
  /**
   * Joins native local resource cleanup before session shutdown completes.
   * @returns Shared local owner release completion.
   */
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.types.ts#L37)

### DevLog (type alias)

Synchronous native logging callback; failures cannot change session lifecycle.

**Signature**

```ts
type DevLog = (event: DevLogEvent) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.types.ts#L25)

### DevLogEvent (interface)

One admitted development log, rendered by the existing terminal policy.

**Signature**

```ts
export interface DevLogEvent {
  readonly level: LogLevel;
  readonly event: string;
  readonly fields?: Readonly<Record<string, JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.types.ts#L15)

### DevOptions (interface)

Development host inputs; all process/session resources belong to one lifetime.

**Signature**

```ts
export interface DevOptions {
  readonly projectRoot?: string;
  readonly compile: CandidateCompile;
  readonly activationFingerprint?: DevActivationFingerprint;
  /**
   * Reuses the prepared identity only for a child installed from that validated receipt.
   * @param candidate - SDK child associated with one immutable preparation result.
   * @returns Its accepted identity, or absence for an independently checked fallback child.
   */
  readonly preparedActivationFingerprint?: (
    candidate: StartedCandidate,
  ) => RuntimeActivationFingerprint | undefined;
  /**
   * Proves application readiness after mandatory SDK cohort verification.
   * @param candidate - Unpublished child already matched to its graph/cohort.
   * @param signal - Activation cancellation consumed by readiness HTTP work.
   * @returns Joined proof or typed rejection before switching traffic.
   */
  readonly candidateVerificationEffect?: (
    candidate: StartedCandidate,
    signal: AbortSignal,
  ) => Effect.Effect<void, CliAdapterError>;
  /** Releases any request retained as the candidate's real route proof after publication. */
  readonly candidateVerificationPublished?: (candidate: StartedCandidate) => void;
  /** Releases a request retained by a candidate that could not be published. */
  readonly candidateVerificationRejected?: (candidate: StartedCandidate) => void;
  /**
   * Checks the final input epoch in the atomic traffic-switch turn.
   * @param candidate - Verified unpublished child.
   * @returns False when its prepared input epoch is obsolete.
   */
  readonly candidateAdmission?: (candidate: StartedCandidate) => boolean;
  readonly hostname?: string;
  readonly candidateHostname?: string;
  readonly stablePort?: number;
  readonly generatedDirectory?: string;
  readonly environment?: Readonly<Record<string, string | undefined>>;
  readonly maxStartupOutputBytes?: number;
  readonly candidateStopTimeoutMs?: number;
  readonly healthTimeoutMs?: number;
  /** Permits immutable prepared candidates to overlap independent health reads. */
  readonly candidateVerificationConcurrentHealth?: boolean;
  /** Native verification transport; prepared sessions restrict bearer credentials to internal probes. */
  readonly candidateVerificationFetch?: typeof fetch;
  readonly drainTimeoutMs?: number;
  readonly inspector?: Pick<InspectionBridgeOptions, "host" | "port"> | false;
  readonly inspectionRecords?: InspectionBridgeOptions["records"];
  /** Bridge credentials shared by every generation; generated per session when omitted. */
  readonly inspectionIdentity?: { readonly sessionId: string; readonly token: string };
  /**
   * Reads the bridge policy an accepted generation was built with.
   * @param generationToken - Promoted generation.
   * @returns Its policy, or undefined when the session keeps its current bridge.
   */
  readonly inspectionPolicy?: (generationToken: number) => DevInspectorPolicy | undefined;
  /**
   * Observes the bridge policy of every promoted generation, changed or not, once the
   * retired generation has drained.
   * @param policy - Bridge policy the session now serves.
   * @returns Completion after policy-owned resources are released or retained.
   */
  readonly inspectionApplied?: (policy: DevInspectorPolicy) => Effect.Effect<void>;
  /**
   * Observes a generation that was not promoted.
   * @param generationToken - Rejected, failed or superseded generation.
   * @returns Completion after resources prepared for it are rolled back.
   */
  readonly inspectionRejected?: (generationToken: number) => Effect.Effect<void>;
  /** Grace period after backend activation before optional inspector acquisition. */
  readonly supportStartupDelayMs?: number;
  readonly spawn?: typeof Bun.spawn;
  readonly signal?: AbortSignal;
  readonly installSignalHandlers?: boolean;
  readonly logger?: Omit<LoggerOptions, "component">;
  readonly onLog?: DevLog;
  /**
   * Consumes a projected native log envelope without lifecycle authority.
   * @param record - Existing structured log record.
   * @param origin - Declared process source.
   * @returns No value after synchronous admission.
   */
  readonly onRecord?: (record: LogRecord, origin: "application" | "relkit" | "inspector") => void;
  /**
   * Optionally intercepts a stable-proxy request before application routing.
   * @param request - Native incoming request.
   * @returns A native response receipt or absence to delegate to the backend.
   */
  readonly intercept?: (request: Request) => Promise<Response> | undefined;
  /**
   * Closes callback admission when shutdown begins.
   * @returns No value; resource cleanup remains with the session Scope.
   */
  readonly onStopping?: () => void;
  readonly terminal?: {
    readonly verbose?: boolean;
    readonly color?: boolean;
    readonly columns?: number;
  };
  readonly observability?: Omit<SupervisorObservabilityOptions, "activationFingerprint">;
  readonly localServices?: DevLocalServices;
  /** Native orchestration hook; acquired local owners close in the same session graph. */
  readonly localServicesEffect?: Effect.Effect<void>;
  /**
   * Native invalidation hook, captured by the owning compiler/cache service.
   * @param files - Admitted changed paths.
   * @returns Lazy session cache invalidation before the next compilation.
   */
  readonly sourceChangedEffect?: (files: readonly string[]) => Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/commands/dev.types.ts#L45)

## `editor.ts`

### initialize

Creates the synchronous editor plugin using the editor's own TypeScript instance.

**Signature**

```ts
declare const initialize: (modules: EditorModules) => ts.server.PluginModule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/editor.ts#L13)

## `index.ts`

### "./commands/dev.js" (namespace export)

Re-exports all named exports from the "./commands/dev.js" module.

**Signature**

```ts
export * from "./commands/dev.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/index.ts#L1)

### "./main.js" (namespace export)

Re-exports all named exports from the "./main.js" module.

**Signature**

```ts
export * from "./main.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/index.ts#L2)

## `tooling.ts`

Exposes finite native ownership, byte identities and import policy to
repository tooling through a declared package boundary. These exports acquire
no CLI session; callers own cancellation, compilation and publication scopes.

### DevSnapshot

**Signature**

```ts
declare const DevSnapshot: Struct<{
  readonly version: Literal<1>;
  readonly fingerprint: String;
  readonly graphHash: String;
  readonly graphFile: String;
  readonly activationFile: String;
  readonly manifestFile: String;
  readonly runtimeIntegrationsFile: String;
  readonly jobsManifestFile: optionalKey<String>;
  readonly localServicesFile: optionalKey<String>;
  readonly entrypoint: String;
  readonly importIndex: String;
  readonly activation: Struct<{
    readonly graphHash: String;
    readonly manifestHash: String;
    readonly jobsManifestHash: optionalKey<String>;
    readonly runtimeIntegrationsPlanHash: String;
    readonly localServicesPlanHash: optionalKey<String>;
  }>;
  readonly tools: Struct<{
    readonly layout: Literal<1>;
    readonly bun: String;
    readonly effect: String;
    readonly typescript: String;
    readonly relkit: String;
    readonly platform: Literals<
      readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64"]
    >;
  }>;
  readonly inspector: optionalKey<
    Struct<{
      readonly enabled: Boolean;
      readonly connection: Struct<{ readonly host: String; readonly port: Number }>;
      readonly maxPreviewBytes: Number;
    }>
  >;
  readonly ports: optionalKey<Struct<{ readonly backend: Number }>>;
  readonly readiness: Union<
    readonly [
      Struct<{
        readonly kind: Literal<"route">;
        readonly path: String;
        readonly status: Literal<200>;
        readonly body: String;
      }>,
      Struct<{ readonly kind: Literal<"graph">; readonly routeTableHash: String }>,
    ]
  >;
  readonly inputs: $Array<
    Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
  >;
  readonly typecheckInputs: Struct<{
    readonly files: $Array<
      Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
    >;
    readonly observations: $Array<
      Union<
        readonly [
          Struct<{
            readonly kind: Literals<readonly ["fileExists", "directoryExists"]>;
            readonly path: Union<readonly [String, Literal<".">]>;
            readonly exists: Boolean;
          }>,
          Struct<{
            readonly kind: Literals<readonly ["directories", "entries"]>;
            readonly path: Union<readonly [String, Literal<".">]>;
            readonly entries: $Array<String>;
          }>,
        ]
      >
    >;
  }>;
  readonly dependencies: $Array<
    Struct<{
      readonly name: String;
      readonly version: String;
      readonly root: String;
      readonly members: $Array<
        Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
      >;
    }>
  >;
  readonly artifacts: $Array<
    Struct<{ readonly path: String; readonly hash: String; readonly bytes: Number }>
  >;
  readonly routeImports: $Array<
    Struct<{ readonly routeId: String; readonly members: $Array<String> }>
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L14)

### SnapshotFileOperations

**Signature**

```ts
declare const SnapshotFileOperations: SnapshotFileOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L13)

### SnapshotFiles

**Signature**

```ts
declare const SnapshotFiles: typeof SnapshotFiles;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L12)

### SnapshotPointer

**Signature**

```ts
declare const SnapshotPointer: Struct<{
  readonly version: Literal<1>;
  readonly generation: String;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L14)

### narrowEffectImportPlugin

**Signature**

```ts
declare const narrowEffectImportPlugin: () => Bun.BunPlugin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L9)

### narrowEffectImports

**Signature**

```ts
declare const narrowEffectImports: (source: string, path: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L8)

### ownedNativePromise

**Signature**

```ts
declare const ownedNativePromise: <A>(
  operation: string,
  run: (signal: AbortSignal) => PromiseLike<A>,
) => Effect<Awaited<A>, CliAdapterError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L6)

### snapshotDigest

**Signature**

```ts
declare const snapshotDigest: (bytes: Uint8Array | string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L11)

### snapshotFilesLive

**Signature**

```ts
declare const snapshotFilesLive: Layer<SnapshotFiles, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/internal/tooling.ts#L12)

## `main-generator.ts`

Lazily loads CLI-owned scaffolding after command selection, validates the retained generator facade and preserves the public unavailable-API diagnostic.

### isGeneratorApi

Validates the minimal foreign facade while preserving its original identity.

**Signature**

```ts
declare const isGeneratorApi: (value: unknown) => value is CreateRelkitGeneratorApi;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-generator.ts#L36)

### loadCreateRelkit

Imports the optional generator using the existing public Promise contract.

**Throws**

The established unavailable-API failure.

**Signature**

```ts
declare const loadCreateRelkit: () => Promise<CreateRelkitGeneratorApi>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-generator.ts#L13)

### loadCreateRelkitEffect

Imports one foreign namespace lazily without creating a nested command runtime.

**Signature**

```ts
declare const loadCreateRelkitEffect: Effect.Effect<
  CreateRelkitGeneratorApi,
  CliAdapterError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-generator.ts#L18)

## `main-support-types.ts`

Defines CLI invocation I/O, presentation, runtime, and generator adapter contracts.

### CliCommandContext (interface)

Borrowed command inputs; all resource owners live in the invocation's service graph.

**Signature**

```ts
export interface CliCommandContext {
  /** Selected public command. */
  readonly command: string;
  /** Remaining public arguments. */
  readonly args: readonly string[];
  /** Whether output uses the established JSON protocol. */
  readonly json: boolean;
  /** Caller and native termination signals combined before prompting. */
  readonly signal: AbortSignal;
  /** Optional native terminal detection override. */
  readonly tty?: boolean;
  /** Optional borrowed output sinks. */
  readonly io?: CliIo;
  /** Public output/error projection. */
  readonly reporter: CliReporter;
  /** Synchronous callback into the scoped logger owner. */
  readonly log: CliLogger;
  /** Optional synchronous callback into the scoped status owner. */
  readonly onProgress?: (message: string) => void;
  /** Whether noninteractive continuous integration rules apply. */
  readonly ci?: boolean;
  /** Explicit working directory override. */
  readonly cwd?: string;
  /** Optional foreign prompt adapter, supplied before any prompt is admitted. */
  readonly promptDriver?: PromptDriver;
  /** Whether this invocation may ask the user for missing inputs. */
  readonly interactive?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L33)

### CliFailure (type alias)

Original public error object enriched with stable CLI status metadata.

**Signature**

```ts
type CliFailure = Error & {
  /** Stable public diagnostic code. */
  readonly code: string;
  /** Established native exit status. */
  readonly exitCode: number;
  /** Native termination signal when one caused the failure. */
  readonly signal?: "SIGINT" | "SIGTERM" | "SIGHUP";
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L128)

### CliIo (interface)

Borrowed synchronous output sinks; the invocation never closes these streams.

**Signature**

```ts
export interface CliIo {
  /** Writes one already formatted public output line. */
  readonly stdout: (line: string) => void;
  /** Writes one already formatted diagnostic line. */
  readonly stderr: (line: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L13)

### CliLogger (type alias)

Synchronous native callback bridge to the invocation's scoped logging queue.

**Signature**

```ts
type CliLogger = (
  level: LogLevel,
  message: string,
  fields?: Readonly<Record<string, unknown>>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L27)

### CliReporter (interface)

Established public JSON/human presentation contract.

**Signature**

```ts
export interface CliReporter {
  /** Emits an untrusted domain result with optional human presentation. */
  readonly output: (value: unknown, human?: string) => void;
  /** Emits the established public failure code and message. */
  readonly error: (code: string, message: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L20)

### CliRuntime (interface)

Optional public invocation injection; defaults are acquired lazily by the selected domain.

**Signature**

```ts
export interface CliRuntime {
  /** Borrowed public output sinks. */
  readonly io?: CliIo;
  /** Explicit package version override used by public help/version output. */
  readonly version?: string;
  /** Explicit terminal detection override. */
  readonly tty?: boolean;
  /** Explicit continuous integration mode. */
  readonly ci?: boolean;
  /** Continuing caller cancellation; never replaced by a domain-owned controller. */
  readonly signal?: AbortSignal;
  /** Whether the invocation installs temporary native termination handlers. */
  readonly installSignalHandlers?: boolean;
  /** Optional individual foreign SDK loader; unused commands never call it. */
  readonly loadCreateRelkit?: () => Promise<CreateRelkitGeneratorApi>;
  /** Explicit project discovery root. */
  readonly cwd?: string;
  /** Optional native prompt adapter retaining its original public contract. */
  readonly promptDriver?: PromptDriver;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L107)

### CreateRelkitGeneratorApi (interface)

Narrow compatible generator SDK; domain values remain opaque until their owner validates them.

**Signature**

```ts
export interface CreateRelkitGeneratorApi {
  /** Parses the generator's existing synchronous create contract. */
  readonly normalizeCreateOptions: (
    args: readonly string[],
    context: { readonly json: boolean },
  ) => unknown;
  /** Executes the generator-owned transaction with its native cancellation receipt. */
  readonly generateProject: (
    options: unknown,
    context: CliCommandContext,
  ) => unknown | Promise<unknown>;
  /** Resolves missing create inputs without adding duplicate CLI confirmation. */
  readonly resolveCreateOptionsDetails?: (
    args: readonly string[],
    context: {
      readonly json: boolean;
      readonly interactive: boolean;
      readonly signal?: AbortSignal;
      readonly promptDriver?: PromptDriver;
    },
  ) => Promise<{ readonly options: unknown; readonly prompted: boolean }>;
  /** Previews a validated create plan without mutation. */
  readonly planCreate?: (
    options: unknown,
    context?: { readonly cwd?: string },
  ) => Promise<CreateScaffoldPlan>;
  /** Resolves the existing add selection flow with caller cancellation. */
  readonly resolveAddRequestDetails?: (
    args: readonly string[],
    context: {
      readonly cwd?: string;
      readonly interactive: boolean;
      readonly signal?: AbortSignal;
      readonly promptDriver?: PromptDriver;
    },
  ) => Promise<{ readonly request: AddRequest; readonly prompted: boolean }>;
  /** Previews the existing add plan. */
  readonly planAdd?: (request: AddRequest) => Promise<ScaffoldPlan>;
  /** Applies one generator-owned add transaction and its cleanup policy. */
  readonly applyScaffoldPlan?: (
    plan: ScaffoldPlan,
    context?: ApplyScaffoldContext,
  ) => Promise<AddResult>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support-types.ts#L62)

## `main-support.ts`

Presents CLI output, help and terminal failures while keeping command cancellation scoped to its invocation; optional scaffold loading has a separate lazy owner.

### "./main-support-types.js" (namespace export)

Re-exports all named exports from the "./main-support-types.js" module.

**Signature**

```ts
export * from "./main-support-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L9)

### CLI_EXIT_CODES

Stable command, usage and native-signal exit statuses.

**Signature**

```ts
declare const CLI_EXIT_CODES: Readonly<{
  success: 0;
  failure: 1;
  usage: 2;
  sigint: 130;
  sigterm: 143;
  sighup: 129;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L14)

### CLI_VERSION

Version of this installed CLI package.

**Signature**

```ts
declare const CLI_VERSION: string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L12)

### createReporter

Builds the existing result/error presentation policy.

**Signature**

```ts
declare const createReporter: (json: boolean, io: CliIo) => CliReporter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L29)

### errorMessage

Formats an existing terminal diagnostic without changing Error identity.

**Signature**

```ts
declare const errorMessage: (error: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L155)

### fail

Constructs the typed product failure while retaining public code/exit fields.

**Signature**

```ts
declare const fail: (
  code: string,
  message: string,
  exitCode?: number,
  signal?: "SIGINT" | "SIGTERM" | "SIGHUP",
) => CliFailureError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L119)

### failSignal

Preserves signal-specific public cancellation codes.

**Signature**

```ts
declare const failSignal: (signal: "SIGINT" | "SIGTERM" | "SIGHUP") => CliFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L107)

### helpPayload

Projects public machine-readable help from pure command metadata.

**Signature**

```ts
declare const helpPayload: (
  version: string,
  command: string | readonly string[] | undefined,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L50)

### helpText

Formats the existing compact human help.

**Signature**

```ts
declare const helpText: (version: string, command: string | undefined) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L69)

### installSignals

Installs native process cancellation for one invocation owner.

**Signature**

```ts
declare const installSignals: (controller: AbortController) => () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L91)

### isGeneratorApi

**Signature**

```ts
declare const isGeneratorApi: (value: unknown) => value is CreateRelkitGeneratorApi;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L178)

### loadCreateRelkit

**Signature**

```ts
declare const loadCreateRelkit: () => Promise<CreateRelkitGeneratorApi>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L178)

### loadCreateRelkitEffect

**Signature**

```ts
declare const loadCreateRelkitEffect: Effect<CreateRelkitGeneratorApi, CliAdapterError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L178)

### toFailure

Applies the terminal invocation error policy after owned cleanup completes.

**Signature**

```ts
declare const toFailure: (error: unknown, signal: AbortSignal) => CliFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main-support.ts#L138)

## `main.ts`

Owns one native CLI invocation, its cancellation signals, presentation and scoped cleanup.

### "./cli-help-model.js" (namespace export)

Re-exports all named exports from the "./cli-help-model.js" module.

**Signature**

```ts
export * from "./cli-help-model.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main.ts#L17)

### "./main-support.js" (namespace export)

Re-exports all named exports from the "./main-support.js" module.

**Signature**

```ts
export * from "./main-support.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main.ts#L18)

### main

Runs the native process entry point using the same invocation owner.

**Signature**

```ts
declare const main: (argv?: readonly string[]) => Promise<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main.ts#L84)

### runCli

Executes one invocation with one service graph and scoped resources.

**Signature**

```ts
declare const runCli: (argv?: readonly string[], runtime?: CliRuntime) => Promise<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/main.ts#L26)

## `add-name.ts`

Normalizes authored artifact names into stable file stems, identifiers and logical ID segments before add planning can mutate project files.

### NormalizedArtifactName (interface)

Normalized user label, file stem, binding identifier and descriptor ID segment.

**Signature**

```ts
export interface NormalizedArtifactName {
  readonly input: string;
  readonly fileStem: string;
  readonly identifier: string;
  readonly idSegment: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-name.ts#L8)

### normalizeArtifactName

Normalizes one friendly label for source files, bindings, and stable IDs.

**Signature**

```ts
declare const normalizeArtifactName: (input: string) => NormalizedArtifactName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-name.ts#L20)

## `add-options.ts`

Builds normalized existing-project add requests from CLI arguments and enforces headless requirements before interactive resolution.

### normalizeAddRequest

Parses one complete non-interactive `relkit add` request.

**Signature**

```ts
declare const normalizeAddRequest: (
  args: readonly string[],
  context?: { readonly cwd?: string },
) => AddRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-options.ts#L35)

## `add-output.ts`

Formats scaffold plans and apply results into terminal or JSON output while preserving verification failures and actionable next steps.

### formatAddResult

Formats the completed add result and verification status.

**Signature**

```ts
declare const formatAddResult: (result: AddResult) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-output.ts#L46)

### formatScaffoldPlan

Formats a scaffold plan for review before mutation.

**Signature**

```ts
declare const formatScaffoldPlan: (plan: ScaffoldPlan) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-output.ts#L10)

## `add-plan.ts`

Composes project discovery, artifact planning and request-local builder state into an immutable scaffold plan before transaction acquisition.

### ScaffoldPlanning (class)

Cohesive discovery and planning authority, with isolated Ref state per request.

**Signature**

```ts
declare class ScaffoldPlanning
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-plan.ts#L38)

### planAdd

Preserves the existing public Promise API and stable rejection constructors.

**Signature**

```ts
declare const planAdd: (request: AddRequest) => Promise<ScaffoldPlan>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-plan.ts#L84)

### planAddEffect

Plans an artifact through an explicitly supplied planning service.

**Signature**

```ts
declare const planAddEffect: (
  request: AddRequest,
) => Effect.Effect<ScaffoldPlan, GeneratorIoError | GeneratorDomainError, ScaffoldPlanning>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-plan.ts#L72)

### scaffoldPlanningLive

Planning Layer captures only declaration discovery and filesystem authority.

**Signature**

```ts
declare const scaffoldPlanningLive: Layer.Layer<
  ScaffoldPlanning,
  never,
  GeneratorFileSystem | ProjectDiscoveryServiceTag
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-plan.ts#L46)

## `add-resolver.ts`

Composes add discovery and interactive resolution into one request workflow, preserving typed cancellation and validation failures.

### AddResolution (class)

Ordered interactive-add resolution, distinct from applying the user's final consent.

**Signature**

```ts
declare class AddResolution
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L27)

### ResolveAddContext

**Signature**

```ts
declare const ResolveAddContext: ResolveAddContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L24)

### ResolvedAddRequest

**Signature**

```ts
declare const ResolvedAddRequest: ResolvedAddRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L24)

### addResolutionLive

Captures declaration discovery, filesystem reads and prompt input at the owning Layer boundary.

**Signature**

```ts
declare const addResolutionLive: Layer.Layer<
  AddResolution,
  never,
  GeneratorFileSystem | GeneratorPrompt | ProjectDiscoveryServiceTag
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L35)

### resolveAddRequest

Preserves the existing normalized-request Promise API.

**Signature**

```ts
declare const resolveAddRequest: (
  args: readonly string[],
  context?: ResolveAddContext,
) => Promise<AddRequest>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L76)

### resolveAddRequestDetails

Preserves the existing detailed Promise API and add-flow consent behavior.

**Signature**

```ts
declare const resolveAddRequestDetails: (
  args: readonly string[],
  context?: ResolveAddContext,
) => Promise<ResolvedAddRequest>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L89)

### resolveAddRequestDetailsEffect

Resolves a request through explicit add-resolution authority while retaining consent metadata.

**Signature**

```ts
declare const resolveAddRequestDetailsEffect: (
  args: ReadonlyArray<string>,
  context?: ResolveAddContext | undefined,
) => Effect.Effect<
  ResolvedAddRequest,
  GeneratorIoError | GeneratorPromptError | GeneratorDomainError,
  AddResolution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.ts#L63)

## `add-resolver.types.ts`

Composes add discovery and interactive resolution into one request workflow, preserving typed cancellation and validation failures. This companion contains the shared planning contracts without executing work.

### AddResolutionService (interface)

Finite add-resolution owner with explicit discovery, prompt and source authority.

**Signature**

```ts
export interface AddResolutionService {
  /**
   * Resolves missing interactive add choices against source-discovered facts.
   * @param args - Literal flag and positional arguments.
   * @param context - Caller-owned settings and cancellation.
   * @returns An Effect returning a validated request and whether resolution prompted.
   */
  readonly resolve: (
    args: readonly string[],
    context: ResolveAddContext,
  ) => Effect.Effect<
    ResolvedAddRequest,
    GeneratorDomainError | GeneratorIoError | GeneratorPromptError
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.types.ts#L27)

### ResolveAddContext (interface)

Existing interactive-add resolution context.

**Signature**

```ts
export interface ResolveAddContext {
  readonly cwd?: string;
  readonly interactive?: boolean;
  readonly promptDriver?: PromptDriver;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.types.ts#L13)

### ResolvedAddRequest (interface)

Existing resolved add request and consent-relevant prompted flag.

**Signature**

```ts
export interface ResolvedAddRequest {
  readonly request: AddRequest;
  readonly prompted: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-resolver.types.ts#L21)

## `add-transaction.ts`

Acquires file and lock snapshots before applying an immutable scaffold plan; commit, rollback and cleanup retain the original transaction owner.

### AddCommandResult

**Signature**

```ts
declare const AddCommandResult: AddCommandResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L31)

### ApplyScaffoldContext

**Signature**

```ts
declare const ApplyScaffoldContext: ApplyScaffoldContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L31)

### ScaffoldTransaction (class)

Owns file mutation, install/check and rollback within one finite transaction scope.

**Signature**

```ts
declare class ScaffoldTransaction
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L34)

### applyScaffoldPlan

Preserves the Promise transaction API and canonical public error constructors.

**Signature**

```ts
declare const applyScaffoldPlan: (
  plan: ScaffoldPlan,
  context?: ApplyScaffoldContext,
) => Promise<AddResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L98)

### applyScaffoldPlanEffect

Applies a plan with a caller-supplied transaction service.

**Signature**

```ts
declare const applyScaffoldPlanEffect: (
  plan: ScaffoldPlan,
  context?: ApplyScaffoldContext | undefined,
) => Effect.Effect<
  AddResult,
  GeneratorIoError | GeneratorProcessError | GeneratorDomainError,
  ScaffoldTransaction
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L85)

### scaffoldTransactionLive

Transaction Layer captures explicit filesystem and process authority once.

**Signature**

```ts
declare const scaffoldTransactionLive: Layer.Layer<
  ScaffoldTransaction,
  never,
  GeneratorFileSystem | GeneratorProcess
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.ts#L43)

## `add-transaction.types.ts`

Acquires file and lock snapshots before applying an immutable scaffold plan; commit, rollback and cleanup retain the original transaction owner. This companion contains the shared planning contracts without executing work.

### AddCommandResult (interface)

Existing command-runner result compatibility surface.

**Signature**

```ts
export interface AddCommandResult extends GeneratorCommandResult {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.types.ts#L16)

### ApplyScaffoldContext (interface)

Existing scaffold transaction settings, preserving all caller injection points.

**Signature**

```ts
export interface ApplyScaffoldContext {
  readonly commandRunner?: GeneratorCommandRunner;
  readonly bunExecutable?: string;
  readonly relkitExecutable?: string;
  readonly signal?: AbortSignal;
  /**
   * Reports the current step through the caller's progress sink.
   * @param message - User-facing progress text for the current step.
   * @returns Completion after the sink receives one progress message.
   */
  readonly onProgress?: (message: string) => void;
  readonly deferVerification?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.types.ts#L19)

### ScaffoldTransactionService (interface)

Scoped add-transaction owner; infrastructure remains an explicit Layer dependency.

**Signature**

```ts
export interface ScaffoldTransactionService {
  /**
   * Applies planned files, installs/checks when required and rolls back failure.
   * @param plan - Immutable conflict-checked scaffold plan.
   * @param context - Caller-owned settings and cancellation.
   * @returns A scoped Effect returning the unchanged AddResult after all owned cleanup settles.
   */
  readonly apply: (
    plan: ScaffoldPlan,
    context: ApplyScaffoldContext,
  ) => Effect.Effect<AddResult, GeneratorDomainError | GeneratorIoError | GeneratorProcessError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/add-transaction.types.ts#L34)

## `index.ts`

CLI-owned existing-project scaffolding; creation remains a lightweight dependency.

### "./add-name.js" (namespace export)

Re-exports all named exports from the "./add-name.js" module.

**Signature**

```ts
export * from "./add-name.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L3)

### "./add-options.js" (namespace export)

Re-exports all named exports from the "./add-options.js" module.

**Signature**

```ts
export * from "./add-options.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L4)

### "./add-output.js" (namespace export)

Re-exports all named exports from the "./add-output.js" module.

**Signature**

```ts
export * from "./add-output.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L12)

### "./add-plan.js" (namespace export)

Re-exports all named exports from the "./add-plan.js" module.

**Signature**

```ts
export * from "./add-plan.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L11)

### "./add-resolver.js" (namespace export)

Re-exports all named exports from the "./add-resolver.js" module.

**Signature**

```ts
export * from "./add-resolver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L13)

### "./add-transaction.js" (namespace export)

Re-exports all named exports from the "./add-transaction.js" module.

**Signature**

```ts
export * from "./add-transaction.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L8)

### "./plan-builder.js" (namespace export)

Re-exports all named exports from the "./plan-builder.js" module.

**Signature**

```ts
export * from "./plan-builder.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L10)

### "./project-catalog.js" (namespace export)

Re-exports all named exports from the "./project-catalog.js" module.

**Signature**

```ts
export * from "./project-catalog.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L9)

### "./project-discovery-types.js" (namespace export)

Re-exports all named exports from the "./project-discovery-types.js" module.

**Signature**

```ts
export * from "./project-discovery-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L5)

### "./project-discovery.js" (namespace export)

Re-exports all named exports from the "./project-discovery.js" module.

**Signature**

```ts
export * from "./project-discovery.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L6)

### "./render-database.js" (namespace export)

Re-exports all named exports from the "./render-database.js" module.

**Signature**

```ts
export * from "./render-database.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L14)

### "./source-edit.js" (namespace export)

Re-exports all named exports from the "./source-edit.js" module.

**Signature**

```ts
export * from "./source-edit.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L7)

### "create-relkit" (namespace export)

Re-exports all named exports from the "create-relkit" module.

**Signature**

```ts
export * from "create-relkit";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/index.ts#L2)

## `plan-builder.ts`

Exposes the synchronous planning facade over request-local Effect state; file writes remain deferred until the transaction applies the resulting plan.

### PlanBuilder (class)

Per-request Effect owner with synchronous and Promise compatibility edges.

**Signature**

```ts
declare class PlanBuilder
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L15)

### read (method)

Reads source through the Promise compatibility edge.

**Signature**

```ts
declare const read: (path: string) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L21)

### create (method)

Plans file creation through the Promise compatibility edge.

**Signature**

```ts
declare const create: (path: string, content: string, mode?: number) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L32)

### update (method)

Plans a source update through the Promise compatibility edge.

**Signature**

```ts
declare const update: (path: string, transform: (source: string) => string) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L42)

### dependency (method)

Preserves the existing synchronous dependency API.

**Signature**

```ts
declare const dependency: (name: ScaffoldDependencyName) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L51)

### registerArtifact (method)

Preserves the existing synchronous artifact registration API.

**Signature**

```ts
declare const registerArtifact: (
  kind: DiscoveredArtifact["kind"],
  value: PlannedArtifactInput,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L61)

### registerProfile (method)

Preserves the existing synchronous profile registration API.

**Signature**

```ts
declare const registerProfile: (profile: DiscoveredProfile) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L70)

### script (method)

Preserves the existing synchronous script API.

**Signature**

```ts
declare const script: (name: string, command: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L80)

### warning (method)

Preserves the existing synchronous warning API.

**Signature**

```ts
declare const warning: (code: string, message: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L90)

### nextStep (method)

Preserves the existing synchronous next-step API.

**Signature**

```ts
declare const nextStep: (command: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L99)

### envExample (method)

Preserves the environment-example Promise API.

**Signature**

```ts
declare const envExample: (name: string, value?: string) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L109)

### gitignore (method)

Preserves the gitignore Promise API.

**Signature**

```ts
declare const gitignore: (pattern: string) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L118)

### finish (method)

Preserves the immutable plan Promise API.

**Signature**

```ts
declare const finish: () => Promise<ScaffoldPlan>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L126)

### relative (method)

Converts a source path into its existing project-relative representation.

**Signature**

```ts
declare const relative: (absolutePath: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/plan-builder.ts#L135)

## `project-catalog.ts`

Resolves declared package versions for selected scaffold dependencies using installed project metadata and the portable release catalog.

### resolveProjectDependencies

Preserves the project catalog Promise API and authored alias ownership.

**Signature**

```ts
declare const resolveProjectDependencies: (
  projectRoot: string,
  dependencies: Readonly<Record<string, string>>,
) => Promise<Readonly<Record<string, string>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-catalog.ts#L49)

### resolveProjectDependenciesEffect

Resolves authored Bun aliases without replacing declarations or hiding filesystem authority.

**Signature**

```ts
declare const resolveProjectDependenciesEffect: (
  projectRoot: string,
  dependencies: Readonly<Record<string, string>>,
) => Effect.Effect<
  Readonly<Record<string, string>>,
  GeneratorIoError | GeneratorDomainError,
  GeneratorFileSystem
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-catalog.ts#L24)

## `project-discovery-types.ts`

Defines immutable declaration-only scaffold discovery records. Compiler syntax
supplies layout/ownership; renderers preserve logical identities and provider
declarations while creating sources at their selected physical boundaries.

### DiscoveredArtifact (interface)

Static descriptor kind, identity, export form and owning source path.

**Signature**

```ts
export interface DiscoveredArtifact {
  readonly kind: SourceFactoryKind;
  readonly path: string;
  readonly domain?: string;
  readonly binding: string;
  readonly id?: string;
  readonly factory: string;
  readonly exported: boolean;
  readonly exportKind?: "default" | "named";
  readonly options: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery-types.ts#L35)

### DiscoveredProfile (interface)

Static provider capability, name, adapter/model identity and default selection.

**Signature**

```ts
export interface DiscoveredProfile {
  readonly capability: "bucket" | "cache" | "job" | "event" | "model";
  readonly name: string;
  readonly adapter?: string;
  readonly modelId?: string;
  readonly isDefault: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery-types.ts#L50)

### DiscoveredService (interface)

Source-declared service identity, capability, members and optional database facts.

**Signature**

```ts
export interface DiscoveredService {
  readonly domain: string;
  readonly path: string;
  readonly binding: string;
  readonly capability: "generic" | "database" | "auth";
  readonly dialect?: DatabaseDialect;
  readonly schemaPath?: string;
  readonly members: readonly DiscoveredServiceMember[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery-types.ts#L22)

### DiscoveredServiceMember (interface)

Statically discovered service member name and referenced binding.

**Signature**

```ts
export interface DiscoveredServiceMember {
  readonly name: string;
  readonly targetBinding?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery-types.ts#L14)

### ProjectDiscovery (interface)

Deterministic source-only app, provider, service and artifact facts for one project.

**Signature**

```ts
export interface ProjectDiscovery {
  /** Present on compiler-backed discovery; older supplied planning fixtures may omit it. */
  readonly layout?: ApplicationLayout;
  readonly projectRoot: string;
  readonly packagePath: string;
  readonly appPath: string;
  readonly appFactory: "defineApp" | "defineConfig";
  readonly envPath?: string;
  readonly services: readonly DiscoveredService[];
  readonly artifacts: readonly DiscoveredArtifact[];
  readonly profiles: readonly DiscoveredProfile[];
  readonly awsPulumiDeployment: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery-types.ts#L61)

## `project-discovery.ts`

Composes source inspection and filesystem discovery into service, artifact and provider facts used by CLI scaffolding resolution.

### ProjectDiscoveryServiceTag (class)

Declaration-only project discovery authority; never imports user application modules.

**Signature**

```ts
declare class ProjectDiscoveryServiceTag
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery.ts#L15)

### discoverProject

Preserves the existing Promise discovery API and original rejection constructors.

**Signature**

```ts
declare const discoverProject: (projectRoot: string) => Promise<ProjectDiscovery>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery.ts#L89)

### discoverProjectEffect

Discovers canonical RELKIT source facts using caller-provided filesystem authority.

**Example**

```ts
import { Effect } from "effect";
import { discoverProjectEffect, projectDiscoveryLive } from "@relkit/cli/scaffolding";
const inspect = discoverProjectEffect("./my-app").pipe(Effect.provide(projectDiscoveryLive));
// Supply GeneratorFileSystem at the application or test composition boundary.
```

**Signature**

```ts
declare const discoverProjectEffect: (
  projectRoot: string,
) => Effect.Effect<
  ProjectDiscovery,
  GeneratorIoError | GeneratorDomainError,
  ProjectDiscoveryServiceTag
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery.ts#L77)

### projectDiscoveryLive

Discovery implementation with bounded independent reads and deterministic source order.

**Signature**

```ts
declare const projectDiscoveryLive: Layer.Layer<
  ProjectDiscoveryServiceTag,
  never,
  GeneratorFileSystem
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/project-discovery.ts#L24)

## `render-database.ts`

Plans one native Drizzle service at the selected application boundary, including
schema tooling and environment declarations. Generator filesystem authority owns
source publication; no database client or migration runs during this workflow.

### RenderedDatabase

**Signature**

```ts
declare const RenderedDatabase: RenderedDatabase;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/render-database.ts#L12)

### renderDatabase

Preserves the renderDatabase Promise compatibility API.

**Signature**

```ts
declare const renderDatabase: (
  builder: PlanBuilder,
  request: Extract<AddRequest, { kind: "database" }>,
) => Promise<RenderedDatabase>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/render-database.ts#L93)

### renderDatabaseEffect

Plans database through the owning request and typed filesystem authority.

**Signature**

```ts
declare const renderDatabaseEffect: (
  builder: PlanBuilder,
  request: AddRequestBase & {
    readonly kind: "database";
    readonly orm: "drizzle";
    readonly dialect: DatabaseDialect;
    readonly authSchema?: boolean;
  },
) => Effect.Effect<RenderedDatabase, GeneratorIoError | GeneratorDomainError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/render-database.ts#L41)

## `render-database.types.ts`

Carries the selected native database dialect and physical source destinations
between database/auth scaffold stages. Values describe source declarations;
no connection, transaction or provider ownership is acquired by planning.

### RenderedDatabase (interface)

Validated discovered/planned native database and registered schema locations.

**Signature**

```ts
export interface RenderedDatabase {
  readonly dialect: Extract<AddRequest, { kind: "database" }>["dialect"];
  readonly servicePath: string;
  readonly schemaPath: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/render-database.types.ts#L10)

## `source-edit.ts`

Applies focused TypeScript syntax edits to existing source text while retaining unrelated authored statements and the planner's collision diagnostics.

### addFactoryObjectMember

Inserts one property into a canonical factory object or one nested object property.

**Signature**

```ts
declare const addFactoryObjectMember: (
  source: string,
  fileName: string,
  factories: readonly string[],
  path: readonly string[],
  memberName: string,
  memberSource: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L30)

### addSourceExport

Appends one export declaration after validating the source syntax.

**Signature**

```ts
declare const addSourceExport: (source: string, fileName: string, declaration: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L14)

### addSourceImport

**Signature**

```ts
declare const addSourceImport: (source: string, fileName: string, declaration: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L5)

### readFactoryObject

Parses the one supported factory object before editing its declarations.

**Signature**

```ts
declare const readFactoryObject: (
  source: string,
  fileName: string,
  factories: readonly string[],
) => ts.ObjectLiteralExpression;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L59)

### readFactoryStringProperty

Reads one literal string property from a supported factory call.

**Signature**

```ts
declare const readFactoryStringProperty: (
  source: string,
  fileName: string,
  factory: string,
  name: string,
  argumentIndex?: number,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L76)

### staticPropertyName

Reads statically known property names without evaluating computed expressions.

**Signature**

```ts
declare const staticPropertyName: (node: ts.PropertyName | undefined) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-edit.ts#L95)

## `source-import-edit.ts`

Adds and merges TypeScript import bindings required by planned source changes while preserving existing imports and module specifiers.

### addSourceImport

Adds or merges one import declaration without reprinting the source file.

**Signature**

```ts
declare const addSourceImport: (source: string, fileName: string, declaration: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/cli/src/scaffolding/source-import-edit.ts#L13)

---

# Client API
Source: https://relkit.dev/docs/api/client

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [createClient](/docs/api/client#createclient)

For configuration and examples, read [generated clients](/docs/modules/http/generated-clients), [streaming](/docs/modules/http/streaming), [jobs](/docs/modules/jobs).

For a complete workflow, follow [connect react](/guides/frontend/connect-react).

## Frontend usage

[Connect a React frontend](/guides/frontend/connect-react) shows the client side of this capability.

## Public imports

- `@relkit/client` — 11 exports
- `@relkit/client/server` — 1 exports
- `@relkit/client/server/tanstack-query` — 4 exports
- `@relkit/client/tanstack-query` — 2 exports
- `@relkit/client/react` — 117 exports
- `@relkit/client/jobs` — 60 exports
- `@relkit/client/build/next` — 1 exports
- `@relkit/client/build/vite` — 2 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                             | Kind  | Import from                                   | Example                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | ----- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [AgentBase](/docs/api/client#agentbase-interface)                                               | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L86)   |
| [AgentContent](/docs/api/client#agentcontent-interface)                                         | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentMessage](/docs/api/client#agentmessage-interface)                                         | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentNestedExecution](/docs/api/client#agentnestedexecution-type-alias)                        | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentOutput](/docs/api/client#agentoutput-type-alias)                                          | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentProgress](/docs/api/client#agentprogress-type-alias)                                      | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentRegistry](/docs/api/client#agentregistry-interface)                                       | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentResumeOptions](/docs/api/client#agentresumeoptions-interface)                             | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentRunOptions](/docs/api/client#agentrunoptions-interface)                                   | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentSelector](/docs/api/client#agentselector-type-alias)                                      | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentStopOptions](/docs/api/client#agentstopoptions-interface)                                 | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentThreadOptions](/docs/api/client#agentthreadoptions-interface)                             | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentTimelineItem](/docs/api/client#agenttimelineitem-type-alias)                              | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [AgentToolCall](/docs/api/client#agenttoolcall-interface)                                       | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ChannelHandlers](/docs/api/client#channelhandlers-type-alias)                                  | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ChannelRegistry](/docs/api/client#channelregistry-interface)                                   | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ChannelSelector](/docs/api/client#channelselector-type-alias)                                  | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [clearPendingOperations](/docs/api/client#clearpendingoperations)                               | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L80)  |
| [ClientAgentContract](/docs/api/client#clientagentcontract-interface)                           | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/client-react.ts#L34)                                     |
| [ClientAgentDynamic](/docs/api/client#clientagentdynamic-interface)                             | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/client-react.ts#L40)                                     |
| [ClientChannelContract](/docs/api/client#clientchannelcontract-interface)                       | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/client-react.ts#L26)                                     |
| [ClientHeaders](/docs/api/client#clientheaders-type-alias)                                      | Type  | `@relkit/client`                              | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ClientHeadersInit](/docs/api/client#clientheadersinit-type-alias)                              | Type  | `@relkit/client`                              | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ClientRegistry](/docs/api/client#clientregistry-interface)                                     | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ClientRouteContract](/docs/api/client#clientroutecontract-interface)                           | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/client-react.ts#L18)                                     |
| [ClientSelector](/docs/api/client#clientselector-type-alias)                                    | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ClientStreamContract](/docs/api/client#clientstreamcontract-interface)                         | Type  | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/client-react.ts#L21)                                     |
| [ContractFor](/docs/api/client#contractfor-type-alias)                                          | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [CountPresence](/docs/api/realtime#countpresence-interface)                                     | Type  | `@relkit/client/react`                        | [API example](/docs/api/realtime#countpresence-interface)                                                                         |
| [createAutoClient](/docs/api/client#createautoclient-1)                                         | Value | `@relkit/client`                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/client.test.ts#L124)             |
| [CreateAutoClientOptions](/docs/api/client#createautoclientoptions-interface)                   | Type  | `@relkit/client`                              | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [createClient](/docs/api/client#createclient-1)                                                 | Value | `@relkit/client`                              | [API example](/docs/api/client#createclient-1)                                                                                    |
| [CreateClientOptions](/docs/api/client#createclientoptions-interface)                           | Type  | `@relkit/client`                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/fixture-client.ts#L58)                   |
| [createRelkitServerContext](/docs/api/client#createrelkitservercontext)                         | Value | `@relkit/client/server/tanstack-query`        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/ssr.ts#L13)                              |
| [CreateRelkitServerContextOptions](/docs/api/client#createrelkitservercontextoptions-interface) | Type  | `@relkit/client/server/tanstack-query`        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [createServerClient](/docs/api/client#createserverclient)                                       | Value | `@relkit/client/server`                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/client.test.ts#L98)              |
| [createTanstackQueryUtils](/docs/api/client#createtanstackqueryutils)                           | Value | `@relkit/client/tanstack-query`               | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/server-query-entry.test.ts#L42)  |
| [createWebSocketClient](/docs/api/client#createwebsocketclient-1)                               | Value | `@relkit/client`                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/fixture-client.ts#L62)                   |
| [CreateWebSocketClientOptions](/docs/api/client#createwebsocketclientoptions-interface)         | Type  | `@relkit/client`                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/fixture-client.ts#L61)                   |
| [DefaultContract](/docs/api/client#defaultcontract-type-alias)                                  | Type  | `@relkit/client`                              | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [DefaultContractRegistry](/docs/api/client#defaultcontractregistry-interface)                   | Type  | `@relkit/client`                              | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [digestPendingRequest](/docs/api/client#digestpendingrequest)                                   | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L26)             |
| [ErrorFor](/docs/api/client#errorfor-type-alias)                                                | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [FiniteSelector](/docs/api/client#finiteselector-type-alias)                                    | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [forgetPending](/docs/api/client#forgetpending)                                                 | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [InputFor](/docs/api/client#inputfor-type-alias)                                                | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [isJobUnknownOutcome](/docs/api/client#isjobunknownoutcome)                                     | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/reconcile-unknown.ts#L4)                     |
| [ItemFor](/docs/api/client#itemfor-type-alias)                                                  | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobCancelInput](/docs/api/client#jobcancelinput-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobCancelInputFor](/docs/api/client#jobcancelinputfor-type-alias)                              | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobCancelName](/docs/api/client#jobcancelname-type-alias)                                      | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobCancelOutputFor](/docs/api/client#jobcanceloutputfor-type-alias)                            | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobClientField](/docs/api/client#jobclientfield-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobClientOperation](/docs/api/app#jobclientoperation-type-alias)                               | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobContract](/docs/api/client#jobcontract-type-alias)                                          | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L18)                                      |
| [JobErrorEnvelope](/docs/api/app#joberrorenvelope-interface)                                    | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobFailureFor](/docs/api/client#jobfailurefor-type-alias)                                      | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobFor](/docs/api/client#jobfor-type-alias)                                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobGetInput](/docs/api/client#jobgetinput-type-alias)                                          | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobListInput](/docs/api/client#joblistinput-type-alias)                                        | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobListQuery](/docs/api/client#joblistquery-type-alias)                                        | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobMutationOptions](/docs/api/client#jobmutationoptions-type-alias)                            | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobProcedureContract](/docs/api/client#jobprocedurecontract-interface)                         | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobProcedureSelector](/docs/api/client#jobprocedureselector-type-alias)                        | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L65)                                      |
| [JobRegistry](/docs/api/client#jobregistry-interface)                                           | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L17)                                      |
| [JobRetryInput](/docs/api/client#jobretryinput-type-alias)                                      | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRetryInputFor](/docs/api/client#jobretryinputfor-type-alias)                                | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRetryName](/docs/api/client#jobretryname-type-alias)                                        | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRetryOutputFor](/docs/api/client#jobretryoutputfor-type-alias)                              | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRunFor](/docs/api/client#jobrunfor-type-alias)                                              | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRunSelector](/docs/api/client#jobrunselector-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRunStatus](/docs/api/app#jobrunstatus-type-alias)                                           | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobRunWatchController](/docs/api/client#jobrunwatchcontroller-class)                           | Value | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobSelector](/docs/api/client#jobselector-type-alias)                                          | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobSnapshotFor](/docs/api/client#jobsnapshotfor-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobStreamGapError](/docs/api/client#jobstreamgaperror-class)                                   | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L471)         |
| [JobStreamInput](/docs/api/client#jobstreaminput-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobStreamOptions](/docs/api/client#jobstreamoptions-interface)                                 | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobStreamOverflowError](/docs/api/client#jobstreamoverflowerror-class)                         | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L424)         |
| [JobStreamProcedureContract](/docs/api/client#jobstreamprocedurecontract-interface)             | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerInput](/docs/api/client#jobtriggerinput-type-alias)                                  | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerInputFor](/docs/api/client#jobtriggerinputfor-type-alias)                            | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerName](/docs/api/client#jobtriggername-type-alias)                                    | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerOptions](/docs/api/client#jobtriggeroptions-interface)                               | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerOutputFor](/docs/api/client#jobtriggeroutputfor-type-alias)                          | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobTriggerSelector](/docs/api/client#jobtriggerselector-type-alias)                            | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [jobUnknownOutcome](/docs/api/client#jobunknownoutcome)                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L36)             |
| [JobWatchAbortedError](/docs/api/client#jobwatchabortederror-class)                             | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L160)         |
| [JobWatchController](/docs/api/client#jobwatchcontroller-interface)                             | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchDisposedError](/docs/api/client#jobwatchdisposederror-class)                           | Value | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchFrame](/docs/api/client#jobwatchframe-type-alias)                                      | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchFrameFor](/docs/api/client#jobwatchframefor-type-alias)                                | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchInput](/docs/api/client#jobwatchinput-type-alias)                                      | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchListener](/docs/api/client#jobwatchlistener-type-alias)                                | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchName](/docs/api/client#jobwatchname-type-alias)                                        | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchOptions](/docs/api/client#jobwatchoptions-interface)                                   | Type  | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/jobs/quality-fixture.ts#L51)                   |
| [JobWatchReadTimeoutError](/docs/api/client#jobwatchreadtimeouterror-class)                     | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L196)         |
| [JobWatchState](/docs/api/client#jobwatchstate-interface)                                       | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [JobWatchUnavailableError](/docs/api/client#jobwatchunavailableerror-class)                     | Value | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [matchesPendingRequest](/docs/api/client#matchespendingrequest)                                 | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L28)             |
| [MemberPresence](/docs/api/realtime#memberpresence-interface)                                   | Type  | `@relkit/client/react`                        | [API example](/docs/api/realtime#memberpresence-interface)                                                                        |
| [MutationSelector](/docs/api/client#mutationselector-type-alias)                                | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [NamedStreamFrame](/docs/api/app#namedstreamframe-type-alias)                                   | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [ORPCError](/docs/api/client#orpcerror)                                                         | Value | `@relkit/client`                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-sse-client.test.ts#L90)    |
| [OutputFor](/docs/api/client#outputfor-type-alias)                                              | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [PendingCapacityError](/docs/api/client#pendingcapacityerror-class)                             | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/agent/pending-service.test.ts#L43)             |
| [pendingOperations](/docs/api/client#pendingoperations)                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L114) |
| [PendingRecoveryUnavailableError](/docs/api/client#pendingrecoveryunavailableerror-class)       | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [PendingRememberOptions](/docs/api/client#pendingrememberoptions-interface)                     | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [pendingRequest](/docs/api/client#pendingrequest)                                               | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L27)             |
| [PendingRequestMismatchError](/docs/api/client#pendingrequestmismatcherror-class)               | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [pendingScopeKey](/docs/api/client#pendingscopekey)                                             | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [QuerySelector](/docs/api/client#queryselector-type-alias)                                      | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [reconcileAgentRun](/docs/api/client#reconcileagentrun)                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L101) |
| [relkit](/docs/api/client#relkit)                                                               | Value | `@relkit/client/build/vite`                   | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/vite.config.ts#L5)                       |
| [RelkitClientProvider](/docs/api/client#relkitclientprovider)                                   | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx#L27)                             |
| [RelkitClientProviderProps](/docs/api/client#relkitclientproviderprops-interface)               | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitClientRuntime](/docs/api/client#relkitclientruntime-interface)                           | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitHydrationState](/docs/api/client#relkithydrationstate-interface)                         | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [relkitJobKey](/docs/api/client#relkitjobkey)                                                   | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitJobKeyOptions](/docs/api/client#relkitjobkeyoptions-interface)                           | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [relkitKey](/docs/api/client#relkitkey)                                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/ssr.ts#L17)                              |
| [RelkitKeyScope](/docs/api/client#relkitkeyscope-interface)                                     | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitServerContext](/docs/api/client#relkitservercontext-interface)                           | Type  | `@relkit/client/server/tanstack-query`        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitServerHydrationState](/docs/api/client#relkitserverhydrationstate-interface)             | Type  | `@relkit/client/server/tanstack-query`        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitVitePlugin](/docs/api/client#relkitviteplugin-interface)                                 | Type  | `@relkit/client/build/vite`                   | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RelkitWriteError](/docs/api/client#relkitwriteerror-class)                                     | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [rememberJobPending](/docs/api/client#rememberjobpending)                                       | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L19)             |
| [rememberPending](/docs/api/client#rememberpending)                                             | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L64)  |
| [RunCancellationReceipt](/docs/api/app#runcancellationreceipt-interface)                        | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RunHandle](/docs/api/app#runhandle-interface)                                                  | Type  | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L36)                                      |
| [RunListQuery](/docs/api/app#runlistquery-interface)                                            | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RunPage](/docs/api/app#runpage-interface)                                                      | Type  | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector-api/tests/compatibility/jobs.test.ts#L85)         |
| [RunRetryReceipt](/docs/api/app#runretryreceipt-interface)                                      | Type  | `@relkit/client/jobs`                         | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [RunSnapshot](/docs/api/app#runsnapshot-type-alias)                                             | Type  | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L557)         |
| [RunWatchFrame](/docs/api/app#runwatchframe-type-alias)                                         | Type  | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L615)         |
| [SelectedJobField](/docs/api/client#selectedjobfield-type-alias)                                | Type  | `@relkit/client/react`, `@relkit/client/jobs` | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [StreamSelector](/docs/api/client#streamselector-type-alias)                                    | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [StreamState](/docs/api/client#streamstate-interface)                                           | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [TanstackQueryOperationContext](/docs/api/client#tanstackqueryoperationcontext)                 | Type  | `@relkit/client/tanstack-query`               | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [updatePending](/docs/api/client#updatepending)                                                 | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/pending.test.ts#L46)             |
| [useAgent](/docs/api/client#useagent)                                                           | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/assistant.tsx#L12)                       |
| [UseAgentResult](/docs/api/client#useagentresult-type-alias)                                    | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useChannel](/docs/api/client#usechannel)                                                       | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/announcements.tsx#L10)                   |
| [UseChannelOptions](/docs/api/client#usechanneloptions-interface)                               | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [UseChannelResult](/docs/api/client#usechannelresult-type-alias)                                | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useInfiniteRoute](/docs/api/client#useinfiniteroute)                                           | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useJobCancel](/docs/api/client#usejobcancel-1)                                                 | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L75)                                      |
| [useJobRetry](/docs/api/client#usejobretry-1)                                                   | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L76)                                      |
| [useJobRun](/docs/api/client#usejobrun)                                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/export-orders.tsx#L11)                   |
| [UseJobRunOptions](/docs/api/client#usejobrunoptions-interface)                                 | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [UseJobRunResult](/docs/api/client#usejobrunresult-interface)                                   | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useJobTrigger](/docs/api/client#usejobtrigger-1)                                               | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/export-orders.tsx#L10)                   |
| [useRealtime](/docs/api/client#userealtime)                                                     | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [UseRealtimeResult](/docs/api/client#userealtimeresult-interface)                               | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useRelkitClient](/docs/api/client#userelkitclient)                                             | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx#L10)                             |
| [useRoute](/docs/api/client#useroute)                                                           | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/announcements.tsx#L9)                    |
| [useRouteMutation](/docs/api/client#useroutemutation)                                           | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/create-order.tsx#L10)                    |
| [useRouteUtils](/docs/api/client#userouteutils)                                                 | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useStream](/docs/api/client#usestream)                                                         | Value | `@relkit/client/react`                        | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/report.tsx#L10)                          |
| [UseStreamResult](/docs/api/client#usestreamresult-interface)                                   | Type  | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [useSuspenseRoute](/docs/api/client#usesuspenseroute)                                           | Value | `@relkit/client/react`                        | [Module example](/docs/modules/http/generated-clients)                                                                            |
| [watchJobRun](/docs/api/client#watchjobrun)                                                     | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/watch-run.ts#L6)                             |
| [watchJobStream](/docs/api/client#watchjobstream-1)                                             | Value | `@relkit/client/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L301)         |
| [withRelkit](/docs/api/client#withrelkit)                                                       | Value | `@relkit/client/build/next`                   | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/next.config.ts#L4)                       |

## `manifest.ts`

### readPublicFingerprint

Reads the generated manifest fingerprint and rejects malformed generated output.

**Signature**

```ts
declare const readPublicFingerprint: (root?: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/manifest.ts#L9)

## `next.ts`

### withRelkit

Adds the generated public fingerprint and linked-workspace root to Next configuration.

**Signature**

```ts
declare const withRelkit: (config?: NextConfig, options?: { readonly root?: string }) => NextConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/next.ts#L12)

## `next.types.ts`

The Next configuration shape accepted and returned by the client build adapter.

### NextConfig (type alias)

The Next configuration shape accepted and returned by the client build adapter.

**Signature**

```ts
type NextConfig = Readonly<Record<string, unknown>> & {
  readonly env?: Readonly<Record<string, string | undefined>>;
  readonly turbopack?: Readonly<Record<string, unknown>> & { readonly root?: string };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/next.types.ts#L2)

## `vite.ts`

### RelkitVitePlugin

**Signature**

```ts
declare const RelkitVitePlugin: RelkitVitePlugin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/vite.ts#L3)

### relkit

Creates the Vite adapter that defines the generated client fingerprint.

**Signature**

```ts
declare const relkit: (options?: { readonly root?: string }) => RelkitVitePlugin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/vite.ts#L10)

## `vite.types.ts`

The minimal Vite plugin contract defining the generated client fingerprint.

### RelkitVitePlugin (interface)

The minimal Vite plugin contract defining the generated client fingerprint.

**Signature**

```ts
export interface RelkitVitePlugin {
  readonly name: "relkit";
  config(): {
    readonly define: Readonly<Record<string, string>>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/build/vite.types.ts#L2)

## `client-owner.ts`

### acquireClientOwner

Acquires one synchronous Layer context and an independently closable fiber scope.

**Signature**

```ts
declare const acquireClientOwner: <Service, Shape>(
  layer: Layer.Layer<Service>,
  key: Context.Key<Service, Shape>,
) => ClientOwner<Shape>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/client-owner.ts#L17)

## `client-owner.types.ts`

### ClientOwner (interface)

Once-acquired domain context with independent asynchronous lifetime ownership.

**Signature**

```ts
export interface ClientOwner<Shape> {
  /** Stable service identity; invoking it does not acquire another Layer. */
  readonly service: Shape;
  /** Runs one child owned by this context and joins its scoped finalizers.
   * @typeParam A - Successful operation result.
   * @typeParam E - Original typed failure, preserved at the Promise boundary.
   * @param effect - Lazy resource-owning service workflow.
   * @returns The original result or rejection after child cleanup. */
  readonly run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
  /** Interrupts active children and joins acquired-resource finalizers once.
   * @returns The same settlement Promise on concurrent or repeated closure. */
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/client-owner.types.ts#L7)

## `client-runtime.ts`

### runClient

Runs fully provided client work at a Promise adapter, retaining original failures.

**Signature**

```ts
declare const runClient: <A, E>(effect: Effect.Effect<A, E>, signal?: AbortSignal) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/client-runtime.ts#L16)

### runClientSync

Runs a fully provided synchronous state decision at its compatibility edge.

**Signature**

```ts
declare const runClientSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/client-runtime.ts#L27)

## `index.ts`

Exposes transport clients and the generated contract augmentation authority.
Install @relkit/client for HTTP/WebSocket clients; React and TanStack peers
are needed only by their explicit integration entrypoints.

### ClientHeaders

**Signature**

```ts
declare const ClientHeaders: ClientHeaders;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L11)

### ClientHeadersInit

**Signature**

```ts
declare const ClientHeadersInit: ClientHeadersInit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L10)

### CreateAutoClientOptions

**Signature**

```ts
declare const CreateAutoClientOptions: CreateAutoClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L14)

### CreateClientOptions

**Signature**

```ts
declare const CreateClientOptions: CreateClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L12)

### CreateWebSocketClientOptions

**Signature**

```ts
declare const CreateWebSocketClientOptions: CreateWebSocketClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L13)

### DefaultContract (type alias)

Contract inferred from the preserved public registry augmentation.

**Signature**

```ts
type DefaultContract = DefaultContractRegistry extends {
  readonly contract: infer Contract extends RouterContract;
}
  ? Contract
  : RouterContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L21)

### DefaultContractRegistry (interface)

Original augmentation authority; generated applications extend this exact module.

**Signature**

```ts
export interface DefaultContractRegistry {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L18)

### ORPCError

**Signature**

```ts
declare const ORPCError: typeof ORPCError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L7)

### createAutoClient

**Signature**

```ts
declare const createAutoClient: <Contract extends RouterContract = RouterContract>(
  options: CreateAutoClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L8)

### createClient

**Signature**

```ts
declare const createClient: <Contract extends RouterContract = RouterContract>(
  options: CreateClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L8)

### createWebSocketClient

**Signature**

```ts
declare const createWebSocketClient: <Contract extends RouterContract = RouterContract>(
  options: CreateWebSocketClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.ts#L8)

## `index.types.ts`

Native header inputs accepted without copying mutable Headers at construction.

### ClientHeaders (type alias)

Static headers or a provider evaluated for each future request.

**Signature**

```ts
type ClientHeaders = ClientHeadersInit | (() => ClientHeadersInit | Promise<ClientHeadersInit>);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.types.ts#L6)

### ClientHeadersInit (type alias)

Native header inputs accepted without copying mutable Headers at construction.

**Signature**

```ts
type ClientHeadersInit =
  Headers | Readonly<Record<string, string>> | readonly (readonly [string, string])[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.types.ts#L2)

### CreateAutoClientOptions (interface)

Combined transport options; fallback applies only to WebSocket establishment failure.

**Signature**

```ts
export interface CreateAutoClientOptions
  extends CreateClientOptions, CreateWebSocketClientOptions {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.types.ts#L34)

### CreateClientOptions (interface)

HTTP client configuration preserving browser credentials and caller transport overrides.

**Signature**

```ts
export interface CreateClientOptions {
  /** Application HTTP origin and optional base path. */
  readonly baseUrl: string;
  /** Request-time headers, including asynchronous providers. */
  readonly headers?: ClientHeaders;
  /** Browser fetch credentials policy; the live adapter supplies the existing default. */
  readonly credentials?: RequestInit["credentials"];
  /** Borrowed fetch implementation used for all HTTP requests. */
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.types.ts#L10)

### CreateWebSocketClientOptions (interface)

WebSocket configuration whose establishment timeout leaves accepted streams independent.

**Signature**

```ts
export interface CreateWebSocketClientOptions {
  /** Application origin converted to its corresponding WebSocket protocol. */
  readonly baseUrl: string;
  /** Maximum time allowed for initial connection establishment. */
  readonly establishmentTimeoutMs?: number;
  /** Headers retained with the existing WebSocket transport contract. */
  readonly headers?: ClientHeaders;
  /** Borrowed WebSocket constructor, or the browser implementation when omitted. */
  readonly websocket?: typeof WebSocket;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/index.types.ts#L22)

## `content.service.ts`

### JobContent (class)

Named job content lifetime and bounded continuity contract.

**Signature**

```ts
declare class JobContent
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/content.service.ts#L14)

### JobContentLive

Provides named-content acquisition with scoped native pulls and bounded continuity.

**See**

- packages/client/tests/compatibility/jobs-watch.test.ts for continuity assertions.

**Signature**

```ts
declare const JobContentLive: Layer.Layer<JobContent, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/content.service.ts#L25)

## `content.types.ts`

### JobContentService (interface)

Named stream acquisition, continuity and memory-bound ownership.

**Signature**

```ts
export interface JobContentService {
  /** Acquires named content and transfers native cleanup to the returned iterator.
   * @param client - Borrowed generated job transport.
   * @param job - Declared job key.
   * @param options - Existing stream identity, cursor, cancellation and bounds.
   * @returns Lazy acquisition of bounded frames or the original native failure. */
  readonly open: (
    client: unknown,
    job: string,
    options: JobStreamOptions,
  ) => Effect.Effect<AsyncIterable<NamedStreamFrame<JsonValue>>, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/content.types.ts#L6)

## `contracts.types.ts`

### JobCancelInput (type alias)

Cancellation request with caller-owned operation identity.

**Signature**

```ts
type JobCancelInput = {
  readonly runId: string;
  readonly operationId: OperationId | string;
  readonly reason?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L100)

### JobClientField (type alias)

Client-visible run projection fields.

**Signature**

```ts
type JobClientField = "status" | "input" | "progress" | "output" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L10)

### JobGetInput (type alias)

Authoritative run lookup and expected application identity.

**Signature**

```ts
type JobGetInput = {
  readonly runId: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L64)

### JobListInput (type alias)

Job-specific listing filters and expected application identity.

**Signature**

```ts
type JobListInput = {
  readonly query?: JobListQuery;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L72)

### JobListQuery (type alias)

Filters accepted by a generated job-specific list; ownership is server-derived.

**Signature**

```ts
type JobListQuery = Omit<RunListQuery, "jobId" | "service">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L5)

### JobProcedureContract (interface)

Generated finite procedure shape preserving input, output and failure inference.

**Signature**

```ts
export interface JobProcedureContract<Input, Output, Failure = Error> {
  readonly input: Input;
  readonly output: Output;
  readonly error: Failure;
  readonly operation: "query" | "mutation";
  readonly stream: false;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L28)

### JobRetryInput (type alias)

Retry request with caller-owned operation identity.

**Signature**

```ts
type JobRetryInput = {
  readonly runId: string;
  readonly operationId: OperationId | string;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L110)

### JobStreamInput (type alias)

Named content observation cursor and expected application identity.

**Signature**

```ts
type JobStreamInput<StreamName extends string = string> = {
  readonly runId: string;
  readonly name: StreamName;
  readonly after?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L90)

### JobStreamProcedureContract (interface)

Generated stream procedure shape preserving item and failure inference.

**Signature**

```ts
export interface JobStreamProcedureContract<Input, Item, Failure = Error> {
  readonly input: Input;
  readonly output: AsyncIterable<Item>;
  readonly item: Item;
  readonly error: Failure;
  readonly operation: "query" | "mutation";
  readonly stream: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L42)

### JobTriggerInput (type alias)

Job trigger request and expected application identity.

**Signature**

```ts
type JobTriggerInput<Input> = {
  readonly input: Input;
  readonly options?: JobTriggerOptions;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L55)

### JobTriggerOptions (interface)

Browser-safe options accepted by a generated job trigger.

**Signature**

```ts
export interface JobTriggerOptions {
  readonly operationId?: OperationId | string;
  readonly idempotencyKey?: string;
  readonly delay?: string;
  readonly at?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L13)

### JobWatchInput (type alias)

Run observation cursor and expected application identity.

**Signature**

```ts
type JobWatchInput = {
  readonly runId: string;
  readonly after?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/contracts.types.ts#L80)

## `controller-state.ts`

### stateFromFeedEvent

Projects observation status or frames into the existing external-store state.

**Signature**

```ts
declare const stateFromFeedEvent: <Run>(
  current: JobWatchState<Run>,
  event: FeedEvent<Run>,
  source: JobWatchOptions["source"],
) => JobWatchState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller-state.ts#L13)

## `controller-support.ts`

### freeze

Deep-freezes external-store state without cloning its identity.

**Signature**

```ts
declare const freeze: <T>(value: T) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller-support.ts#L24)

### notify

Isolates one external-store callback from observation ownership.

**Signature**

```ts
declare const notify: <Run>(listener: JobWatchListener<Run>, state: JobWatchState<Run>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller-support.ts#L10)

### reconnectAfterTeardown

Waits for interrupted setup and cleanup before admitting the next connection.

**Signature**

```ts
declare const reconnectAfterTeardown: (
  previous: Promise<void> | undefined,
  teardown: Promise<void> | undefined,
  start: () => Promise<void>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller-support.ts#L49)

### resumedOptions

Adds the retained snapshot cursor to the existing observation options.

**Signature**

```ts
declare const resumedOptions: <Run>(
  options: JobWatchOptions,
  state: JobWatchState<Run>,
) => JobWatchOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller-support.ts#L35)

## `controller.service.ts`

### JobControllers (class)

Creates passive external-store views over scoped physical observation services.

**Signature**

```ts
declare class JobControllers
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.service.ts#L15)

### JobControllersLive

Acquires the controller factory once without opening native requests.

**Example**

```ts
import { Layer, ManagedRuntime } from "effect";
import { runExecutionSync } from "@relkit/contracts/operation";
import { JobControllers, JobControllersLive } from "./controller.service.js";
import { JobFeedRegistryLive } from "./feed-registry.service.js";
export async function observeJob(client: unknown): Promise<void> {
  const owner = ManagedRuntime.make(JobControllersLive.pipe(Layer.provide(JobFeedRegistryLive)));
  try {
    const factory = runExecutionSync(owner, JobControllers);
    const view = factory.view(client, "job", { runId: "run" });
    try {
      await view.connect();
    } finally {
      await view.dispose();
    }
  } finally {
    await owner.dispose();
  }
}
```

**Signature**

```ts
declare const JobControllersLive: Layer.Layer<JobControllers, never, JobFeedRegistry>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.service.ts#L39)

## `controller.service.types.ts`

### JobControllerFactory (interface)

Once-acquired state factory sharing only complete-key physical observations.

**Signature**

```ts
export interface JobControllerFactory {
  readonly view: (client: unknown, name: string, options: JobWatchOptions) => JobControllerView;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.service.types.ts#L16)

### JobControllerView (interface)

Passive external-store state; asynchronous native work belongs to the feed service.

**Signature**

```ts
export interface JobControllerView {
  readonly snapshot: () => JobWatchState<unknown>;
  readonly subscribe: (listener: JobWatchListener<unknown>) => () => void;
  readonly assertLive: () => void;
  readonly isDisconnected: () => boolean;
  readonly connect: () => Promise<void>;
  readonly disconnect: () => Promise<void>;
  readonly dispose: () => Promise<void>;
  readonly refetch: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.service.types.ts#L4)

## `controller.ts`

### JobRunWatchController (class)

Passive synchronous external-store facade over scoped physical feed services.

**Signature**

```ts
declare class JobRunWatchController<Run> {
  constructor(client: unknown, name: string, options: JobWatchOptions);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L24)

### getSnapshot (method)

**Signature**

```ts
declare const getSnapshot: () => JobWatchState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L42)

### subscribe (method)

Borrows controller state publication without acquiring native work.

**Signature**

```ts
declare const subscribe: (listener: JobWatchListener<Run>) => () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L51)

### connect (method)

**Signature**

```ts
declare const connect: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L56)

### disconnect (method)

**Signature**

```ts
declare const disconnect: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L70)

### dispose (method)

**Signature**

```ts
declare const dispose: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L82)

### refetch (method)

**Signature**

```ts
declare const refetch: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L88)

### watchJobRun

Creates an idle, independently disposable external-store watch owner.

**Signature**

```ts
declare const watchJobRun: <Name extends string>(
  client: unknown,
  name: Name,
  options: JobWatchOptions,
) => JobWatchController<JobRunFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/controller.ts#L102)

## `feed-registry.service.ts`

### JobFeedRegistry (class)

Reference-counted native observation ownership, independent of controller state.

**Signature**

```ts
declare class JobFeedRegistry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/feed-registry.service.ts#L14)

### JobFeedRegistryLive

Provides reference-counted feed sharing within complete security/protocol keys.

**Example**

```ts
import { Effect, ManagedRuntime } from "effect";
import { runExecutionSync } from "@relkit/contracts/operation";
import { JobFeedRegistry, JobFeedRegistryLive } from "./feed-registry.service.js";
export async function borrowJobFeed(client: unknown): Promise<void> {
  const owner = ManagedRuntime.make(JobFeedRegistryLive);
  try {
    const registry = runExecutionSync(owner, JobFeedRegistry);
    const borrow = await owner.runPromise(registry.borrow(client, "job", { runId: "run" }));
    try {
      await borrow.feed.addLease("view", () => undefined);
    } finally {
      await Effect.runPromise(borrow.release);
    }
  } finally {
    await owner.dispose();
  }
}
```

**See**

- tests/jobs/registry.test.ts for checked scoped native cleanup.

**Signature**

```ts
declare const JobFeedRegistryLive: Layer.Layer<JobFeedRegistry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/feed-registry.service.ts#L41)

## `feed-registry.types.ts`

### JobFeedRegistryService (interface)

Reference-counted observation registry, with complete request authority.

**Signature**

```ts
export interface JobFeedRegistryService {
  /** Registers a passive external-store view without another Layer acquisition. */
  readonly borrowView: (client: unknown, name: string, options: JobWatchOptions) => WatchFeedBorrow;
  readonly borrow: (
    client: unknown,
    name: string,
    options: JobWatchOptions,
  ) => Effect.Effect<WatchFeedBorrow>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/feed-registry.types.ts#L23)

### WatchFeedBorrow (interface)

One independently closable reference to a shared feed.

**Signature**

```ts
export interface WatchFeedBorrow {
  readonly feed: SharedWatchFeed<unknown>;
  /** Excludes a final retiring group before native callbacks can reconnect. */
  readonly retire: Effect.Effect<void>;
  readonly release: Effect.Effect<void>;
  /** Passive view retirement; this boundary never awaits native work. */
  readonly retireView: () => void;
  /** Joins the shared native borrow after passive view retirement. */
  readonly releaseView: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/feed-registry.types.ts#L12)

### WatchFeedGroup (interface)

One native RcMap borrow shared by independently retired passive view leases.

**Signature**

```ts
export interface WatchFeedGroup {
  readonly feed: SharedWatchFeed<unknown>;
  readonly scope: Scope.Closeable;
  readonly references: Ref.Ref<number>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/feed-registry.types.ts#L6)

## `index.ts`

### "./contracts.types.js" (namespace export)

Re-exports all named exports from the "./contracts.types.js" module.

**Signature**

```ts
export * from "./contracts.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L15)

### JobCancelInputFor

**Signature**

```ts
declare const JobCancelInputFor: JobCancelInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L29)

### JobCancelName

**Signature**

```ts
declare const JobCancelName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L38)

### JobCancelOutputFor

**Signature**

```ts
declare const JobCancelOutputFor: JobCancelOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L30)

### JobClientOperation

**Signature**

```ts
declare const JobClientOperation: JobClientOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L2)

### JobContract

**Signature**

```ts
declare const JobContract: JobContract<
  Name,
  JobId,
  Input,
  Output,
  Failure,
  Progress,
  Streams,
  Operations,
  Fields
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L19)

### JobErrorEnvelope

**Signature**

```ts
declare const JobErrorEnvelope: JobErrorEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L3)

### JobFailureFor

**Signature**

```ts
declare const JobFailureFor: JobFailureFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L31)

### JobFor

**Signature**

```ts
declare const JobFor: JobFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L20)

### JobProcedureSelector

**Signature**

```ts
declare const JobProcedureSelector: JobProcedureSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L21)

### JobRegistry

**Signature**

```ts
declare const JobRegistry: JobRegistry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L17)

### JobRetryInputFor

**Signature**

```ts
declare const JobRetryInputFor: JobRetryInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L32)

### JobRetryName

**Signature**

```ts
declare const JobRetryName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L39)

### JobRetryOutputFor

**Signature**

```ts
declare const JobRetryOutputFor: JobRetryOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L33)

### JobRunFor

**Signature**

```ts
declare const JobRunFor: JobRunFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L34)

### JobRunSelector

**Signature**

```ts
declare const JobRunSelector: JobRunSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L25)

### JobRunStatus

**Signature**

```ts
declare const JobRunStatus: JobRunStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L4)

### JobRunWatchController

**Signature**

```ts
declare const JobRunWatchController: typeof JobRunWatchController;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L57)

### JobSelector

**Signature**

```ts
declare const JobSelector: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L22)

### JobSnapshotFor

**Signature**

```ts
declare const JobSnapshotFor: JobSnapshotFor<Input, Output, Progress, Failure, Fields>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L23)

### JobStreamGapError

**Signature**

```ts
declare const JobStreamGapError: typeof JobStreamGapError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L58)

### JobStreamOptions

**Signature**

```ts
declare const JobStreamOptions: JobStreamOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L59)

### JobStreamOverflowError

**Signature**

```ts
declare const JobStreamOverflowError: typeof JobStreamOverflowError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L58)

### JobTriggerInputFor

**Signature**

```ts
declare const JobTriggerInputFor: JobTriggerInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L35)

### JobTriggerName

**Signature**

```ts
declare const JobTriggerName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L40)

### JobTriggerOutputFor

**Signature**

```ts
declare const JobTriggerOutputFor: JobTriggerOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L36)

### JobTriggerSelector

**Signature**

```ts
declare const JobTriggerSelector: JobTriggerSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L24)

### JobWatchAbortedError

**Signature**

```ts
declare const JobWatchAbortedError: typeof JobWatchAbortedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L52)

### JobWatchController

**Signature**

```ts
declare const JobWatchController: JobWatchController<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L45)

### JobWatchDisposedError

**Signature**

```ts
declare const JobWatchDisposedError: typeof JobWatchDisposedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L53)

### JobWatchFrame

**Signature**

```ts
declare const JobWatchFrame: JobWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L46)

### JobWatchFrameFor

**Signature**

```ts
declare const JobWatchFrameFor: JobWatchFrameFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L37)

### JobWatchListener

**Signature**

```ts
declare const JobWatchListener: JobWatchListener<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L47)

### JobWatchName

**Signature**

```ts
declare const JobWatchName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L41)

### JobWatchOptions

**Signature**

```ts
declare const JobWatchOptions: JobWatchOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L48)

### JobWatchReadTimeoutError

**Signature**

```ts
declare const JobWatchReadTimeoutError: typeof JobWatchReadTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L55)

### JobWatchState

**Signature**

```ts
declare const JobWatchState: JobWatchState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L49)

### JobWatchUnavailableError

**Signature**

```ts
declare const JobWatchUnavailableError: typeof JobWatchUnavailableError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L54)

### NamedStreamFrame

**Signature**

```ts
declare const NamedStreamFrame: NamedStreamFrame<Item>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L5)

### RunCancellationReceipt

**Signature**

```ts
declare const RunCancellationReceipt: RunCancellationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L6)

### RunHandle

**Signature**

```ts
declare const RunHandle: RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L7)

### RunListQuery

**Signature**

```ts
declare const RunListQuery: RunListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L8)

### RunPage

**Signature**

```ts
declare const RunPage: RunPage<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L9)

### RunRetryReceipt

**Signature**

```ts
declare const RunRetryReceipt: RunRetryReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L10)

### RunSnapshot

**Signature**

```ts
declare const RunSnapshot: RunSnapshot<Input, Output, Progress, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L11)

### RunWatchFrame

**Signature**

```ts
declare const RunWatchFrame: RunWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L12)

### SelectedJobField

**Signature**

```ts
declare const SelectedJobField: SelectedJobField<Fields, Field>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L26)

### watchJobRun

**Signature**

```ts
declare const watchJobRun: <Name extends string>(
  client: unknown,
  name: Name,
  options: JobWatchOptions,
) => JobWatchController<JobRunFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L57)

### watchJobStream

**Signature**

```ts
declare const watchJobStream: <Item extends JsonValue = JsonValue>(
  client: unknown,
  job: string,
  options: JobStreamOptions,
) => Promise<AsyncIterable<NamedStreamFrame<Item>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/index.ts#L58)

## `job-registry-derived.ts`

### "./job-registry-derived.types.js" (namespace export)

Re-exports all named exports from the "./job-registry-derived.types.js" module.

**Signature**

```ts
export * from "./job-registry-derived.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.ts#L3)

## `job-registry-derived.types.ts`

### JobCancelInputFor (type alias)

Infers the exact cancellation request or its dynamic fallback.

**Signature**

```ts
type JobCancelInputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly runs: infer Runs }
    ? Runs extends { readonly cancel: infer Cancel }
      ? Cancel extends { readonly input: infer Input }
        ? Input
        : never
      : never
    : never
  : JobCancelInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L117)

### JobCancelName (type alias)

Names of jobs exposing cancellation receipts.

**Signature**

```ts
type JobCancelName = JobRunName<"cancel">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L44)

### JobCancelOutputFor (type alias)

Infers the declared cancellation receipt or its standard fallback.

**Signature**

```ts
type JobCancelOutputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly runs: infer Runs }
    ? Runs extends { readonly cancel: infer Cancel }
      ? Cancel extends { readonly output: infer Output }
        ? Output
        : RunCancellationReceipt
      : RunCancellationReceipt
    : RunCancellationReceipt
  : RunCancellationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L131)

### JobFailureFor (type alias)

Infers declared job failures while preserving the standard error envelope fallback.

**Signature**

```ts
type JobFailureFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly trigger: infer Trigger }
    ? Trigger extends { readonly error: infer Failure }
      ? Failure
      : JobErrorEnvelope
    : JobErrorEnvelope
  : JobErrorEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L79)

### JobRetryInputFor (type alias)

Infers the exact retry request or its dynamic fallback.

**Signature**

```ts
type JobRetryInputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly runs: infer Runs }
    ? Runs extends { readonly retry: infer Retry }
      ? Retry extends { readonly input: infer Input }
        ? Input
        : never
      : never
    : never
  : JobRetryInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L145)

### JobRetryName (type alias)

Names of jobs exposing retry receipts.

**Signature**

```ts
type JobRetryName = JobRunName<"retry">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L49)

### JobRetryOutputFor (type alias)

Infers the declared retry receipt or its standard fallback.

**Signature**

```ts
type JobRetryOutputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly runs: infer Runs }
    ? Runs extends { readonly retry: infer Retry }
      ? Retry extends { readonly output: infer Output }
        ? Output
        : RunRetryReceipt
      : RunRetryReceipt
    : RunRetryReceipt
  : RunRetryReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L159)

### JobRunFor (type alias)

Infers authoritative run payloads from get or watch contracts.

**Signature**

```ts
type JobRunFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly runs: infer Runs }
    ? Runs extends { readonly get: infer Get }
      ? Get extends { readonly output: infer Output }
        ? Output
        : RunSnapshot
      : Runs extends { readonly watch: infer Watch }
        ? Watch extends { readonly output: AsyncIterable<infer Frame> }
          ? Frame extends { readonly run: infer Run }
            ? Run
            : RunSnapshot
          : RunSnapshot
        : RunSnapshot
    : RunSnapshot
  : RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L91)

### JobRunName (type alias)

Names of jobs exposing the selected run operation.

**Signature**

```ts
type JobRunName<Operation extends JobRunOperation> = {
  [Name in JobSelector]: JobFor<Name> extends { readonly runs: infer Runs }
    ? Operation extends keyof Runs
      ? Name
      : never
    : never;
}[JobSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L28)

### JobTriggerInputFor (type alias)

Infers the declared trigger input while preserving the dynamic fallback.

**Signature**

```ts
type JobTriggerInputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly trigger: infer Trigger }
    ? Trigger extends { readonly input: infer Input }
      ? Input
      : never
    : never
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L55)

### JobTriggerName (type alias)

Names of jobs exposing a declared trigger procedure.

**Signature**

```ts
type JobTriggerName = {
  [Name in JobSelector]: JobFor<Name> extends { readonly trigger: unknown } ? Name : never;
}[JobSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L20)

### JobTriggerOutputFor (type alias)

Infers the declared trigger receipt while preserving RunHandle fallback.

**Signature**

```ts
type JobTriggerOutputFor<Name extends string> = Name extends JobSelector
  ? JobFor<Name> extends { readonly trigger: infer Trigger }
    ? Trigger extends { readonly output: infer Output }
      ? Output
      : never
    : never
  : RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L67)

### JobWatchFrameFor (type alias)

Wraps the inferred authoritative run payload in its native watch frame.

**Signature**

```ts
type JobWatchFrameFor<Name extends string> = RunWatchFrame<JobRunFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L111)

### JobWatchName (type alias)

Names of jobs exposing native run observation.

**Signature**

```ts
type JobWatchName = JobRunName<"watch">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-derived.types.ts#L39)

## `job-registry-types.ts`

Augmentable registry of application-declared job contracts.

### "./job-registry.types.js" (namespace export)

Re-exports all named exports from the "./job-registry.types.js" module.

**Signature**

```ts
export * from "./job-registry.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-types.ts#L8)

### JobRegistry (interface)

Augmentable registry of application-declared job contracts.

**Signature**

```ts
export interface JobRegistry {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry-types.ts#L6)

## `job-registry.types.ts`

### JobContract (type alias)

Generated job declaration retaining operation availability and selective field inference.

**Signature**

```ts
type JobContract<
  Name extends string = string,
  JobId extends string = string,
  Input = unknown,
  Output = unknown,
  Failure = JobErrorEnvelope,
  Progress = unknown,
  Streams extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
  Operations extends readonly JobClientOperation[] = readonly JobClientOperation[],
  Fields extends readonly JobClientField[] = readonly [],
> = {
  readonly name: Name;
  readonly jobId: JobId;
} & TriggerMember<Input, Failure, Operations> &
  RunMembers<Input, Output, Progress, Failure, Streams, Operations, Fields>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L166)

### JobFor (type alias)

Looks up one declared job contract without widening its members.

**Signature**

```ts
type JobFor<Name extends JobSelector> = JobRegistry[Name];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L191)

### JobProcedureSelector (type alias)

Union of exact procedure selectors exposed by one declared job.

**Signature**

```ts
type JobProcedureSelector<Name extends JobSelector = JobSelector> =
  JobTriggerSelector<Name> | JobRunSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L221)

### JobRunSelector (type alias)

Produces exact selectors for the declared run operations.

**Signature**

```ts
type JobRunSelector<Name extends JobSelector> =
  JobFor<Name> extends { readonly runs: infer Runs }
    ? {
        [
          Operation in "get" | "list" | "watch" | "stream" | "cancel" | "retry"
        ]: Runs extends Record<Operation, unknown>
          ? Runs[Operation] extends never
            ? never
            : `${Name}.runs.${Operation}`
          : never;
      }["get" | "list" | "watch" | "stream" | "cancel" | "retry"]
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L204)

### JobSelector (type alias)

String keys of the application-declared job registry.

**Signature**

```ts
type JobSelector = Extract<keyof JobRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L185)

### JobSnapshotFor (type alias)

Projects run payload fields according to the declared client visibility contract.

**Signature**

```ts
type JobSnapshotFor<
  Input,
  Output,
  Progress,
  Failure,
  Fields extends readonly JobClientField[],
> = RunSnapshot<
  SelectedJobField<Fields, "input"> extends true ? Input : never,
  SelectedJobField<Fields, "output"> extends true ? Output : never,
  SelectedJobField<Fields, "progress"> extends true ? Progress : never,
  SelectedJobField<Fields, "error"> extends true ? Failure : never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L44)

### JobTriggerSelector (type alias)

Produces the exact trigger selector only for trigger-capable jobs.

**Signature**

```ts
type JobTriggerSelector<Name extends JobSelector> =
  JobFor<Name> extends { readonly trigger: unknown } ? `${Name}.trigger` : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L197)

### SelectedJobField (type alias)

Tests whether a projection field belongs to the declared visible field set.

**Signature**

```ts
type SelectedJobField<
  Fields extends readonly JobClientField[],
  Field extends JobClientField,
> = Field extends Fields[number] ? true : false;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/job-registry.types.ts#L31)

## `observation.service.ts`

### JobObservation (class)

Cohesive native/polling observation workflow, replaceable at the feed owner.

**Signature**

```ts
declare class JobObservation
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/observation.service.ts#L7)

### JobObservationLive

Acquires the live observation workflow; native dependencies are supplied by each feed.

**See**

- tests/jobs/quality.test.ts for checked observation, recovery and interruption cases.

**Signature**

```ts
declare const JobObservationLive: Layer.Layer<JobObservation, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/observation.service.ts#L17)

## `observation.types.ts`

### JobObservationService (interface)

Live/test contract for one independently cancellable shared observation lifetime.

**Signature**

```ts
export interface JobObservationService {
  /** Observes one physical feed until confirmed completion or retirement.
   * @typeParam Run - Application-declared run payload.
   * @param feed - Native dependency and authoritative observation state.
   * @param generation - Active worker generation rejecting stale callbacks.
   * @returns A lazy observed and interruptible workflow preserving native failures. */
  readonly consume: <Run>(
    feed: WatchFeedLoop<Run>,
    generation: number,
  ) => Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/observation.types.ts#L5)

## `read-timeout.ts`

### readWatchNext

Bounds one native iterator pull using the caller's cancellation authority.

**Signature**

```ts
declare const readWatchNext: (
  iterator: AsyncIterator<unknown>,
  signal: AbortSignal,
  timeoutMs?: number,
) => Promise<IteratorResult<unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/read-timeout.ts#L10)

### timedCall

Races one native boundary call against cancellation and the existing bounded read deadline.

**Signature**

```ts
declare const timedCall: <T>(
  signal: AbortSignal,
  timeoutMs: number,
  operation: (signal: AbortSignal) => Promise<T> | T,
) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/read-timeout.ts#L26)

## `reconcile-boundary.ts`

### asWatchFrame

Checks the existing selective watch-frame envelope and retains original fields.

**Signature**

```ts
declare const asWatchFrame: (value: unknown) => RunWatchFrame;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L109)

### isProcedureNotFound

Recognizes the existing missing-procedure envelope used for safe read fallback.

**Signature**

```ts
declare const isProcedureNotFound: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L82)

### isRunSnapshot

Checks the existing selective run-snapshot authority without stricter payload validation.

**Signature**

```ts
declare const isRunSnapshot: (value: unknown) => value is RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L121)

### optionalJobProcedure

Resolves an optional generated procedure while preserving unrelated lookup defects.

**Signature**

```ts
declare const optionalJobProcedure: (
  root: unknown,
  name: string,
  operation: string,
) => Procedure | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L63)

### ownJobProcedure

Finds a concrete job procedure while avoiding synthesized proxy properties.

**Signature**

```ts
declare const ownJobProcedure: (
  root: unknown,
  name: string,
  operation: string,
) => Procedure | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L27)

### resolveJobProcedure

Resolves a generated job procedure or preserves the existing missing-procedure error.

**Signature**

```ts
declare const resolveJobProcedure: (root: unknown, name: string, operation: string) => Procedure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L12)

### throwIfAborted

Preserves the public watch-aborted failure at a native compatibility edge.

**Signature**

```ts
declare const throwIfAborted: (signal: AbortSignal) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L130)

### toAsyncIterator

Checks and transfers a native iterable or iterator without cloning its payloads.

**Signature**

```ts
declare const toAsyncIterator: (value: unknown) => AsyncIterator<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-boundary.ts#L91)

## `reconcile-support.ts`

### closeIterator

Bounds a native iterator's return without changing an existing public failure.

**Signature**

```ts
declare const closeIterator: (iterator: AsyncIterator<unknown>) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-support.ts#L8)

### newEpoch

Creates the existing local epoch used for synthesized authoritative snapshots.

**Signature**

```ts
declare const newEpoch: () => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile-support.ts#L32)

## `reconcile.ts`

### WatchRequest

**Signature**

```ts
declare const WatchRequest: WatchRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L17)

### authoritativeFrame

Reads authoritative run state, falling back to watch only for a missing get procedure.

**Signature**

```ts
declare const authoritativeFrame: (
  client: unknown,
  name: string,
  options: JobWatchOptions,
  signal: AbortSignal,
) => Promise<RunWatchFrame | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L100)

### closeIterator

**Signature**

```ts
declare const closeIterator: (iterator: AsyncIterator<unknown>) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L148)

### frameFromRun

Projects an authoritative run into the existing frozen snapshot frame.

**Signature**

```ts
declare const frameFromRun: (run: RunSnapshot) => RunWatchFrame;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L137)

### newEpoch

**Signature**

```ts
declare const newEpoch: () => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L148)

### openWatchIterator

Bounds native watch establishment and preserves the supplied lifetime signal.

**Signature**

```ts
declare const openWatchIterator: (
  client: unknown,
  name: string,
  request: WatchRequest,
  signal: AbortSignal,
  timeoutMs?: number,
) => Promise<AsyncIterator<unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L74)

### ownJobProcedure

**Signature**

```ts
declare const ownJobProcedure: (
  root: unknown,
  name: string,
  operation: string,
) => Procedure | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L11)

### readFirstWatchFrame

Reads and closes a temporary native watch used for authoritative fallback.

**Signature**

```ts
declare const readFirstWatchFrame: (
  client: unknown,
  name: string,
  request: WatchRequest,
  signal: AbortSignal,
  timeoutMs?: number,
) => Promise<RunWatchFrame | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L43)

### resolveJobProcedure

**Signature**

```ts
declare const resolveJobProcedure: (root: unknown, name: string, operation: string) => Procedure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L11)

### watchRequest

Builds the existing run observation request without widening identity authority.

**Signature**

```ts
declare const watchRequest: (options: JobWatchOptions, after?: string | undefined) => WatchRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.ts#L25)

## `reconcile.types.ts`

### Procedure (type alias)

A native job procedure callable preserving unknown request and result authority.

**Signature**

```ts
type Procedure = (...args: readonly unknown[]) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.types.ts#L4)

### WatchRequest (interface)

Run identity, retained cursor and optional expected application identity.

**Signature**

```ts
export interface WatchRequest {
  readonly runId: string;
  readonly after?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/reconcile.types.ts#L7)

## `stream-errors.ts`

### JobStreamGapError (class)

**Signature**

```ts
declare class JobStreamGapError { constructor(
    readonly expected: number,
    readonly received: number,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-errors.ts#L15)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_STREAM_GAP"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-errors.ts#L16)

### JobStreamOverflowError (class)

**Signature**

```ts
declare class JobStreamOverflowError { constructor(readonly limit: "frames" | "bytes" | "item-bytes") }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-errors.ts#L1)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_STREAM_OVERFLOW"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-errors.ts#L2)

## `stream-support.ts`

### byteLength

Measures the existing UTF-8 JSON representation used by content memory limits.

**Signature**

```ts
declare const byteLength: (value: unknown) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-support.ts#L53)

### streamIdentity

Combines every existing named-content generation boundary into its continuity key.

**Signature**

```ts
declare const streamIdentity: (frame: NamedStreamFrame) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-support.ts#L7)

### toAsyncIterator

Checks and transfers a native iterable or iterator without cloning its payloads.

**Signature**

```ts
declare const toAsyncIterator: (value: unknown) => AsyncIterator<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-support.ts#L62)

### validateFrame

Validates the existing selective named-content frame and chunk authority.

**Signature**

```ts
declare const validateFrame: (value: unknown) => NamedStreamFrame;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream-support.ts#L18)

## `stream.ts`

### JobStreamGapError

**Signature**

```ts
declare const JobStreamGapError: typeof JobStreamGapError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream.ts#L8)

### JobStreamOptions

**Signature**

```ts
declare const JobStreamOptions: JobStreamOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream.ts#L7)

### JobStreamOverflowError

**Signature**

```ts
declare const JobStreamOverflowError: typeof JobStreamOverflowError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream.ts#L8)

### watchJobStream

Opens one bounded named-content iterator with existing continuity guarantees.

**Signature**

```ts
declare const watchJobStream: <Item extends JsonValue = JsonValue>(
  client: unknown,
  job: string,
  options: JobStreamOptions,
) => Promise<AsyncIterable<NamedStreamFrame<Item>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream.ts#L22)

## `stream.types.ts`

### JobStreamOptions (interface)

Existing content bounds and request authority for one named stream.

**Signature**

```ts
export interface JobStreamOptions {
  readonly runId: string;
  readonly name: string;
  readonly after?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
  readonly signal?: AbortSignal;
  readonly readTimeoutMs?: number;
  readonly maxFrames?: number;
  readonly maxBytes?: number;
  readonly maxItemBytes?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/stream.types.ts#L3)

## `types.ts`

### JobWatchAbortedError (class)

**Signature**

```ts
declare class JobWatchAbortedError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L22)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_WATCH_ABORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L23)

### JobWatchController

**Signature**

```ts
declare const JobWatchController: JobWatchController<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L6)

### JobWatchDisposedError (class)

**Signature**

```ts
declare class JobWatchDisposedError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L9)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_WATCH_DISPOSED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L10)

### JobWatchFrame

**Signature**

```ts
declare const JobWatchFrame: JobWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L4)

### JobWatchListener

**Signature**

```ts
declare const JobWatchListener: JobWatchListener<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L5)

### JobWatchOptions

**Signature**

```ts
declare const JobWatchOptions: JobWatchOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L2)

### JobWatchReadTimeoutError (class)

**Signature**

```ts
declare class JobWatchReadTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L48)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_WATCH_READ_TIMEOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L49)

### JobWatchState

**Signature**

```ts
declare const JobWatchState: JobWatchState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L3)

### JobWatchUnavailableError (class)

**Signature**

```ts
declare class JobWatchUnavailableError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L35)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_WATCH_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L36)

### isTerminalRun

Recognizes only the existing terminal run statuses.

**Signature**

```ts
declare const isTerminalRun: (run: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/types.ts#L66)

## `watch-feed-loop.ts`

### WatchFeedLoop

**Signature**

```ts
declare const WatchFeedLoop: WatchFeedLoop<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-loop.ts#L10)

### runWatchFeed

Runs the native observation/reconciliation/retry state machine in its owner fiber.

**Signature**

```ts
declare const runWatchFeed: <Run>(
  feed: WatchFeedLoop<Run>,
  generation: number,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-loop.ts#L19)

## `watch-feed-loop.types.ts`

### WatchFeedLoop (interface)

State authority shared by native and polling observation workflows.

**Signature**

```ts
export interface WatchFeedLoop<Run> {
  readonly client: unknown;
  readonly name: string;
  readonly options: JobWatchOptions;
  readonly isActive: (generation: number) => boolean;
  readonly lastCursor: () => string | undefined;
  readonly setAbort: (controller: AbortController | undefined) => void;
  readonly setIterator: (iterator: AsyncIterator<unknown> | undefined) => void;
  readonly acceptFrame: (value: unknown) => RunWatchFrame<Run> | undefined;
  readonly emit: (event: FeedEvent<Run>) => void;
  readonly verifyTerminal: (
    frame: RunWatchFrame<Run>,
    signal: AbortSignal,
  ) => Promise<boolean | undefined>;
  readonly releaseTerminal: () => void;
  readonly resolveFirsts: () => void;
  readonly rejectFirsts: (error: unknown) => void;
  readonly failureCount: () => number;
  readonly setFailureCount: (value: number) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-loop.types.ts#L9)

## `watch-feed-observers.ts`

### WatchFeedObservers

**Signature**

```ts
declare const WatchFeedObservers: WatchFeedObservers<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.ts#L4)

### emitObservers

Publishes to each observer while isolating synchronous view failures.

**Signature**

```ts
declare const emitObservers: <Run>(
  observers: WatchFeedObservers<Run>,
  event: FeedEvent<Run>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.ts#L13)

### rejectObserverFirsts

Rejects pending first-snapshot Promises with the original failure object.

**Signature**

```ts
declare const rejectObserverFirsts: <Run>(
  observers: WatchFeedObservers<Run>,
  error: unknown,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.ts#L43)

### releaseWatchFeedTerminal

Aborts the observer request and clears leases after authoritative completion.

**Signature**

```ts
declare const releaseWatchFeedTerminal: <Run>(
  observers: Map<string, { readonly observer: FeedObserver<Run>; readonly first: Pending }>,
  abort: AbortController | undefined,
  onEmpty: () => void,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.ts#L58)

### resolveObserverFirsts

Settles each pending first-snapshot Promise after authoritative evidence.

**Signature**

```ts
declare const resolveObserverFirsts: <Run>(observers: WatchFeedObservers<Run>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.ts#L32)

## `watch-feed-observers.types.ts`

### WatchFeedObservers (type alias)

Each feed lease's callback and shared first-snapshot settlement authority.

**Signature**

```ts
type WatchFeedObservers<Run> = ReadonlyMap<
  string,
  { readonly observer: FeedObserver<Run>; readonly first: Pending }
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-observers.types.ts#L8)

## `watch-feed-polling.ts`

### runPollingFeed

Observes authoritative snapshots with the injected Clock and unchanged retry policy.

**Signature**

```ts
declare const runPollingFeed: <Run>(
  feed: WatchFeedLoop<Run>,
  generation: number,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-polling.ts#L16)

## `watch-feed-recovery.ts`

### recoverWatchFeed

Applies the bounded, idempotent observation retry policy without retrying server work.

**Signature**

```ts
declare const recoverWatchFeed: <Run>(
  feed: WatchFeedLoop<Run>,
  generation: number,
  error: unknown,
  controller: AbortController,
) => Effect.Effect<void, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-recovery.ts#L13)

## `watch-feed-refetch.ts`

### refetchSharedWatchFeed

Owns a temporary authoritative read while respecting borrowed cancellation.

**Signature**

```ts
declare const refetchSharedWatchFeed: <Run>(
  client: unknown,
  name: string,
  options: JobWatchOptions,
  lastCursor: string | undefined,
  signal?: AbortSignal,
) => Promise<RunWatchFrame<Run> | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-refetch.ts#L16)

## `watch-feed-state.ts`

### WatchFeedState

**Signature**

```ts
declare const WatchFeedState: WatchFeedState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-state.ts#L4)

### acceptWatchFrame

Applies epoch changes and duplicate suppression without losing retained cursor authority.

**Signature**

```ts
declare const acceptWatchFrame: <Run>(
  state: WatchFeedState<Run>,
  value: unknown,
) => { readonly state: WatchFeedState<Run>; readonly frame: RunWatchFrame<Run> | undefined };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-state.ts#L22)

### emptyWatchFeedState

Creates the initial empty observation cache with no native resources.

**Signature**

```ts
declare const emptyWatchFeedState: <Run>() => WatchFeedState<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-state.ts#L11)

## `watch-feed-state.types.ts`

### WatchFeedState (interface)

Accepted frame, epoch, sequence and cursor retained by one shared observation feed.

**Signature**

```ts
export interface WatchFeedState<Run> {
  readonly lastFrame: RunWatchFrame<Run> | undefined;
  readonly lastCursor: string | undefined;
  readonly lastSequence: number;
  readonly nativeEpoch: string | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-state.types.ts#L7)

## `watch-feed-support.ts`

### Pending

**Signature**

```ts
declare const Pending: Pending;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L4)

### backoff

Calculates the existing bounded observation reconnect delay.

**Signature**

```ts
declare const backoff: (attempt: number, options: JobWatchOptions) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L26)

### closeEmptyIterator

Provides the existing already-completed native iterator.

**Signature**

```ts
declare const closeEmptyIterator: () => AsyncIterator<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L98)

### deferred

Creates one settled-once first-snapshot Promise with explicit resolution authority.

**Signature**

```ts
declare const deferred: () => Pending;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L10)

### isFrame

Checks the existing selective observation-frame shape.

**Signature**

```ts
declare const isFrame: (value: unknown) => value is RunWatchFrame;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L107)

### isUnauthorized

Recognizes existing nested authorization denial envelopes.

**Signature**

```ts
declare const isUnauthorized: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L134)

### offline

Waits for browser online recovery while owning its listener and borrowed signal.

**Signature**

```ts
declare const offline: (signal: AbortSignal) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L61)

### resetFrame

Marks reconnect continuity without fabricating cursor or terminal evidence.

**Signature**

```ts
declare const resetFrame: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L116)

### wait

Owns a native delay and removes its timer and borrowed abort listener on settlement.

**Signature**

```ts
declare const wait: (milliseconds: number, signal: AbortSignal) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L39)

### withAfter

Adds a retained cursor only when one exists.

**Signature**

```ts
declare const withAfter: (options: JobWatchOptions, after: string | undefined) => JobWatchOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.ts#L90)

## `watch-feed-support.types.ts`

Settled-once first-snapshot Promise with explicit resolve and reject functions.

### Pending (type alias)

Settled-once first-snapshot Promise with explicit resolve and reject functions.

**Signature**

```ts
type Pending = {
  readonly promise: Promise<void>;
  readonly resolve: () => void;
  readonly reject: (error: unknown) => void;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-support.types.ts#L2)

## `watch-feed-teardown.ts`

Joins native feed completion within the public teardown deadline.

### joinFeedTeardown

Joins native feed completion within the public teardown deadline.

**Signature**

```ts
declare const joinFeedTeardown: (
  interrupted: Promise<void>,
  running: Promise<void>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-teardown.ts#L9)

## `watch-feed-terminal.ts`

### verifyWatchTerminal

Confirms terminal evidence and publishes the authoritative frame.

**Signature**

```ts
declare const verifyWatchTerminal: <Run>(
  client: unknown,
  name: string,
  options: JobWatchOptions,
  frame: RunWatchFrame<Run>,
  signal: AbortSignal,
  accept: (value: unknown) => RunWatchFrame<Run> | undefined,
  emit: (event: FeedEvent<Run>) => void,
) => Promise<boolean | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-terminal.ts#L20)

## `watch-feed-types.ts`

### "./watch-feed.types.js" (namespace export)

Re-exports all named exports from the "./watch-feed.types.js" module.

**Signature**

```ts
export * from "./watch-feed.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed-types.ts#L2)

## `watch-feed.ts`

### FeedEvent

**Signature**

```ts
declare const FeedEvent: FeedEvent<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L17)

### FeedStatus

**Signature**

```ts
declare const FeedStatus: FeedStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L17)

### SharedWatchFeed (class)

Scoped physical native observation shared by independently retired view leases.

**Signature**

```ts
declare class SharedWatchFeed<Run> { constructor(
    private readonly client: unknown,
    private readonly name: string,
    private readonly options: JobWatchOptions,
    private readonly onEmpty: () => void = () => undefined,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L23)

### addLease (method)

Registers one observer and its first-snapshot Promise without duplicating shared native work.

**Signature**

```ts
declare const addLease: (id: string, observer: FeedObserver<Run>) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L59)

### removeLease (method)

Releases one observer and joins bounded native teardown only for the final observer.

**Signature**

```ts
declare const removeLease: (id: string, error?: unknown) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L78)

### refetch (method)

Reads authoritative evidence without changing observation lease ownership.

**Signature**

```ts
declare const refetch: (signal?: AbortSignal) => Promise<RunWatchFrame<Run> | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L115)

### close (method)

Closes the service owner after the sharing registry removes its final entry.

**Signature**

```ts
declare const close: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L134)

### ensureRunning (method)

Starts one supervised observation worker only when live observers require it.

**Signature**

```ts
declare const ensureRunning: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L150)

### loop (method)

Projects the facade's observer and epoch authority into the owned observation workflow.

**Signature**

```ts
declare const loop: (generation: number) => {
  client: unknown;
  name: string;
  options: JobWatchOptions;
  isActive: (generation: number) => boolean;
  lastCursor: () => string | undefined;
  setAbort: (controller: AbortController | undefined) => void;
  setIterator: () => void;
  acceptFrame: (value: unknown) => RunWatchFrame<Run> | undefined;
  emit: (event: FeedEvent<Run>) => void;
  verifyTerminal: (frame: RunWatchFrame<Run>, signal: AbortSignal) => Promise<boolean | undefined>;
  releaseTerminal: () => void;
  resolveFirsts: () => void;
  rejectFirsts: (error: unknown) => void;
  failureCount: () => number;
  setFailureCount: (value: number) => void;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L176)

### releaseTerminal (method)

Retires terminal observer authority and invalidates the shared registry entry.

**Signature**

```ts
declare const releaseTerminal: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L217)

### acceptFrame (method)

Applies epoch, sequence and cursor duplicate rules to the cached observer snapshot.

**Signature**

```ts
declare const acceptFrame: (value: unknown) => RunWatchFrame<Run> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L229)

### emit (method)

Publishes an observation without allowing one callback to fail another observer.

**Signature**

```ts
declare const emit: (event: FeedEvent<Run>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.ts#L240)

## `watch-feed.types.ts`

### FeedEvent (type alias)

Canonical native frame or physical observation lifecycle publication.

**Signature**

```ts
type FeedEvent<Run> =
  | { readonly kind: "frame"; readonly frame: RunWatchFrame<Run> }
  | { readonly kind: "status"; readonly status: FeedStatus; readonly error?: unknown };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.types.ts#L7)

### FeedObserver (type alias)

Synchronous observer isolated from another view and the native worker lifetime.

**Signature**

```ts
type FeedObserver<Run> = (event: FeedEvent<Run>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.types.ts#L19)

### FeedStatus (type alias)

Physical observation states projected into each passive external-store view.

**Signature**

```ts
type FeedStatus =
  "connecting" | "connected" | "reconnecting" | "completed" | "unauthorized" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-feed.types.ts#L12)

## `watch-key.ts`

### WatchFeedKey (class)

Complete immutable sharing identity with borrowed transport/configuration.

**Signature**

```ts
declare class WatchFeedKey { constructor(
    readonly client: unknown,
    readonly name: string,
    readonly options: JobWatchOptions,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-key.ts#L7)

### [Equal.symbol] (method)

**Signature**

```ts
declare const [Equal.symbol]: (that: Equal.Equal) => boolean
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-key.ts#L24)

### [Hash.symbol] (method)

**Signature**

```ts
declare const [Hash.symbol]: () => number
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-key.ts#L28)

### value (property)

**Signature**

```ts
readonly value: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch-key.ts#L8)

## `watch.ts`

### FeedEvent

**Signature**

```ts
declare const FeedEvent: FeedEvent<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.ts#L5)

### FeedStatus

**Signature**

```ts
declare const FeedStatus: FeedStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.ts#L5)

### JobFeedRegistryDefault

Borrowed browser registry; each controller closes its explicit RcMap borrow.

**Signature**

```ts
declare const JobFeedRegistryDefault: Layer.Layer<JobFeedRegistry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.ts#L14)

### SharedWatchFeed

**Signature**

```ts
declare const SharedWatchFeed: typeof SharedWatchFeed;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.ts#L4)

### jobFeedRegistry

Once-acquired reference-counted registry used by controller operations.

**Signature**

```ts
declare const jobFeedRegistry: JobFeedRegistryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.ts#L12)

## `watch.types.ts`

### JobWatchController (interface)

Reusable public watch owner with synchronous state and explicit Promise cleanup.

**Signature**

```ts
export interface JobWatchController<Run = RunSnapshot> {
  getSnapshot(): JobWatchState<Run>;
  subscribe(listener: JobWatchListener<Run>): () => void;
  connect(): Promise<void>;
  disconnect(): Promise<void>;
  dispose(): Promise<void>;
  refetch(): Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.types.ts#L59)

### JobWatchFrame (type alias)

Declared job run observation frame.

**Signature**

```ts
type JobWatchFrame<Run = RunSnapshot> = RunWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.types.ts#L47)

### JobWatchListener (type alias)

Borrowed synchronous observer of frozen job watch state.

**Signature**

```ts
type JobWatchListener<Run = RunSnapshot> = (state: JobWatchState<Run>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.types.ts#L53)

### JobWatchOptions (interface)

Complete watch sharing authority, cursor/projection fields and retry/read bounds.

**Signature**

```ts
export interface JobWatchOptions {
  readonly runId: string;
  readonly jobId?: string;
  readonly after?: string;
  readonly expectedIdentity?: ExpectedClientIdentity;
  readonly identityKey?: string | null;
  readonly applicationId?: string;
  readonly environment?: string;
  readonly grantScope?: string;
  readonly projection?: string;
  readonly schemaVersion?: string;
  readonly protocolVersion?: number;
  readonly source?: "native" | "polling";
  readonly pollIntervalMs?: number;
  readonly maxReconnectAttempts?: number;
  readonly reconnectMinDelayMs?: number;
  readonly reconnectMaxDelayMs?: number;
  readonly readTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.types.ts#L5)

### JobWatchState (interface)

Frozen external-store snapshot of connection, run and continuity evidence.

**Signature**

```ts
export interface JobWatchState<Run = RunSnapshot> {
  readonly run?: Run;
  readonly connection: RunConnection;
  readonly isStale: boolean;
  readonly lastObservedAt?: string;
  readonly connectionError?: unknown;
  readonly continuity?: "state" | "history";
  readonly resetReason?: "reconnected" | "cursor-expired" | "history-unavailable" | "overflow";
  readonly source?: "native" | "polling";
  readonly epoch?: string;
  readonly sequence?: number;
  readonly cursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/jobs/watch.types.ts#L29)

## `native-stream.ts`

### nativeCall

Suspends native work and passes the owning fiber's cancellation signal.

**Signature**

```ts
declare const nativeCall: <A>(
  execute: (signal: AbortSignal) => PromiseLike<A>,
) => Effect.Effect<A, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/native-stream.ts#L10)

### nativeStream

Owns an iterator and its request through all pulls, EOF and early return.

**Signature**

```ts
declare const nativeStream: <A>(
  operation: string,
  open: (signal: AbortSignal) => PromiseLike<AsyncIterator<A>>,
  caller?: AbortSignal,
  opened?: Effect.Effect<void>,
  read?: (iterator: AsyncIterator<A>, signal: AbortSignal) => PromiseLike<IteratorResult<A>>,
) => Stream.Stream<A, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/native-stream.ts#L28)

## `agent-continuation.ts`

### prepareAgentContinuation

Binds a continuation to the authoritative waiting revision for its thread.

**Signature**

```ts
declare const prepareAgentContinuation: (
  client: unknown,
  agentId: string,
  threadId: string,
  payload: unknown,
  current?: ThreadSnapshot,
) => Promise<PreparedContinuation>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-continuation.ts#L16)

### requiredThreadId

Validates the existing caller-supplied thread boundary.

**Throws**

Error when the existing thread validation fails.

**Signature**

```ts
declare const requiredThreadId: (options: AgentThreadOptions | undefined) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-continuation.ts#L35)

## `agent-contract-selection.ts`

### "./agent-contract-selection.types.js" (namespace export)

Re-exports all named exports from the "./agent-contract-selection.types.js" module.

**Signature**

```ts
export * from "./agent-contract-selection.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.ts#L3)

## `agent-contract-selection.types.ts`

### AgentChat (type alias)

Infers whether the declared agent accepts chat send.

**Signature**

```ts
type AgentChat<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly chat: infer Value } ? Value : false;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L35)

### AgentControls (type alias)

Infers the declared agent control capabilities.

**Signature**

```ts
type AgentControls<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly controls: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L28)

### AgentCustomEvent (type alias)

Infers the declared custom observation event payload.

**Signature**

```ts
type AgentCustomEvent<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly customEvent: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L63)

### AgentInput (type alias)

Infers the declared agent run input.

**Signature**

```ts
type AgentInput<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly input: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L14)

### AgentOutput (type alias)

Infers the declared terminal agent output.

**Signature**

```ts
type AgentOutput<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly output: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L21)

### AgentPublicState (type alias)

Infers the public values projected into observed thread state.

**Signature**

```ts
type AgentPublicState<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly publicState: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L56)

### AgentResume (type alias)

Infers the declared continuation input.

**Signature**

```ts
type AgentResume<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly resume: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L42)

### AgentScope (type alias)

Infers declared nested execution scope identities.

**Signature**

```ts
type AgentScope<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly scope: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L70)

### AgentTool (type alias)

Infers the declared tool input and output contract.

**Signature**

```ts
type AgentTool<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly tool: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L49)

### AgentWaiting (type alias)

Infers supported waiting request payloads.

**Signature**

```ts
type AgentWaiting<Name extends AgentSelector> =
  AgentFor<Name> extends { readonly waiting: infer Value } ? Value : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-contract-selection.types.ts#L77)

## `agent-execution-observation.ts`

### AgentExecutionProjection

**Signature**

```ts
declare const AgentExecutionProjection: AgentExecutionProjection<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L8)

### clientEventProjection

Projects canonical client events into the existing browser execution event shape.

**Signature**

```ts
declare const clientEventProjection: (event: AgentClientEvent) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L138)

### executionProjection

Projects authoritative execution state into the existing browser agent shape.

**Signature**

```ts
declare const executionProjection: <Output>(
  current: AgentExecutionProjection<Output>,
  event: AgentExecutionEvent,
) => AgentExecutionProjection<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L17)

### snapshotProjection

Projects a thread snapshot through its canonical executions.

**Signature**

```ts
declare const snapshotProjection: <Output>(
  snapshot: ThreadSnapshot,
) => AgentExecutionProjection<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L56)

### terminalProjection

Projects a native terminal envelope without fabricating missing output.

**Signature**

```ts
declare const terminalProjection: <Output>(value: unknown) => {
  output?: Output;
  status: "failed" | "cancelled" | "succeeded";
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L107)

### updateSnapshotProjection

Updates the browser snapshot projection without widening authority.

**Signature**

```ts
declare const updateSnapshotProjection: <Snapshot extends ThreadSnapshot>(
  snapshot: Snapshot,
  projection: AgentExecutionProjection,
  event: AgentClientEvent,
) => Snapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.ts#L74)

## `agent-execution-observation.types.ts`

### AgentExecutionProjection (interface)

Browser agent lifecycle and content projected from authoritative execution state.

**Signature**

```ts
export interface AgentExecutionProjection<Output = unknown> {
  readonly values?: unknown;
  readonly output?: Output;
  readonly executions: readonly AgentExecutionSnapshot[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-execution-observation.types.ts#L7)

## `agent-hook-contract.ts`

### "./agent-hook-contract.types.js" (namespace export)

Re-exports all named exports from the "./agent-hook-contract.types.js" module.

**Signature**

```ts
export * from "./agent-hook-contract.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.ts#L3)

## `agent-hook-contract.types.ts`

### AgentNestedExecution (type alias)

Projects nested execution identity and public values from the declared scope.

**Signature**

```ts
type AgentNestedExecution<Scope, PublicState> = Omit<
  AgentExecutionSnapshot,
  "agent" | "node" | "values"
> & {
  readonly agent?: ScopeId<Scope, "agent" | "subagent">;
  readonly node?: ScopeId<Scope, "node">;
  readonly values?: PublicState;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L123)

### AgentObservedEvent (type alias)

Canonical observed events with declared tool and custom payload inference.

**Signature**

```ts
type AgentObservedEvent<Tool, CustomEvent> =
  | Exclude<AgentClientEvent, AgentToolEvent>
  | TypedToolEvent<AgentToolEvent, Tool>
  | ObservedCustomEvent<CustomEvent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L84)

### AgentToolCall (interface)

Stable browser projection of canonical tool identity, state, input and output.

**Signature**

```ts
export interface AgentToolCall {
  readonly toolCallId: string;
  readonly messageId: string;
  readonly partId: string;
  readonly runId?: string;
  readonly toolId: string;
  readonly state: ToolPartState;
  readonly inputText?: string;
  readonly input?: unknown;
  readonly output?: unknown;
  readonly createdAt: string;
  readonly updatedAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L14)

### TypedAgentToolCall (type alias)

Specializes observed tool identity and payloads when a tool contract is declared.

**Signature**

```ts
type TypedAgentToolCall<Tool> = Tool extends ToolContract
  ? Omit<AgentToolCall, "toolId" | "input" | "output"> & {
      readonly toolId: Tool["id"];
      readonly input?: Tool["input"];
      readonly output?: Tool["output"];
    }
  : AgentToolCall;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L42)

### TypedThreadSnapshot (type alias)

Authoritative thread snapshot with declaration-derived output, scope, values and waiting requests.

**Signature**

```ts
type TypedThreadSnapshot<Output, PublicState, Scope, Waiting> = Omit<
  ThreadSnapshot,
  "executions" | "output" | "values" | "waiting"
> & {
  readonly executions: readonly AgentNestedExecution<Scope, PublicState>[];
  readonly output?: Output;
  readonly values?: PublicState;
  readonly waiting?: [Waiting] extends [never] ? never : TypedWaitingState<Waiting>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L139)

### TypedWaitingState (type alias)

Projects waiting requests using the declared supported waiting union.

**Signature**

```ts
type TypedWaitingState<Waiting> = Omit<AgentWaitingState, "requests"> & {
  readonly requests: readonly (Waiting extends AgentWaitingRequest ? Waiting : never)[];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-contract.types.ts#L93)

## `agent-hook-types.ts`

### "./agent-hook-types.types.js" (namespace export)

Re-exports all named exports from the "./agent-hook-types.types.js" module.

**Signature**

```ts
export * from "./agent-hook-types.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.ts#L3)

## `agent-hook-types.types.ts`

### AgentBase (interface)

Observed durable thread state with declaration-derived payload and control contracts.

**Signature**

```ts
export interface AgentBase<
  Output,
  Tool = ClientAgentDynamic,
  PublicState = unknown,
  CustomEvent = never,
  Scope = ClientAgentDynamic,
  Waiting = AgentWaitingRequest,
> extends AgentContent<Tool> {
  readonly status:
    | "idle"
    | "loading"
    | "running"
    | "waiting"
    | "approval-interrupted"
    | "stopping"
    | "worker-interrupted"
    | "succeeded"
    | "failed"
    | "cancelled"
    | "error";
  readonly threadId?: string;
  readonly events: readonly AgentObservedEvent<Tool, CustomEvent>[];
  readonly values?: PublicState;
  readonly executions: readonly AgentNestedExecution<Scope, PublicState>[];
  readonly output?: Output;
  readonly snapshot?: ThreadSnapshot;
  readonly waiting?: ([Waiting] extends [never] ? never : TypedWaitingState<Waiting>) | undefined;
  readonly error?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L116)

### AgentContent (interface)

Indexed browser content supporting ordered timeline and direct identity lookup.

**Signature**

```ts
export interface AgentContent<Tool = ClientAgentDynamic> {
  readonly timeline: readonly AgentTimelineItem<Tool>[];
  readonly timelineById: ReadonlyMap<string, AgentTimelineItem<Tool>>;
  readonly messages: readonly AgentMessage[];
  readonly messagesById: ReadonlyMap<string, AgentMessage>;
  readonly toolCalls: readonly TypedAgentToolCall<Tool>[];
  readonly toolCallsById: ReadonlyMap<string, TypedAgentToolCall<Tool>>;
  readonly progress: readonly AgentProgress[];
  readonly progressById: ReadonlyMap<string, AgentProgress>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L96)

### AgentMessage (interface)

Browser projection of canonical user or assistant text message parts.

**Signature**

```ts
export interface AgentMessage {
  readonly messageId: string;
  readonly runId?: string;
  readonly role: "user" | "assistant";
  readonly parts: readonly Extract<BrowserMessagePart, { readonly kind: "text" }>[];
  readonly createdAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L58)

### AgentNestedExecution

**Signature**

```ts
declare const AgentNestedExecution: AgentNestedExecution<Scope, PublicState>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L25)

### AgentOutput

**Signature**

```ts
declare const AgentOutput: AgentOutput<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L23)

### AgentProgress (type alias)

Browser progress projection with its canonical run or tool scope.

**Signature**

```ts
type AgentProgress = AgentProgressBase & import("@relkit/contracts").AgentProgressScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L81)

### AgentResumeOptions (interface)

Continuation options requiring explicit resume mode.

**Signature**

```ts
export interface AgentResumeOptions extends AgentThreadOptions {
  readonly resume: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L44)

### AgentRunOptions (interface)

Fresh run options excluding continuation mode.

**Signature**

```ts
export interface AgentRunOptions extends AgentThreadOptions {
  readonly resume?: false;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L37)

### AgentStopOptions (interface)

Durable thread stop policy preserving graceful and immediate alternatives.

**Signature**

```ts
export interface AgentStopOptions extends AgentThreadOptions {
  readonly mode?: "graceful" | "immediate";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L51)

### AgentThreadOptions (interface)

Caller-owned durable thread identity used by observation and controls.

**Signature**

```ts
export interface AgentThreadOptions {
  readonly threadId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L30)

### AgentTimelineItem (type alias)

Ordered browser timeline member retaining stable message, tool and progress identity.

**Signature**

```ts
type AgentTimelineItem<Tool = ClientAgentDynamic> =
  | { readonly key: string; readonly kind: "message"; readonly message: AgentMessage }
  | { readonly key: string; readonly kind: "tool"; readonly toolCall: TypedAgentToolCall<Tool> }
  | { readonly key: string; readonly kind: "progress"; readonly progress: AgentProgress };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L87)

### AgentToolCall

**Signature**

```ts
declare const AgentToolCall: AgentToolCall;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L25)

### UseAgentResult (type alias)

Public agent hook state and declaration-derived execution, observation and controls.

**Signature**

```ts
type UseAgentResult<Name extends AgentSelector> = Omit<ContractBase<Name>, "snapshot"> & {
  readonly snapshot?: TypedThreadSnapshot<
    AgentOutput<Name>,
    AgentPublicState<Name>,
    AgentScope<Name>,
    AgentWaiting<Name>
  >;
} & Execution<Name> &
  Observation &
  Controls<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook-types.types.ts#L214)

## `agent-hook.ts`

### "./agent-hook-types.js" (namespace export)

Re-exports all named exports from the "./agent-hook-types.js" module.

**Signature**

```ts
export * from "./agent-hook-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook.ts#L19)

### useAgent

Adapts the agent service into React state while keeping accepted work independent of view cleanup.

**Signature**

```ts
declare const useAgent: <Name extends AgentSelector>(name: Name) => UseAgentResult<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook.ts#L27)

## `agent-hook.types.ts`

### InvocationOptions (type alias)

Explicit caller thread authority for an agent submission.

**Signature**

```ts
type InvocationOptions = AgentThreadOptions & { readonly resume?: boolean };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook.types.ts#L7)

### ObservationRequest (type alias)

The thread selected for the view's current agent observation.

**Signature**

```ts
type ObservationRequest = { readonly threadId: string; readonly revision: number };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-hook.types.ts#L4)

## `agent-methods.ts`

### agentMethods

Projects declared agent methods over the view's borrowed invocation and observation adapters.

**Signature**

```ts
declare const agentMethods: <Output>(
  state: AgentBase<Output>,
  invoke: Invoke,
  observe: (options: AgentThreadOptions) => Promise<void>,
) => {
  observe: (options: AgentThreadOptions) => Promise<void>;
  run: (input: unknown, options: AgentThreadOptions) => Promise<void>;
  send: (message: string, options: AgentThreadOptions) => Promise<void>;
  steer: (message: string, options: AgentThreadOptions) => Promise<void>;
  followUp: (message: string, options: AgentThreadOptions) => Promise<void>;
  stop: (options: AgentStopOptions) => Promise<void>;
  approve: (approvalId: string, options: AgentThreadOptions) => Promise<void>;
  deny: (approvalId: string, options: AgentThreadOptions) => Promise<void>;
  status:
    | "idle"
    | "loading"
    | "running"
    | "waiting"
    | "approval-interrupted"
    | "stopping"
    | "worker-interrupted"
    | "succeeded"
    | "failed"
    | "cancelled"
    | "error";
  threadId?: string;
  events: ReadonlyArray<AgentObservedEvent<ClientAgentDynamic, never>>;
  values?: unknown;
  executions: ReadonlyArray<AgentNestedExecution<ClientAgentDynamic, unknown>>;
  output?: Output;
  snapshot?: ThreadSnapshot;
  waiting?: TypedWaitingState<AgentWaitingRequest> | undefined;
  error?: unknown;
  timeline: ReadonlyArray<AgentTimelineItem<ClientAgentDynamic>>;
  timelineById: ReadonlyMap<string, AgentTimelineItem<ClientAgentDynamic>>;
  messages: readonly AgentMessage[];
  messagesById: ReadonlyMap<string, AgentMessage>;
  toolCalls: ReadonlyArray<AgentToolCall>;
  toolCallsById: ReadonlyMap<string, AgentToolCall>;
  progress: readonly AgentProgress[];
  progressById: ReadonlyMap<string, AgentProgress>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-methods.ts#L12)

## `agent-methods.types.ts`

### Invoke (type alias)

Borrowed agent submission callback preserving its declared receipt Promise.

**Signature**

```ts
type Invoke = (
  kind: string,
  payload: unknown,
  options: AgentThreadOptions & { readonly resume?: boolean },
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-methods.types.ts#L4)

## `agent-observation-effect.ts`

### observeAgent

Restores the authoritative snapshot and owns every subsequent observation attempt.

**Signature**

```ts
declare const observeAgent: <Output>(
  client: unknown,
  streamClient: unknown,
  agentId: string,
  threadId: string,
  identity: AgentIdentity | undefined,
  signal: AbortSignal,
  update: AgentUpdate<Output>,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation-effect.ts#L27)

## `agent-observation-index.ts`

### upsertMessage

Replaces or appends one message while preserving its timeline position.

**Signature**

```ts
declare const upsertMessage: (content: AgentContent, value: AgentMessage) => AgentContent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation-index.ts#L15)

### upsertProgress

Replaces or appends one scoped progress item while preserving its timeline position.

**Signature**

```ts
declare const upsertProgress: (content: AgentContent, value: AgentProgress) => AgentContent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation-index.ts#L55)

### upsertTool

Replaces or appends one tool call while preserving its timeline position.

**Signature**

```ts
declare const upsertTool: (content: AgentContent, value: AgentToolCall) => AgentContent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation-index.ts#L35)

## `agent-observation.ts`

### agentContentFromMessages

Projects authoritative messages into indexed browser content.

**Signature**

```ts
declare const agentContentFromMessages: (messages: readonly BrowserMessage[]) => AgentContent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation.ts#L45)

### applyAgentEvent

Applies one canonical agent observation while preserving lifecycle and journal authority.

**Signature**

```ts
declare const applyAgentEvent: <Output>(
  current: AgentBase<Output>,
  event: AgentClientEvent,
) => AgentBase<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation.ts#L56)

### emptyAgentContent

Creates empty indexed browser agent content without native resources.

**Signature**

```ts
declare const emptyAgentContent: () => AgentContent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observation.ts#L27)

## `agent-observer.ts`

### restoreAndObserve

Restores and observes one caller-owned thread until terminal evidence or cleanup.

**Signature**

```ts
declare const restoreAndObserve: <Output>(
  client: unknown,
  streamClient: unknown,
  agentId: string,
  threadId: string,
  identity: AgentIdentity | undefined,
  signal: AbortSignal,
  update: AgentUpdate<Output>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-observer.ts#L18)

## `agent-operations.service.ts`

### AgentOperations (class)

Agent observation, continuation and accepted-work ownership contract.

**Signature**

```ts
declare class AgentOperations
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.service.ts#L17)

### AgentOperationsLive

Provides agent operations using the existing pending receipt authority.

**Example**

```ts
import { Layer } from "effect";
import { AgentOperationsLive } from "./agent-operations.service.js";
import { pendingOperationsLayer } from "./pending.service.js";
export const live = AgentOperationsLive.pipe(Layer.provide(pendingOperationsLayer()));
```

**Signature**

```ts
declare const AgentOperationsLive: Layer.Layer<AgentOperations, never, PendingOperations>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.service.ts#L32)

### isAcceptedAgentRun

Retains the existing weak receipt predicate used by agent dispatch.

**Signature**

```ts
declare const isAcceptedAgentRun: (value: unknown) => value is { readonly threadId: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.service.ts#L203)

## `agent-operations.types.ts`

### AgentIdentity (interface)

Complete identity authority supplied to an observation or submission.

**Signature**

```ts
export interface AgentIdentity {
  readonly identityScope: string;
  readonly sessionEpoch: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L13)

### AgentObservationCursor (interface)

Checkpoint state belongs to one observation fiber.

**Signature**

```ts
export interface AgentObservationCursor {
  checkpoint: JournalCheckpoint;
  runId: string | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L40)

### AgentOperationsService (interface)

Cohesive agent recovery and accepted-work contract, independent of React.

**Signature**

```ts
export interface AgentOperationsService {
  /** Observes durable thread snapshots and ordered frames until view retirement.
   * @typeParam Output - Application-declared terminal output payload.
   * @param client - Borrowed finite procedure transport.
   * @param streamClient - Borrowed native observation transport.
   * @param agentId - Declared agent key.
   * @param threadId - Caller-owned durable thread identity.
   * @param identity - Complete authorization and session boundary.
   * @param signal - View lifetime propagated to native observations.
   * @param update - Isolated external-store publication.
   * @returns A lazy scoped recovery workflow preserving native errors. */
  readonly observe: <Output>(
    client: unknown,
    streamClient: unknown,
    agentId: string,
    threadId: string,
    identity: AgentIdentity | undefined,
    signal: AbortSignal,
    update: AgentUpdate<Output>,
  ) => Effect.Effect<void, unknown>;
  /** Binds continuation input to an authoritative waiting revision.
   * @param client - Borrowed finite procedure transport.
   * @param agentId - Declared agent key.
   * @param threadId - Caller-owned durable thread identity.
   * @param payload - Original transmitted continuation payload.
   * @param current - Matching authoritative snapshot when already available.
   * @returns A lazy observed revision and digest input or original native failure. */
  readonly continuation: (
    client: unknown,
    agentId: string,
    threadId: string,
    payload: unknown,
    current?: ThreadSnapshot,
  ) => Effect.Effect<PreparedContinuation, unknown>;
  /** Reconciles stored receipts with durable thread identity.
   * @param client - Borrowed receipt lookup transport.
   * @param scopeKey - Complete pending isolation scope.
   * @param agentId - Declared agent key.
   * @param signal - View lifetime for receipt observations.
   * @returns A lazy observed restored thread identity or original native failure. */
  readonly reconcile: (
    client: unknown,
    scopeKey: string,
    agentId: string,
    signal: AbortSignal,
  ) => Effect.Effect<string | undefined, unknown>;
  /** Dispatches accepted agent work independently of observation cancellation.
   * @param request - Complete identity, input, continuation and pending authority.
   * @returns A lazy observed original receipt or original native rejection. */
  readonly submit: (request: AgentSubmission) => Effect.Effect<unknown, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L45)

### AgentReceiptLookup (type alias)

Receipt lookup preserves the existing finite recovery alternatives.

**Signature**

```ts
type AgentReceiptLookup =
  | { readonly status: "found"; readonly receipt: { readonly threadId: string } }
  | { readonly status: "not-found" | "expired" | "state-lost" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L23)

### AgentSubmission (interface)

Request state for a single accepted-work submission.

**Signature**

```ts
export interface AgentSubmission {
  readonly client: unknown;
  readonly scopeKey: string;
  readonly agentId: string;
  readonly threadId: string;
  readonly identity: AgentIdentity | undefined;
  readonly kind: string;
  readonly payload: unknown;
  readonly resume?: boolean;
  readonly snapshot?: ThreadSnapshot;
  readonly activeRunId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L27)

### AgentUpdate (type alias)

State publication remains borrowed from the calling view.

**Signature**

```ts
type AgentUpdate<Output> = (
  value: AgentBase<Output> | ((current: AgentBase<Output>) => AgentBase<Output>),
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L9)

### PreparedContinuation (interface)

A continuation digest binds input to the authoritative waiting revision.

**Signature**

```ts
export interface PreparedContinuation {
  readonly waitingRevision: string;
  readonly digestValue: { readonly payload: unknown; readonly waitingRevision: string };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-operations.types.ts#L18)

## `agent-reconcile.ts`

### reconcileAgentRun

Reconciles recorded submissions using authoritative receipt lookup.

**Signature**

```ts
declare const reconcileAgentRun: (
  client: unknown,
  scopeKey: string,
  agentId: string,
  signal: AbortSignal,
) => Promise<string | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-reconcile.ts#L12)

## `agent-runtime.ts`

### agentOperations

Once-acquired service used by synchronous constructors and Promise adapters.

**Signature**

```ts
declare const agentOperations: AgentOperationsService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-runtime.ts#L11)

### agentRuntime

**Signature**

```ts
declare const agentRuntime: ManagedRuntime.ManagedRuntime<AgentOperations, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-runtime.ts#L7)

## `agent-snapshot-observation.ts`

### applyAgentSnapshot

Replaces authoritative agent state and reconciles its browser projection.

**Signature**

```ts
declare const applyAgentSnapshot: <Output>(
  current: AgentBase<Output>,
  snapshot: ThreadSnapshot,
) => AgentBase<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-snapshot-observation.ts#L13)

## `agent-sse-client.ts`

### createAgentSseClient

Creates the native SSE edge used by the agent observation service.

**Signature**

```ts
declare const createAgentSseClient: (options: AgentSseClientOptions, fallback?: object) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-sse-client.ts#L13)

## `agent-sse-stream.ts`

### agentSseObservations

Transfers a native response reader into a scoped Effect parser and iterator edge.

**Signature**

```ts
declare const agentSseObservations: (
  body: ReadableStream<Uint8Array>,
  controller: AbortController,
  borrowed?: AbortSignal,
) => AsyncIterable<AgentObservation>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-sse-stream.ts#L12)

## `agent-sse.types.ts`

### AgentSseClientOptions (interface)

Native HTTP configuration for the browser-safe agent SSE edge.

**Signature**

```ts
export interface AgentSseClientOptions {
  readonly baseUrl: string;
  readonly credentials: NonNullable<RequestInit["credentials"]>;
  readonly headers?: ClientHeaders;
  readonly fetch: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-sse.types.ts#L5)

### AgentSseObserveInput (interface)

Existing selective observation input authority.

**Signature**

```ts
export interface AgentSseObserveInput {
  readonly agentId: string;
  readonly threadId: string;
  readonly runId?: string;
  readonly after: JournalCheckpoint;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/agent-sse.types.ts#L12)

## `context-support.ts`

### browserOrigin

Reads the current browser backend origin or the existing local fallback.

**Signature**

```ts
declare const browserOrigin: () => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L11)

### compiledFingerprint

Reads the existing browser or Next public fingerprint binding.

**Signature**

```ts
declare const compiledFingerprint: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L31)

### finiteFetcher

Creates the finite native fetch edge with combined caller and deadline signals.

**Signature**

```ts
declare const finiteFetcher: (timeoutMs: number) => typeof fetch;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L105)

### identityHeaders

Attaches existing identity, jobs protocol and CSRF authority to current headers.

**Signature**

```ts
declare const identityHeaders: (
  value: ClientHeaders | undefined,
  identity: ClientIdentityDocument | undefined,
) => Promise<Headers>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L65)

### isRelkitQuery

Selects query entries owned by RELKIT's existing key prefix.

**Signature**

```ts
declare const isRelkitQuery: (query: { readonly queryKey: readonly unknown[] }) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L23)

### loadIdentity

Reads the existing backend identity document with caller-owned cancellation.

**Signature**

```ts
declare const loadIdentity: (
  baseUrl: string,
  credentials: NonNullable<RequestInit["credentials"]>,
  signal: AbortSignal,
) => Promise<ClientIdentityDocument>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L45)

### sameScope

Compares every existing query and hydration isolation boundary.

**Signature**

```ts
declare const sameScope: (left: RelkitKeyScope, right: RelkitKeyScope) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L202)

### scopeFor

Constructs the complete existing backend and identity hydration/query scope.

**Signature**

```ts
declare const scopeFor: (
  backend: string,
  identity: ClientIdentityDocument,
  identityKey: string | null | undefined,
  environment?: string,
) => RelkitKeyScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L178)

### streamClientFor

Selects the existing HTTP, WebSocket, auto or SSE procedure adapter.

**Signature**

```ts
declare const streamClientFor: (options: {
  readonly baseUrl: string;
  readonly credentials: NonNullable<RequestInit["credentials"]>;
  readonly headers: ClientHeaders | undefined;
  readonly transport: "auto" | "websocket" | "http-stream" | "sse" | undefined;
  readonly timeoutMs: number;
  readonly identity: ClientIdentityDocument | undefined;
}) => ReturnType<typeof createClient>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L141)

### streamFetcher

Bounds native stream establishment without timing out the subsequent live stream.

**Signature**

```ts
declare const streamFetcher: (timeoutMs: number) => typeof fetch;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-support.ts#L118)

## `context-types.ts`

### "./context.types.js" (namespace export)

Re-exports all named exports from the "./context.types.js" module.

**Signature**

```ts
export * from "./context.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context-types.ts#L2)

## `context.tsx`

### RelkitClientProvider

Provides configured clients, query hydration, identity isolation and realtime ownership.

**See**

- https://relkit.dev/docs/modules/client#install-the-provider

**Signature**

```ts
declare const RelkitClientProvider: (props: RelkitClientProviderProps) => ReactNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.tsx#L51)

### RelkitClientProviderProps

**Signature**

```ts
declare const RelkitClientProviderProps: RelkitClientProviderProps;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.tsx#L39)

### RelkitClientRuntime

**Signature**

```ts
declare const RelkitClientRuntime: RelkitClientRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.tsx#L40)

### RelkitHydrationState

**Signature**

```ts
declare const RelkitHydrationState: RelkitHydrationState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.tsx#L41)

### useRelkitClient

Reads the required existing React client provider context.

**Throws**

Error when called outside RelkitClientProvider.

**See**

- https://relkit.dev/docs/modules/client#install-the-provider

**Signature**

```ts
declare const useRelkitClient: () => RelkitClientRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.tsx#L195)

## `context.types.ts`

### RelkitClientProviderProps (interface)

React provider configuration retaining borrowed clients and hydration authority.

**Signature**

```ts
export interface RelkitClientProviderProps {
  readonly baseUrl?: string;
  readonly environment?: string;
  readonly credentials?: RequestInit["credentials"];
  readonly headers?: ClientHeaders;
  readonly queryClient?: QueryClient;
  readonly identityKey?: string | null;
  readonly hydratedState?: RelkitHydrationState;
  readonly transport?: "auto" | "websocket" | "http-stream" | "sse";
  readonly requestTimeoutMs?: number;
  readonly streamEstablishmentTimeoutMs?: number;
  readonly children: ReactNode;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.types.ts#L20)

### RelkitClientRuntime (interface)

Provider-owned client and identity state shared by React boundary adapters.

**Signature**

```ts
export interface RelkitClientRuntime {
  readonly client: ReturnType<typeof createClient>;
  readonly streamClient: ReturnType<typeof createClient>;
  readonly queryClient: QueryClient;
  readonly utils: unknown;
  readonly identity?: ClientIdentityDocument;
  readonly identityKey?: string | null;
  readonly status: "loading" | "ready" | "application-updated" | "error";
  readonly scope?: RelkitKeyScope;
  readonly transport: "auto" | "websocket" | "http-stream" | "sse";
  readonly streamEstablishmentTimeoutMs: number;
  readonly environment?: string;
  readonly realtime: RealtimeManager;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.types.ts#L37)

### RelkitHydrationState (interface)

Server-supplied ready identity and application contract hydration.

**Signature**

```ts
export interface RelkitHydrationState {
  readonly scope: RelkitKeyScope;
  readonly dehydrated: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/context.types.ts#L12)

## `finite-hooks.ts`

### RelkitWriteError

**Signature**

```ts
declare const RelkitWriteError: typeof RelkitWriteError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L35)

### useInfiniteRoute

Adapts a declared paginated route while retaining page and scope inference.

**Signature**

```ts
declare const useInfiniteRoute: <
  Name extends QuerySelector,
  PageParam,
  Selected = InfiniteData<OutputFor<Name>, PageParam>,
>(
  name: Name,
  options: Omit<
    UseInfiniteQueryOptions<
      OutputFor<Name>,
      ErrorFor<Name>,
      Selected,
      readonly unknown[],
      PageParam
    >,
    "queryKey" | "queryFn"
  > & { readonly input: (page: PageParam) => InputFor<Name> },
) => UseInfiniteQueryResult<Selected, ErrorFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L177)

### useRoute

Adapts a declared finite route into a scope-bound TanStack query.

**Signature**

```ts
declare const useRoute: <Name extends QuerySelector, Selected = OutputFor<Name>>(
  name: Name,
  options: QueryInput<Name, Selected>,
) => UseQueryResult<Selected, ErrorFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L45)

### useRouteMutation

Adapts a declared accepted-work operation into TanStack mutation state.

**Signature**

```ts
declare const useRouteMutation: <Name extends MutationSelector, Context = unknown>(
  name: Name,
  options?: Omit<
    UseMutationOptions<OutputFor<Name>, ErrorFor<Name>, InputFor<Name>, Context>,
    "mutationKey" | "mutationFn"
  >,
) => UseMutationResult<OutputFor<Name>, ErrorFor<Name>, InputFor<Name>, Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L98)

### useRouteUtils

Returns the existing generated query/mutation utilities for a declared selector.

**Signature**

```ts
declare const useRouteUtils: <Name extends QuerySelector | MutationSelector>(
  name: Name,
) => ProcedureUtilsLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L219)

### useSuspenseRoute

Adapts a ready declared route into a scope-bound suspense query.

**Signature**

```ts
declare const useSuspenseRoute: <Name extends QuerySelector, Selected = OutputFor<Name>>(
  name: Name,
  options: Omit<
    UseSuspenseQueryOptions<OutputFor<Name>, ErrorFor<Name>, Selected>,
    "queryKey" | "queryFn"
  > & {
    readonly input: InputFor<Name>;
  },
) => UseSuspenseQueryResult<Selected, ErrorFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.ts#L71)

## `finite-hooks.types.ts`

### QueryInput (type alias)

Declared route input or the existing skip-token readiness sentinel.

**Signature**

```ts
type QueryInput<Name extends QuerySelector, Selected> = Omit<
  UseQueryOptions<OutputFor<Name>, ErrorFor<Name>, Selected>,
  "queryKey" | "queryFn"
> & { readonly input: InputFor<Name> };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/finite-hooks.types.ts#L9)

## `index.ts`

Exposes React providers and hooks backed by the selected query adapter. Install
react, @tanstack/react-query@^5, @tanstack/query-core@^5 and

### "./agent-hook.js" (namespace export)

Re-exports all named exports from the "./agent-hook.js" module.

**Signature**

```ts
export * from "./agent-hook.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L8)

### "./agent-reconcile.js" (namespace export)

Re-exports all named exports from the "./agent-reconcile.js" module.

**Signature**

```ts
export * from "./agent-reconcile.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L9)

### "./context.js" (namespace export)

Re-exports all named exports from the "./context.js" module.

**Signature**

```ts
export * from "./context.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L7)

### "./finite-hooks.js" (namespace export)

Re-exports all named exports from the "./finite-hooks.js" module.

**Signature**

```ts
export * from "./finite-hooks.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L10)

### "./job-hooks.js" (namespace export)

Re-exports all named exports from the "./job-hooks.js" module.

**Signature**

```ts
export * from "./job-hooks.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L11)

### "./keys.js" (namespace export)

Re-exports all named exports from the "./keys.js" module.

**Signature**

```ts
export * from "./keys.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L12)

### "./pending.js" (namespace export)

Re-exports all named exports from the "./pending.js" module.

**Signature**

```ts
export * from "./pending.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L13)

### "./realtime-hook.js" (namespace export)

Re-exports all named exports from the "./realtime-hook.js" module.

**Signature**

```ts
export * from "./realtime-hook.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L14)

### "./registry.js" (namespace export)

Re-exports all named exports from the "./registry.js" module.

**Signature**

```ts
export * from "./registry.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L15)

### "./stream-hook.js" (namespace export)

Re-exports all named exports from the "./stream-hook.js" module.

**Signature**

```ts
export * from "./stream-hook.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L16)

### CountPresence

**Signature**

```ts
declare const CountPresence: CountPresence;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L17)

### JobCancelInput

**Signature**

```ts
declare const JobCancelInput: JobCancelInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L21)

### JobCancelInputFor

**Signature**

```ts
declare const JobCancelInputFor: JobCancelInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L22)

### JobCancelName

**Signature**

```ts
declare const JobCancelName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L23)

### JobCancelOutputFor

**Signature**

```ts
declare const JobCancelOutputFor: JobCancelOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L24)

### JobClientField

**Signature**

```ts
declare const JobClientField: JobClientField;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L20)

### JobContract

**Signature**

```ts
declare const JobContract: JobContract<
  Name,
  JobId,
  Input,
  Output,
  Failure,
  Progress,
  Streams,
  Operations,
  Fields
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L19)

### JobFor

**Signature**

```ts
declare const JobFor: JobFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L25)

### JobGetInput

**Signature**

```ts
declare const JobGetInput: JobGetInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L26)

### JobListInput

**Signature**

```ts
declare const JobListInput: JobListInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L28)

### JobListQuery

**Signature**

```ts
declare const JobListQuery: JobListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L27)

### JobProcedureContract

**Signature**

```ts
declare const JobProcedureContract: JobProcedureContract<Input, Output, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L30)

### JobProcedureSelector

**Signature**

```ts
declare const JobProcedureSelector: JobProcedureSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L29)

### JobRegistry

**Signature**

```ts
declare const JobRegistry: JobRegistry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L31)

### JobRetryInput

**Signature**

```ts
declare const JobRetryInput: JobRetryInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L32)

### JobRetryInputFor

**Signature**

```ts
declare const JobRetryInputFor: JobRetryInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L33)

### JobRetryName

**Signature**

```ts
declare const JobRetryName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L34)

### JobRetryOutputFor

**Signature**

```ts
declare const JobRetryOutputFor: JobRetryOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L35)

### JobRunFor

**Signature**

```ts
declare const JobRunFor: JobRunFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L39)

### JobRunSelector

**Signature**

```ts
declare const JobRunSelector: JobRunSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L36)

### JobSelector

**Signature**

```ts
declare const JobSelector: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L37)

### JobSnapshotFor

**Signature**

```ts
declare const JobSnapshotFor: JobSnapshotFor<Input, Output, Progress, Failure, Fields>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L38)

### JobStreamInput

**Signature**

```ts
declare const JobStreamInput: JobStreamInput<StreamName>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L40)

### JobStreamProcedureContract

**Signature**

```ts
declare const JobStreamProcedureContract: JobStreamProcedureContract<Input, Item, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L41)

### JobTriggerInput

**Signature**

```ts
declare const JobTriggerInput: JobTriggerInput<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L42)

### JobTriggerInputFor

**Signature**

```ts
declare const JobTriggerInputFor: JobTriggerInputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L43)

### JobTriggerName

**Signature**

```ts
declare const JobTriggerName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L44)

### JobTriggerOptions

**Signature**

```ts
declare const JobTriggerOptions: JobTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L46)

### JobTriggerOutputFor

**Signature**

```ts
declare const JobTriggerOutputFor: JobTriggerOutputFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L45)

### JobTriggerSelector

**Signature**

```ts
declare const JobTriggerSelector: JobTriggerSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L47)

### JobWatchFrameFor

**Signature**

```ts
declare const JobWatchFrameFor: JobWatchFrameFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L49)

### JobWatchInput

**Signature**

```ts
declare const JobWatchInput: JobWatchInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L48)

### JobWatchName

**Signature**

```ts
declare const JobWatchName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L50)

### MemberPresence

**Signature**

```ts
declare const MemberPresence: MemberPresence<Member>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L17)

### SelectedJobField

**Signature**

```ts
declare const SelectedJobField: SelectedJobField<Fields, Field>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/index.ts#L51)

## `job-hooks-support.ts`

### PreparedJobRequest

**Signature**

```ts
declare const PreparedJobRequest: PreparedJobRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L4)

### generatedJobTriggerName

Recognizes a generated trigger selector without rewriting other route names.

**Signature**

```ts
declare const generatedJobTriggerName: (name: string) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L70)

### isRecord

Checks whether the existing property-access boundary accepts a supplied value.

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L80)

### prepareJobRequest

Binds a transmitted job request to caller identity and explicit receipt authority.

**Signature**

```ts
declare const prepareJobRequest: (
  value: unknown,
  expectedIdentity: ExpectedClientIdentity,
  mutationContext?: object,
) => PreparedJobRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L15)

### readOperationId

Selects a caller-supplied operation ID from the existing request shape.

**Signature**

```ts
declare const readOperationId: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L48)

### readRunId

Selects the existing run identity from a request.

**Signature**

```ts
declare const readRunId: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.ts#L61)

## `job-hooks-support.types.ts`

Transmitted job input and its operation/run receipt references.

### PreparedJobRequest (interface)

Transmitted job input and its operation/run receipt references.

**Signature**

```ts
export interface PreparedJobRequest {
  readonly value: unknown;
  readonly operationId: string;
  readonly idempotencyKey?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks-support.types.ts#L2)

## `job-hooks.ts`

### JobMutationOptions

**Signature**

```ts
declare const JobMutationOptions: JobMutationOptions<Output, Failure, Input, Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L15)

### UseJobRunOptions

**Signature**

```ts
declare const UseJobRunOptions: UseJobRunOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L4)

### UseJobRunResult

**Signature**

```ts
declare const UseJobRunResult: UseJobRunResult<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L4)

### useJobCancel

**Signature**

```ts
declare const useJobCancel: <Name extends JobCancelName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobCancelOutputFor<Name>,
    JobFailureFor<Name>,
    JobCancelInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobCancelOutputFor<Name>,
  JobFailureFor<Name>,
  JobCancelInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L16)

### useJobRetry

**Signature**

```ts
declare const useJobRetry: <Name extends JobRetryName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobRetryOutputFor<Name>,
    JobFailureFor<Name>,
    JobRetryInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobRetryOutputFor<Name>,
  JobFailureFor<Name>,
  JobRetryInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L16)

### useJobRun

Borrows an idle scoped job controller and exposes its frozen external-store state.

**Signature**

```ts
declare const useJobRun: <Name extends JobWatchName>(
  name: Name,
  options?: UseJobRunOptions,
) => UseJobRunResult<JobRunFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L25)

### useJobTrigger

**Signature**

```ts
declare const useJobTrigger: <Name extends JobTriggerName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobTriggerOutputFor<Name>,
    JobFailureFor<Name>,
    JobTriggerInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobTriggerOutputFor<Name>,
  JobFailureFor<Name>,
  JobTriggerInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.ts#L16)

## `job-hooks.types.ts`

### UseJobRunOptions (interface)

Watch request authority and explicit connection/recovery policy for the declared job.

**Signature**

```ts
export interface UseJobRunOptions extends Omit<
  JobWatchOptions,
  "runId" | "expectedIdentity" | "identityKey" | "applicationId" | "protocolVersion"
> {
  readonly runId?: string;
  readonly enabled?: boolean;
  readonly autoConnect?: boolean;
  readonly expectedIdentity?: ExpectedClientIdentity;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.types.ts#L6)

### UseJobRunResult (interface)

Frozen job run state plus connection, refetch and disposal controls.

**Signature**

```ts
export interface UseJobRunResult<Run = RunSnapshot> extends JobWatchState<Run> {
  readonly connect: () => Promise<void>;
  readonly disconnect: () => Promise<void>;
  readonly refetch: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-hooks.types.ts#L20)

## `job-mutation-hooks.ts`

### JobMutationOptions

**Signature**

```ts
declare const JobMutationOptions: JobMutationOptions<Output, Failure, Input, Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-hooks.ts#L4)

### useJobCancel

Adapts an idempotent job cancellation request into TanStack mutation state.

**Signature**

```ts
declare const useJobCancel: <Name extends JobCancelName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobCancelOutputFor<Name>,
    JobFailureFor<Name>,
    JobCancelInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobCancelOutputFor<Name>,
  JobFailureFor<Name>,
  JobCancelInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-hooks.ts#L114)

### useJobRetry

Adapts an explicit job retry request into TanStack mutation state.

**Signature**

```ts
declare const useJobRetry: <Name extends JobRetryName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobRetryOutputFor<Name>,
    JobFailureFor<Name>,
    JobRetryInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobRetryOutputFor<Name>,
  JobFailureFor<Name>,
  JobRetryInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-hooks.ts#L139)

### useJobTrigger

Adapts a declared job trigger and its pending authority into TanStack mutation state.

**Signature**

```ts
declare const useJobTrigger: <Name extends JobTriggerName, Context = unknown>(
  name: Name,
  options?: JobMutationOptions<
    JobTriggerOutputFor<Name>,
    JobFailureFor<Name>,
    JobTriggerInputFor<Name>,
    Context
  >,
) => UseMutationResult<
  JobTriggerOutputFor<Name>,
  JobFailureFor<Name>,
  JobTriggerInputFor<Name>,
  Context
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-hooks.ts#L41)

## `job-mutation-hooks.types.ts`

### JobMutationOptions (type alias)

Job mutation options preserving operation identity, retry and TanStack callback inference.

**Signature**

```ts
type JobMutationOptions<Output, Failure, Input, Context> = Omit<
  UseMutationOptions<Output, Failure, Input, Context>,
  "mutationKey" | "mutationFn"
> & { readonly jobId?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-hooks.types.ts#L10)

## `job-mutation-support.ts`

### controlReferences

Retains the existing run reference in a job control receipt.

**Signature**

```ts
declare const controlReferences: (input: unknown) => { readonly runId?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-support.ts#L42)

### offline

Reads the browser online hint synchronously without acquiring resources.

**Signature**

```ts
declare const offline: () => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-support.ts#L51)

### settlePending

Applies the existing authoritative or unknown receipt settlement policy.

**Signature**

```ts
declare const settlePending: (
  scopeKey: string,
  pending: PendingOperationMetadata,
  error: unknown,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-support.ts#L29)

### writableScope

Requires ready identity authority before an accepted-work dispatch.

**Signature**

```ts
declare const writableScope: (
  runtime: RelkitClientRuntime,
) => NonNullable<RelkitClientRuntime["scope"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/job-mutation-support.ts#L13)

## `keys.ts`

### RelkitJobKeyOptions

**Signature**

```ts
declare const RelkitJobKeyOptions: RelkitJobKeyOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.ts#L2)

### RelkitKeyScope

**Signature**

```ts
declare const RelkitKeyScope: RelkitKeyScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.ts#L2)

### relkitJobKey

Constructs the canonical scope-complete job observation or mutation key.

**Signature**

```ts
declare const relkitJobKey: (
  scope: RelkitKeyScope,
  operation: "trigger" | "run" | "cancel" | "retry",
  options: RelkitJobKeyOptions,
  input?: unknown,
) => readonly unknown[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.ts#L42)

### relkitKey

Constructs the canonical scope-complete finite query or mutation key.

**Signature**

```ts
declare const relkitKey: (
  scope: RelkitKeyScope,
  kind: "query" | "mutation" | "stream" | "agent" | "channel",
  procedureId: string,
  input?: unknown,
) => readonly unknown[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.ts#L12)

## `keys.types.ts`

Backend, fingerprint, transport, identity and session boundaries of cached client work.

### RelkitJobKeyOptions (interface)

Run, cursor, named-content and projection fields participating in a job cache key.

**Signature**

```ts
export interface RelkitJobKeyOptions {
  readonly jobId: string;
  readonly runId?: string;
  readonly projection?: string;
  readonly schemaVersion?: string;
  readonly environment?: string;
  readonly jobsProtocolVersion?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.types.ts#L14)

### RelkitKeyScope (interface)

Backend, fingerprint, transport, identity and session boundaries of cached client work.

**Signature**

```ts
export interface RelkitKeyScope {
  readonly backend: string;
  readonly applicationId: string;
  readonly identityScope: string;
  readonly sessionEpoch: string;
  readonly identityKey: string | null | undefined;
  readonly publicFingerprint: string;
  readonly environment?: string;
  readonly jobsProtocolVersion?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/keys.types.ts#L2)

## `mutation-runtime.ts`

### mutationOperations

Once-acquired submission service at the Promise/React compatibility boundary.

**Signature**

```ts
declare const mutationOperations: MutationOperationsService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/mutation-runtime.ts#L11)

### mutationRuntime

**Signature**

```ts
declare const mutationRuntime: ManagedRuntime.ManagedRuntime<MutationOperations, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/mutation-runtime.ts#L7)

## `mutation.service.ts`

### MutationOperations (class)

Accepted-work dispatch and authoritative pending settlement contract.

**Signature**

```ts
declare class MutationOperations
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/mutation.service.ts#L11)

### MutationOperationsLive

Acquires accepted-work submission and pending-outcome settlement.

**See**

- tests/compatibility/pending.test.ts for checked metadata and recovery behavior.

**Signature**

```ts
declare const MutationOperationsLive: Layer.Layer<MutationOperations, never, PendingOperations>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/mutation.service.ts#L22)

## `mutation.service.types.ts`

### MutationOperationsService (interface)

Accepted-work submission authority shared by finite and job React adapters.

**Signature**

```ts
export interface MutationOperationsService {
  /** Dispatches accepted work independently of the submitting view lifetime.
   * @param scope - Complete pending receipt isolation scope.
   * @param kind - Existing submission category.
   * @param resource - Declared route or job identity.
   * @param input - Transmitted input retained only in opted-in memory.
   * @param references - Existing receipt references.
   * @param options - Existing idempotency, reuse and retention policy.
   * @param execute - Native server submission boundary.
   * @returns A lazy observed original result or rejection after metadata settlement. */
  readonly submit: (
    scope: string,
    kind: PendingOperationMetadata["kind"],
    resource: string,
    input: unknown,
    references: PendingReferences,
    options: PendingRememberOptions,
    execute: () => PromiseLike<unknown>,
  ) => Effect.Effect<unknown, unknown>;
  /** Applies the existing unknown-outcome policy to receipt metadata.
   * @param scope - Complete pending receipt isolation scope.
   * @param pending - Previously stored metadata.
   * @param error - Original native rejection.
   * @returns A lazy observed metadata update; submission preserves the original rejection. */
  readonly settle: (
    scope: string,
    pending: PendingOperationMetadata,
    error: unknown,
  ) => Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/mutation.service.types.ts#L5)

## `pending-errors.ts`

### MAX_JOB_INTENTS

**Signature**

```ts
declare const MAX_JOB_INTENTS: 100;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L1)

### PendingCapacityError (class)

**Signature**

```ts
declare class PendingCapacityError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L3)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_PENDING_CAPACITY"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L4)

### PendingRecoveryUnavailableError (class)

**Signature**

```ts
declare class PendingRecoveryUnavailableError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L29)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_PENDING_RECOVERY_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L30)

### PendingRequestMismatchError (class)

**Signature**

```ts
declare class PendingRequestMismatchError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L16)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_PENDING_REQUEST_MISMATCH"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-errors.ts#L17)

## `pending-outcome.ts`

### jobUnknownOutcome

Extracts recognized recovery authority without manufacturing successful outcomes.

**Signature**

```ts
declare const jobUnknownOutcome: (value: unknown) => JobUnknownOutcome | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-outcome.ts#L8)

## `pending-store.ts`

### PENDING_PREFIX

**Signature**

```ts
declare const PENDING_PREFIX: "relkit.pending.";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L4)

### clearPendingStorage

Retires all persisted receipt metadata in one complete identity scope.

**Signature**

```ts
declare const clearPendingStorage: (scopeKey: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L71)

### pendingEntryKey

Constructs the existing persistence key for one scoped receipt.

**Signature**

```ts
declare const pendingEntryKey: (scopeKey: string, operationId: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L16)

### pendingMemory

**Signature**

```ts
declare const pendingMemory: Map<
  string,
  { readonly metadata: PendingOperationMetadata; readonly request?: unknown }
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L5)

### readPendingStorage

Recovers selectively validated metadata while isolating malformed entries.

**Signature**

```ts
declare const readPendingStorage: (scopeKey: string) => Map<string, PendingOperationMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L48)

### removePendingStorage

Removes persisted receipt metadata without surfacing unavailable browser storage.

**Signature**

```ts
declare const removePendingStorage: (key: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L37)

### writePendingStorage

Persists metadata best-effort without persisting transmitted requests.

**Signature**

```ts
declare const writePendingStorage: (key: string, value: PendingOperationMetadata) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-store.ts#L26)

## `pending-support.ts`

Enumerates only the existing nested public recovery envelopes.

### candidates

Enumerates only the existing nested public recovery envelopes.

**Signature**

```ts
declare const candidates: (value: unknown) => readonly unknown[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-support.ts#L6)

### isRecord

Checks whether the existing property-access boundary accepts a supplied value.

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending-support.ts#L16)

## `pending.schemas.ts`

### PersistedPendingMetadata

Legacy persisted metadata authority: only operationId was required on recovery.

**Signature**

```ts
declare const PersistedPendingMetadata: Schema.Struct<{ readonly operationId: Schema.String }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.schemas.ts#L4)

### isPersistedPendingMetadata

Validates the recovery discriminator without stripping other legacy fields.

**Signature**

```ts
declare const isPersistedPendingMetadata: <I>(
  input: I,
) => input is I & { readonly operationId: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.schemas.ts#L11)

## `pending.service.ts`

### PendingOperations (class)

Submission receipts, recovery authority and memory-only transmitted requests.

**Signature**

```ts
declare class PendingOperations
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.service.ts#L24)

### pendingOperationsLayer

Acquires pending state once; storage remains a best-effort native persistence edge.

**Example**

```ts
import { Effect, ManagedRuntime } from "effect";
import { PendingOperations, pendingOperationsLayer } from "./pending.service.js";
export async function pendingOwner(): Promise<void> {
  const owner = ManagedRuntime.make(pendingOperationsLayer(new Map()));
  try {
    await owner.runPromise(
      Effect.flatMap(PendingOperations, (service) => service.digest({ input: 1 })),
    );
  } finally {
    await owner.dispose();
  }
}
```

**See**

- packages/client/tests/transport/examples.test.ts for the checked live Layer example.

**Signature**

```ts
declare const pendingOperationsLayer: (
  memory?: Map<string, { readonly metadata: PendingOperationMetadata; readonly request?: unknown }>,
) => Layer.Layer<PendingOperations>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.service.ts#L45)

## `pending.ts`

### PendingCapacityError

**Signature**

```ts
declare const PendingCapacityError: typeof PendingCapacityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L12)

### PendingRecoveryUnavailableError

**Signature**

```ts
declare const PendingRecoveryUnavailableError: typeof PendingRecoveryUnavailableError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L13)

### PendingRememberOptions

**Signature**

```ts
declare const PendingRememberOptions: PendingRememberOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L10)

### PendingRequestMismatchError

**Signature**

```ts
declare const PendingRequestMismatchError: typeof PendingRequestMismatchError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L14)

### clearPendingOperations

Clears every receipt in an explicitly retired identity scope.

**Signature**

```ts
declare const clearPendingOperations: (scopeKey: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L138)

### digestPendingRequest

Hashes the existing canonical transmitted request representation.

**Signature**

```ts
declare const digestPendingRequest: (value: unknown) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L156)

### forgetPending

Removes memory and best-effort persisted metadata after a known outcome.

**Signature**

```ts
declare const forgetPending: (scopeKey: string, operationId: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L95)

### isJobUnknownOutcome

Checks nested public error envelopes for an unknown job outcome.

**Signature**

```ts
declare const isJobUnknownOutcome: (value: unknown) => value is JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L147)

### jobUnknownOutcome

**Signature**

```ts
declare const jobUnknownOutcome: (value: unknown) => JobUnknownOutcome | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L9)

### matchesPendingRequest

Compares a proposed retry against its recorded transmitted request digest.

**Signature**

```ts
declare const matchesPendingRequest: (
  scopeKey: string,
  operationId: string,
  request: unknown,
) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L125)

### pendingOperations

Merges recovered metadata with newer in-memory values without discarding authority.

**Signature**

```ts
declare const pendingOperations: (scopeKey: string) => readonly PendingOperationMetadata[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L104)

### pendingRequest

Reads a transmitted request; restored session metadata never recreates input.

**Signature**

```ts
declare const pendingRequest: (scopeKey: string, operationId: string) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L114)

### pendingScopeKey

Preserves the complete existing scope serialization used by query and receipt keys.

**Signature**

```ts
declare const pendingScopeKey: (scope: RelkitKeyScope) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L27)

### rememberJobPending

Remembers a job intent and retains its transmitted request only in memory.

**Signature**

```ts
declare const rememberJobPending: (
  scopeKey: string,
  resourceId: string,
  request: unknown,
  options?: PendingRememberOptions,
) => Promise<PendingOperationMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L63)

### rememberPending

Records a submission before dispatch without persisting its sensitive request.

**Signature**

```ts
declare const rememberPending: (
  scopeKey: string,
  kind: PendingOperationMetadata["kind"],
  resourceId: string,
  value: unknown,
  references?: PendingReferences,
  options?: PendingRememberOptions,
) => Promise<PendingOperationMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L41)

### updatePending

Updates metadata while preserving a previously retained in-memory request.

**Signature**

```ts
declare const updatePending: (scopeKey: string, value: PendingOperationMetadata) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.ts#L85)

## `pending.types.ts`

### PendingOperationService (interface)

One browser's pending-operation state with isolated live/test implementations.

**Signature**

```ts
export interface PendingOperationService {
  /** Records validated metadata while retaining original input only in opted-in memory.
   * @param scope - Complete application and identity isolation scope.
   * @param kind - Existing submission category.
   * @param resource - Declared job, route or agent key.
   * @param value - Original transmitted request payload.
   * @param references - Existing durable receipt references.
   * @param options - Existing operation identity, reuse and retention policy.
   * @returns Lazy observed metadata creation or the original hashing/capacity failure. */
  readonly remember: (
    scope: string,
    kind: PendingOperationMetadata["kind"],
    resource: string,
    value: unknown,
    references: PendingReferences,
    options: PendingRememberOptions,
  ) => Effect.Effect<PendingOperationMetadata, unknown>;
  /** Replaces persisted metadata without persisting request inputs.
   * @param scope - Complete pending isolation scope.
   * @param value - Existing receipt metadata with its updated outcome.
   * @returns A synchronous observed best-effort metadata update. */
  readonly update: (scope: string, value: PendingOperationMetadata) => Effect.Effect<void>;
  /** Removes one settled receipt and its memory-only request.
   * @param scope - Complete pending isolation scope.
   * @param id - Existing operation identity.
   * @returns A synchronous observed state update. */
  readonly forget: (scope: string, id: string) => Effect.Effect<void>;
  /** Lists metadata using the existing selective persistence validation.
   * @param scope - Complete pending isolation scope.
   * @returns A synchronous observed metadata snapshot. */
  readonly list: (scope: string) => Effect.Effect<readonly PendingOperationMetadata[]>;
  /** Reads opted-in memory input without recovering payloads from persisted metadata.
   * @param scope - Complete pending isolation scope.
   * @param id - Existing operation identity.
   * @returns A synchronous observed original input when retained. */
  readonly request: (scope: string, id: string) => Effect.Effect<unknown>;
  /** Clears receipt metadata and retained memory input for one isolation scope.
   * @param scope - Complete pending isolation scope.
   * @returns A synchronous observed state update. */
  readonly clear: (scope: string) => Effect.Effect<void>;
  /** Checks a request digest against stored receipt metadata.
   * @param scope - Complete pending isolation scope.
   * @param id - Existing operation identity.
   * @param value - Original request payload whose digest is compared.
   * @returns A lazy observed match decision or the original hashing failure. */
  readonly matches: (scope: string, id: string, value: unknown) => Effect.Effect<boolean, unknown>;
  /** Hashes canonical JSON through the existing WebCrypto boundary.
   * @param value - Original payload whose canonical representation is hashed.
   * @returns A lazy observed SHA-256 digest or the original serialization/crypto failure. */
  readonly digest: (value: unknown) => Effect.Effect<string, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.types.ts#L17)

### PendingReferences (type alias)

References persisted with metadata; transmitted inputs remain memory-only.

**Signature**

```ts
type PendingReferences = Pick<PendingOperationMetadata, "threadId" | "runId">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.types.ts#L14)

### PendingRememberOptions (interface)

Submission/recovery authority retained from the existing pending API.

**Signature**

```ts
export interface PendingRememberOptions {
  readonly operationId?: string;
  readonly idempotencyKey?: string;
  readonly recovery?: JobUnknownOutcome["recovery"];
  readonly retainRequest?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/pending.types.ts#L6)

## `procedure.ts`

### ProcedureUtilsLike

**Signature**

```ts
declare const ProcedureUtilsLike: ProcedureUtilsLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/procedure.ts#L2)

### procedureCall

Resolves a callable generated procedure using exact selector semantics.

**Signature**

```ts
declare const procedureCall: (
  root: unknown,
  selector: string | readonly string[],
) => (...args: unknown[]) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/procedure.ts#L25)

### procedureUtils

Resolves generated TanStack utilities using exact selector semantics.

**Signature**

```ts
declare const procedureUtils: (
  root: unknown,
  selector: string | readonly string[],
) => ProcedureUtilsLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/procedure.ts#L10)

### resolveProcedure

Resolves generated paths without changing exact dotted route-key semantics.

**Signature**

```ts
declare const resolveProcedure: (root: unknown, selector: string | readonly string[]) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/procedure.ts#L40)

## `procedure.types.ts`

### ProcedureUtilsLike (interface)

Generated TanStack query/mutation options and keys resolved by exact selector.

**Signature**

```ts
export interface ProcedureUtilsLike {
  queryOptions(options: object): object;
  infiniteOptions(options: object): object;
  mutationOptions(options?: object): object;
  queryKey(options?: object): QueryKey;
  infiniteKey(options?: object): QueryKey;
  mutationKey(options?: object): QueryKey;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/procedure.types.ts#L4)

## `realtime-hook.ts`

### ChannelHandlers

**Signature**

```ts
declare const ChannelHandlers: Partial<{
  readonly [Event in keyof EventsFor<Name>]: (payload: EventsFor<Name>[Event]) => void;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L12)

### UseChannelOptions

**Signature**

```ts
declare const UseChannelOptions: UseChannelOptions<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L13)

### UseChannelResult

**Signature**

```ts
declare const UseChannelResult: UseChannelResult<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L14)

### UseRealtimeResult

**Signature**

```ts
declare const UseRealtimeResult: UseRealtimeResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L11)

### useChannel

Borrows one shared channel session and projects ordered frames into React state.

**Signature**

```ts
declare const useChannel: <Name extends ChannelSelector>(
  name: Name,
  options: UseChannelOptions<Name>,
) => UseChannelResult<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L55)

### useRealtime

Adapts manager status and explicit subscription leases into React's external store.

**Signature**

```ts
declare const useRealtime: () => UseRealtimeResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.ts#L30)

## `realtime-hook.types.ts`

### ChannelFor (type alias)

The channel registry entry inferred from its declared name.

**Signature**

```ts
type ChannelFor<Name extends ChannelSelector> = ChannelRegistry[Name];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L10)

### ChannelHandlers (type alias)

Typed handlers keyed by the declared channel's event names.

**Signature**

```ts
type ChannelHandlers<Name extends ChannelSelector> = Partial<{
  readonly [Event in keyof EventsFor<Name>]: (payload: EventsFor<Name>[Event]) => void;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L50)

### ChannelState (interface)

Current checkpoint, connection status, events and presence projection.

**Signature**

```ts
export interface ChannelState {
  readonly status: RealtimeStatus;
  readonly checkpoint?: ChannelCheckpoint;
  readonly caughtUp: boolean;
  readonly gap?: string;
  readonly presence?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L66)

### EventsFor (type alias)

Event payloads inferred from the declared channel.

**Signature**

```ts
type EventsFor<Name extends ChannelSelector> =
  ChannelFor<Name> extends { readonly events: infer Events } ? Events : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L23)

### ParamsFor (type alias)

Channel parameter input inferred from the declared channel.

**Signature**

```ts
type ParamsFor<Name extends ChannelSelector> =
  ChannelFor<Name> extends { readonly params: infer Params } ? Params : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L16)

### PresenceFor (type alias)

Presence state inferred from the declared channel.

**Signature**

```ts
type PresenceFor<Name extends ChannelSelector> =
  ChannelFor<Name> extends { readonly presence: infer Presence } ? Presence : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L30)

### UseChannelOptions (interface)

Channel parameters and current-view event handlers.

**Signature**

```ts
export interface UseChannelOptions<Name extends ChannelSelector> {
  readonly params: ParamsFor<Name>;
  readonly on?: ChannelHandlers<Name>;
  readonly onCaughtUp?: () => void | Promise<void>;
  readonly onGap?: (reason: string) => void | Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L58)

### UseChannelResult (type alias)

Typed channel projection and explicit realtime controls.

**Signature**

```ts
type UseChannelResult<Name extends ChannelSelector> = Omit<ChannelState, "presence"> &
  ([PresenceFor<Name>] extends [never] ? {} : { readonly presence: PresenceFor<Name> });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L78)

### UseRealtimeResult (interface)

Realtime connection state with explicit channel observer controls.

**Signature**

```ts
export interface UseRealtimeResult {
  readonly status: RealtimeStatus;
  readonly subscribe: <Name extends ChannelSelector>(
    name: Name,
    params: ParamsFor<Name>,
    listener: (frame: RealtimeFrame) => void,
  ) => () => void;
  readonly bind: UseRealtimeResult["subscribe"];
  readonly unbind: (unsubscribe: () => void) => void;
  readonly unsubscribe: (unsubscribe: () => void) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-hook.types.ts#L34)

## `realtime-manager.ts`

### RealtimeFrame

**Signature**

```ts
declare const RealtimeFrame: RealtimeFrame;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L7)

### RealtimeManager (class)

Synchronous external-store adapter over one scoped realtime session owner.

**Signature**

```ts
declare class RealtimeManager {
  constructor(
    client: unknown,
    identity?: Pick<ClientIdentityDocument, "identityScope" | "sessionEpoch">,
  );
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L11)

### subscribe (method)

Borrows a shared channel without letting one observer close another's request.

**Signature**

```ts
declare const subscribe: (
  channel: string,
  params: unknown,
  listener: (frame: RealtimeFrame) => void,
  statusListener?: (status: RealtimeStatus) => void,
) => () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L53)

### listenStatus (method)

Subscribes to manager status changes for React's synchronous external store.

**Signature**

```ts
declare const listenStatus: (listener: () => void) => () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L73)

### dispose (method)

Initiates disposal synchronously; close joins native iterator cleanup.

**Signature**

```ts
declare const dispose: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L81)

### close (method)

Joins the manager's finalization, including pending native pulls and retries.

**Signature**

```ts
declare const close: () => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L91)

### RealtimeStatus

**Signature**

```ts
declare const RealtimeStatus: RealtimeStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L7)

### realtimeSubscriptionKey

**Signature**

```ts
declare const realtimeSubscriptionKey: (channel: string, params: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.ts#L8)

## `realtime-manager.types.ts`

### RealtimeFrame (type alias)

Public channel frames retained without changing wire schemas.

**Signature**

```ts
type RealtimeFrame =
  | {
      readonly kind: "event";
      readonly event: string;
      readonly payload: unknown;
      readonly checkpoint: ChannelCheckpoint;
    }
  | { readonly kind: "caught-up"; readonly checkpoint: ChannelCheckpoint }
  | { readonly kind: "gap"; readonly reason: string; readonly checkpoint: ChannelCheckpoint }
  | { readonly kind: "presence"; readonly presence: PresenceSnapshot };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.types.ts#L8)

### RealtimeSessionService (interface)

Realtime state and scoped workflows supplied by live and test Layers.

**Signature**

```ts
export interface RealtimeSessionService {
  readonly feeds: Map<string, SharedSubscription>;
  readonly statusListeners: Set<() => void>;
  /** Reads the current pure external-store status.
   * @returns A synchronous state read without native acquisition. */
  readonly snapshot: () => Effect.Effect<RealtimeStatus>;
  /** Registers a manager-local view over a complete-key scoped native connection.
   * @param channel - Declared channel key.
   * @param params - Complete native channel parameters.
   * @param listener - Isolated synchronous frame publication.
   * @param statusListener - Optional isolated lifecycle publication.
   * @returns A synchronous registration Effect yielding independently releasable view ownership. */
  readonly subscribe: (
    channel: string,
    params: unknown,
    listener: (frame: RealtimeFrame) => void,
    statusListener?: (status: RealtimeStatus) => void,
  ) => Effect.Effect<Effect.Effect<void>>;
  /** Initiates cancellation of all scoped native connections and resets idle state.
   * @returns A synchronous cancellation request; owner closure joins native workers. */
  readonly stop: () => Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.types.ts#L30)

### RealtimeStatus (type alias)

Existing realtime external-store states.

**Signature**

```ts
type RealtimeStatus = "idle" | "connecting" | "connected" | "stale" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.types.ts#L5)

### SharedSubscription (interface)

One connection shared inside its manager's authorization identity.

**Signature**

```ts
export interface SharedSubscription {
  readonly controller: AbortController;
  readonly listeners: Set<(frame: RealtimeFrame) => void>;
  readonly statusListeners: Set<(status: RealtimeStatus) => void>;
  status: RealtimeStatus;
  checkpoint?: ChannelCheckpoint;
  fiber?: Fiber.Fiber<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-manager.types.ts#L20)

## `realtime-session-key.ts`

Constructs a manager-local sharing key without losing parameter distinctions.

### realtimeSubscriptionKey

Constructs a manager-local sharing key without losing parameter distinctions.

**Signature**

```ts
declare const realtimeSubscriptionKey: (channel: string, params: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-session-key.ts#L7)

## `realtime-session.service.ts`

### RealtimeSessions (class)

One manager's sharing registry, checkpoints and reconnect workers.

**Signature**

```ts
declare class RealtimeSessions
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-session.service.ts#L15)

### realtimeSessionsLayer

Acquires one synchronous registry with scoped, lazy native workers.

**Example**

```ts
import { ManagedRuntime } from "effect";
import { runExecutionSync } from "@relkit/contracts/operation";
import { RealtimeSessions, realtimeSessionsLayer } from "./realtime-session.service.js";
export async function realtimeOwner(): Promise<void> {
  const owner = ManagedRuntime.make(realtimeSessionsLayer({}));
  try {
    const sessions = runExecutionSync(owner, RealtimeSessions);
  } finally {
    await owner.dispose();
  }
}
```

**See**

- packages/client/tests/transport/examples.test.ts for the checked live Layer example.

**Signature**

```ts
declare const realtimeSessionsLayer: (
  client: unknown,
  identity?: Pick<ClientIdentityDocument, "identityScope" | "sessionEpoch">,
) => Layer.Layer<RealtimeSessions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/realtime-session.service.ts#L37)

## `registry.ts`

Augmentable application registry of exact procedure contracts.

### "./registry.types.js" (namespace export)

Re-exports all named exports from the "./registry.types.js" module.

**Signature**

```ts
export * from "./registry.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.ts#L18)

### AgentRegistry (interface)

Augmentable application registry of declared agent contracts.

**Signature**

```ts
export interface AgentRegistry {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.ts#L16)

### ChannelRegistry (interface)

Augmentable application registry of declared channel contracts.

**Signature**

```ts
export interface ChannelRegistry {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.ts#L11)

### ClientRegistry (interface)

Augmentable application registry of exact procedure contracts.

**Signature**

```ts
export interface ClientRegistry {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.ts#L6)

## `registry.types.ts`

### AgentSelector (type alias)

String keys of the declared agent registry.

**Signature**

```ts
type AgentSelector = Extract<keyof AgentRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L129)

### ChannelSelector (type alias)

String keys of the declared channel registry.

**Signature**

```ts
type ChannelSelector = Extract<keyof ChannelRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L124)

### ClientAgentContract (interface)

Generated agent declaration preserving execution, payload and control capabilities.

**Signature**

```ts
export interface ClientAgentContract<
  Input = unknown,
  Output = unknown,
  Controls extends string = never,
  Chat extends boolean = false,
  Resume = never,
  Tool = never,
  PublicState = Readonly<Record<never, never>>,
  CustomEvent = never,
  Scope = ClientAgentDynamic,
  Waiting = never,
> {
  readonly input: Input;
  readonly output: Output;
  readonly controls: Controls;
  readonly chat: Chat;
  readonly resume: Resume;
  readonly tool: Tool;
  readonly publicState: PublicState;
  readonly customEvent: CustomEvent;
  readonly scope: Scope;
  readonly waiting: Waiting;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L89)

### ClientAgentDynamic (interface)

Dynamic agent capability marker retaining the existing broad compatibility contract.

**Signature**

```ts
export interface ClientAgentDynamic {
  readonly kind: "dynamic";
  readonly data: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L116)

### ClientChannelContract (interface)

Generated channel declaration preserving params, event and presence inference.

**Signature**

```ts
export interface ClientChannelContract<
  Params = unknown,
  Events extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
  Presence = never,
> {
  readonly params: Params;
  readonly events: Events;
  readonly presence: Presence;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L66)

### ClientRouteContract (interface)

Generated finite route declaration preserving payload and failure inference.

**Signature**

```ts
export interface ClientRouteContract<
  Input = unknown,
  Output = unknown,
  Failure = globalThis.Error,
> {
  readonly input: Input;
  readonly output: Output;
  readonly error: Failure;
  readonly operation: "query" | "mutation";
  readonly stream: false;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L9)

### ClientSelector (type alias)

String keys of the declared procedure registry.

**Signature**

```ts
type ClientSelector = Extract<keyof ClientRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L134)

### ClientStreamContract (interface)

Generated route stream declaration preserving item and failure inference.

**Signature**

```ts
export interface ClientStreamContract<Input = unknown, Item = unknown, Failure = globalThis.Error> {
  readonly input: Input;
  readonly output: AsyncIterable<Item>;
  readonly item: Item;
  readonly error: Failure;
  readonly operation: "query" | "mutation";
  readonly stream: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L27)

### ContractFor (type alias)

Looks up one exact application procedure contract.

**Signature**

```ts
type ContractFor<Name extends ClientSelector> = ClientRegistry[Name];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L172)

### ErrorFor (type alias)

Infers the declared failure of one exact application procedure.

**Signature**

```ts
type ErrorFor<Name extends ClientSelector> =
  ContractFor<Name> extends {
    readonly error: infer Error;
  }
    ? Error
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L200)

### FiniteSelector (type alias)

Declared procedure keys whose result is finite.

**Signature**

```ts
type FiniteSelector = {
  [Name in ClientSelector]: ClientRegistry[Name] extends { readonly stream: false } ? Name : never;
}[ClientSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L139)

### InputFor (type alias)

Infers the input of one exact application procedure.

**Signature**

```ts
type InputFor<Name extends ClientSelector> =
  ContractFor<Name> extends {
    readonly input: infer Input;
  }
    ? Input
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L178)

### ItemFor (type alias)

Infers the item payload of one exact application stream.

**Signature**

```ts
type ItemFor<Name extends StreamSelector> =
  ContractFor<Name> extends {
    readonly item: infer Item;
  }
    ? Item
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L211)

### JobCancelInput

**Signature**

```ts
declare const JobCancelInput: JobCancelInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L39)

### JobClientField

**Signature**

```ts
declare const JobClientField: JobClientField;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L38)

### JobContract

**Signature**

```ts
declare const JobContract: JobContract<
  Name,
  JobId,
  Input,
  Output,
  Failure,
  Progress,
  Streams,
  Operations,
  Fields
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L37)

### JobFor

**Signature**

```ts
declare const JobFor: JobFor<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L40)

### JobGetInput

**Signature**

```ts
declare const JobGetInput: JobGetInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L41)

### JobListInput

**Signature**

```ts
declare const JobListInput: JobListInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L43)

### JobListQuery

**Signature**

```ts
declare const JobListQuery: JobListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L42)

### JobProcedureContract

**Signature**

```ts
declare const JobProcedureContract: JobProcedureContract<Input, Output, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L45)

### JobProcedureSelector

**Signature**

```ts
declare const JobProcedureSelector: JobProcedureSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L44)

### JobRegistry

**Signature**

```ts
declare const JobRegistry: JobRegistry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L46)

### JobRetryInput

**Signature**

```ts
declare const JobRetryInput: JobRetryInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L47)

### JobRunSelector

**Signature**

```ts
declare const JobRunSelector: JobRunSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L48)

### JobSelector

**Signature**

```ts
declare const JobSelector: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L49)

### JobSnapshotFor

**Signature**

```ts
declare const JobSnapshotFor: JobSnapshotFor<Input, Output, Progress, Failure, Fields>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L50)

### JobStreamInput

**Signature**

```ts
declare const JobStreamInput: JobStreamInput<StreamName>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L51)

### JobStreamProcedureContract

**Signature**

```ts
declare const JobStreamProcedureContract: JobStreamProcedureContract<Input, Item, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L52)

### JobTriggerInput

**Signature**

```ts
declare const JobTriggerInput: JobTriggerInput<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L53)

### JobTriggerOptions

**Signature**

```ts
declare const JobTriggerOptions: JobTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L54)

### JobTriggerSelector

**Signature**

```ts
declare const JobTriggerSelector: JobTriggerSelector<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L55)

### JobWatchInput

**Signature**

```ts
declare const JobWatchInput: JobWatchInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L56)

### MutationSelector (type alias)

Declared finite mutation procedure keys.

**Signature**

```ts
type MutationSelector = {
  [Name in FiniteSelector]: ClientRegistry[Name] extends { readonly operation: "mutation" }
    ? Name
    : never;
}[FiniteSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L155)

### OutputFor (type alias)

Infers the successful output of one exact application procedure.

**Signature**

```ts
type OutputFor<Name extends ClientSelector> =
  ContractFor<Name> extends {
    readonly output: infer Output;
  }
    ? Output
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L189)

### QuerySelector (type alias)

Declared finite query procedure keys.

**Signature**

```ts
type QuerySelector = {
  [Name in FiniteSelector]: ClientRegistry[Name] extends { readonly operation: "query" }
    ? Name
    : never;
}[FiniteSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L146)

### SelectedJobField

**Signature**

```ts
declare const SelectedJobField: SelectedJobField<Fields, Field>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L57)

### StreamSelector (type alias)

Declared procedure keys whose result is streamed.

**Signature**

```ts
type StreamSelector = {
  [Name in ClientSelector]: ClientRegistry[Name] extends { readonly stream: true } ? Name : never;
}[ClientSelector];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/registry.types.ts#L164)

## `stream-hook.ts`

### StreamState

**Signature**

```ts
declare const StreamState: StreamState<Item, Error>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-hook.ts#L4)

### UseStreamResult

**Signature**

```ts
declare const UseStreamResult: UseStreamResult<Input, Item, Error>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-hook.ts#L4)

### useStream

Adapts a declared scoped stream into React state and explicit cancellation controls.

**Signature**

```ts
declare const useStream: <Name extends StreamSelector>(
  name: Name,
  options?: { readonly autoStart?: boolean; readonly input?: InputFor<Name> },
) => UseStreamResult<InputFor<Name>, ItemFor<Name>, ErrorFor<Name>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-hook.ts#L19)

## `stream-hook.types.ts`

Current stream lifecycle, latest item, retained item history and original failure.

### StreamState (interface)

Current stream lifecycle, latest item, retained item history and original failure.

**Signature**

```ts
export interface StreamState<Item, Error> {
  readonly status: "idle" | "starting" | "streaming" | "completed" | "cancelled" | "error";
  readonly items: readonly Item[];
  readonly error?: Error;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-hook.types.ts#L6)

### UseStreamResult (interface)

Typed stream state with explicit start and cancellation controls.

**Signature**

```ts
export interface UseStreamResult<Input, Item, Error> extends StreamState<Item, Error> {
  readonly start: (input: Input) => Promise<void>;
  readonly cancel: () => void;
  readonly reset: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-hook.types.ts#L18)

## `stream-runtime.ts`

### clientStreams

Once-acquired stream service whose call fibers own all native requests.

**Signature**

```ts
declare const clientStreams: ClientStreamService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-runtime.ts#L8)

### streamRuntime

**Signature**

```ts
declare const streamRuntime: ManagedRuntime.ManagedRuntime<ClientStreams, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream-runtime.ts#L6)

## `stream.service.ts`

### ClientStreams (class)

Arbitrary declared procedure observation lifetime, independent of React.

**Signature**

```ts
declare class ClientStreams
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream.service.ts#L8)

### ClientStreamsLive

Supplies declared procedure streams with scoped native pulls.

**See**

- tests/transport/native.test.ts for checked pending-pull cancellation at the Bun boundary.

**Signature**

```ts
declare const ClientStreamsLive: Layer.Layer<ClientStreams, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream.service.ts#L17)

## `stream.service.types.ts`

### ClientStreamService (interface)

Declared procedure observation with borrowed external-store callbacks.

**Signature**

```ts
export interface ClientStreamService {
  /** Owns declared native pulls and external-store publication until cancellation.
   * @param client - Borrowed generated transport.
   * @param name - Exact declared procedure key.
   * @param input - Original request payload.
   * @param signal - View lifetime propagated to the native transport.
   * @param opened - Synchronous establishment publication.
   * @param publish - Isolated synchronous item publication.
   * @returns A lazy scoped observation preserving native errors and joining cleanup. */
  readonly consume: (
    client: unknown,
    name: string,
    input: unknown,
    signal: AbortSignal,
    opened: () => void,
    publish: (item: unknown) => void,
  ) => Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/stream.service.types.ts#L3)

## `view-owner.ts`

Retains an owner across React's synchronous development cleanup/setup replay.

### borrowViewOwner

Retains an owner across React's synchronous development cleanup/setup replay.

**Signature**

```ts
declare const borrowViewOwner: (
  owner: object,
  close: () => void,
  leases: WeakMap<object, object>,
) => () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/view-owner.ts#L10)

## `write-error.ts`

### RelkitWriteError (class)

**Signature**

```ts
declare class RelkitWriteError { constructor(
    readonly outcome: "not-sent" | "unknown",
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/react/write-error.ts#L1)

## `server-context.ts`

Implements the opt-in Bun server query context and identity-bound hydration.
Install @orpc/tanstack-query@2.0.0-beta.31 and @tanstack/query-core@^5 alongside

### CreateRelkitServerContextOptions

**Signature**

```ts
declare const CreateRelkitServerContextOptions: CreateRelkitServerContextOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.ts#L16)

### RelkitServerContext

**Signature**

```ts
declare const RelkitServerContext: RelkitServerContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.ts#L17)

### RelkitServerHydrationState

**Signature**

```ts
declare const RelkitServerHydrationState: RelkitServerHydrationState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.ts#L18)

### createRelkitServerContext

Forwards request identity into a server client and scope-bound hydration state.

**Signature**

```ts
declare const createRelkitServerContext: (
  options: CreateRelkitServerContextOptions,
) => Promise<RelkitServerContext>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.ts#L26)

## `server-context.types.ts`

Describes server query hydration using query-core types alone. The React
provider accepts this structural hydration result without making its own
declarations part of the server integration's dependency graph.

### CreateRelkitServerContextOptions (interface)

Server request, backend and query-client configuration for one hydration context.

**Signature**

```ts
export interface CreateRelkitServerContextOptions {
  readonly baseUrl: string;
  readonly request: Request;
  readonly queryClient: QueryClient;
  readonly identityKey?: string | null;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.types.ts#L22)

### RelkitServerContext (interface)

Typed finite client, TanStack utilities and dehydrated server query state.

**Signature**

```ts
export interface RelkitServerContext {
  readonly client: ReturnType<typeof createClient<DefaultContract>>;
  readonly utils: ReturnType<typeof createTanstackQueryUtils<RelkitServerContext["client"]>>;
  readonly identity: ClientIdentityDocument;
  readonly dehydrate: () => RelkitServerHydrationState;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.types.ts#L30)

### RelkitServerHydrationState (interface)

Identity-bound query snapshot accepted by the React provider on hydration.

**Signature**

```ts
export interface RelkitServerHydrationState {
  /** Backend, application and session authority attached to the cached data. */
  readonly scope: RelkitKeyScope;
  /** Native query-core snapshot, preserving query and mutation metadata. */
  readonly dehydrated: DehydratedState;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server-context.types.ts#L14)

## `server.ts`

Adds request-time tracing to the Bun server transport without loading frontend
bindings. TanStack hydration is exposed by @relkit/client/server/tanstack-query
and requires that integration's documented frontend peers.

### createServerClient

Bun server client with operation-time W3C propagation. Response bodies remain untouched.

**Signature**

```ts
declare const createServerClient: <Contract extends RouterContract = RouterContract>(
  options: CreateClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/server.ts#L18)

## `tanstack-query.ts`

Reexports oRPC's query adapter without adding it to the transport dependency
graph. Install @orpc/tanstack-query@2.0.0-beta.31 and @tanstack/query-core@^5
alongside @relkit/client when selecting this entrypoint.

### TanstackQueryOperationContext

**Signature**

```ts
declare const TanstackQueryOperationContext: OperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/tanstack-query.ts#L7)

### createTanstackQueryUtils

**Signature**

```ts
declare const createTanstackQueryUtils: <T extends AnyNestedClient>(
  client: T,
  options?: NoInfer<RouterUtilsOptions<T>>,
) => RouterUtils<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/tanstack-query.ts#L6)

## `transport-native.ts`

### httpLink

Builds the native HTTP oRPC link with lazy headers and owned iterator cancellation.

**Signature**

```ts
declare const httpLink: (options: CreateClientOptions) => RPCLink<Record<PropertyKey, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport-native.ts#L20)

### webSocketEndpoint

Resolves the RPC WebSocket endpoint and canonical agent capability query.

**Signature**

```ts
declare const webSocketEndpoint: (baseUrl: string) => URL;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport-native.ts#L96)

### webSocketLink

Builds the native oRPC WebSocket link while retaining SDK reconnect ownership.

**Signature**

```ts
declare const webSocketLink: (
  options: CreateWebSocketClientOptions,
  Socket: typeof WebSocket,
  connect?: () => Promise<WebSocket>,
) => WebSocketRPCLink<Record<PropertyKey, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport-native.ts#L74)

## `transport-socket.ts`

### connectSocket

Establishes a socket through an interruptible Clock deadline and native callback.

**Signature**

```ts
declare const connectSocket: (
  Socket: typeof WebSocket,
  endpoint: URL,
  timeoutMs: number,
) => Promise<WebSocket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport-socket.ts#L12)

### connectSocketEffect

Owns establishment callbacks until socket ownership transfers to oRPC.

**Signature**

```ts
declare const connectSocketEffect: (
  Socket: {
    new (url: string | URL, options?: Bun.WebSocketOptions): WebSocket;
    new (url: string | URL, protocols?: string | string[]): WebSocket;
    prototype: WebSocket;
    readonly CONNECTING: 0;
    readonly OPEN: 1;
    readonly CLOSING: 2;
    readonly CLOSED: 3;
  },
  endpoint: URL,
  timeoutMs: number,
) => Effect.Effect<WebSocket, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport-socket.ts#L27)

## `transport.service.ts`

### ClientTransport (class)

Configured transport selection and invocation authority, without server dependencies.

**Signature**

```ts
declare class ClientTransport
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.service.ts#L10)

### clientTransportLayer

Acquires one link owner with a lazy, shared transport-selection decision.

**Example**

```ts
import { Effect, ManagedRuntime } from "effect";
import { runExecutionSync } from "@relkit/contracts/operation";
import { ClientTransport, clientTransportLayer } from "./transport.service.js";
export async function transportOwner(): Promise<void> {
  const owner = ManagedRuntime.make(clientTransportLayer(Effect.succeed({ call: async () => 1 })));
  try {
    const transport = runExecutionSync(owner, ClientTransport);
  } finally {
    await owner.dispose();
  }
}
```

**See**

- packages/client/tests/transport/examples.test.ts for executable ownership examples.

**Signature**

```ts
declare const clientTransportLayer: (
  select: Effect.Effect<TransportLink, unknown, Scope.Scope>,
) => Layer.Layer<ClientTransport>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.service.ts#L33)

### selectAutoTransport

Selects WebSocket once, falling back only when initial establishment fails.

**Signature**

```ts
declare const selectAutoTransport: (
  options: CreateAutoClientOptions,
) => Effect.Effect<
  RPCLink<Record<PropertyKey, unknown>> | RPCLink<Record<PropertyKey, unknown>>,
  never,
  Scope.Scope
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.service.ts#L79)

## `transport.ts`

### createClient

Creates the generated contract's synchronous HTTP proxy with a configured service owner.

**Example**

```ts
import { createClient } from "@relkit/client";
export const makeClient = () => createClient({ baseUrl: "http://127.0.0.1:3000" });
```

**Signature**

```ts
declare const createClient: <Contract extends RouterContract = RouterContract>(
  options: CreateClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.ts#L28)

Since v0.1.0

### createAutoClient

Creates a lazy proxy whose first transport choice is shared by concurrent calls.

**Signature**

```ts
declare const createAutoClient: <Contract extends RouterContract = RouterContract>(
  options: CreateAutoClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.ts#L54)

### createWebSocketClient

Creates a synchronous lazy WebSocket proxy, retaining constructor availability errors.

**Signature**

```ts
declare const createWebSocketClient: <Contract extends RouterContract = RouterContract>(
  options: CreateWebSocketClientOptions,
) => RouterContractClient<Contract>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.ts#L40)

## `transport.types.ts`

### ClientTransportService (interface)

One configured link-selection and invocation owner.

**Signature**

```ts
export interface ClientTransportService {
  /** Selects the owned link and invokes one declared procedure.
   * @param path - Exact generated procedure path segments.
   * @param input - Original request payload passed to the native link.
   * @param options - Existing oRPC context, cancellation and request options.
   * @returns A lazy observed invocation preserving the native result and error identity. */
  readonly invoke: (
    path: string[],
    input: unknown,
    options: ClientOptions<TransportContext>,
  ) => Effect.Effect<unknown, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.types.ts#L8)

### TransportContext (type alias)

Existing oRPC context retained without translating native error objects.

**Signature**

```ts
type TransportContext = Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.types.ts#L5)

### TransportLink (type alias)

Native link dependency supplied at transport acquisition.

**Signature**

```ts
type TransportLink = ClientLink<TransportContext>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/client/src/transport.types.ts#L22)

---

# Configuration API
Source: https://relkit.dev/docs/api/config

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineEnv](/docs/api/config#defineenv)

For configuration and examples, read [Environment contracts](/docs/learn/concepts/environment), [local docker](/docs/modules/database/local-docker), [define](/docs/modules/database/define).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/config` — 37 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                         | Kind  | Import from      | Example                                                                                                          |
| --------------------------------------------------------------------------- | ----- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| [BindingValueRef](/docs/api/provider#bindingvalueref-type-alias)            | Type  | `@relkit/config` | [Module example](/docs/learn/concepts/environment)                                                               |
| [ConfigOperation](/docs/api/config#configoperation-type-alias)              | Type  | `@relkit/config` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/config/tests/effect-telemetry.test.ts#L14) |
| [ConfigTelemetry](/docs/api/config#configtelemetry-class)                   | Value | `@relkit/config` | [API example](/docs/api/config#configtelemetry-class)                                                            |
| [ConfigTelemetryLive](/docs/api/config#configtelemetrylive)                 | Value | `@relkit/config` | [API example](/docs/api/config#configtelemetrylive)                                                              |
| [ConfigTelemetryService](/docs/api/config#configtelemetryservice-interface) | Type  | `@relkit/config` | [Module example](/docs/learn/concepts/environment)                                                               |
| [ConfigValidationError](/docs/api/config#configvalidationerror-class)       | Value | `@relkit/config` | [API example](/docs/api/config#configvalidationerror-class)                                                      |
| [createEnvRefEffect](/docs/api/config#createenvrefeffect)                   | Value | `@relkit/config` | [API example](/docs/api/config#createenvrefeffect)                                                               |
| [defineEnv](/docs/api/config#defineenv)                                     | Value | `@relkit/config` | [API example](/docs/api/config#defineenv)                                                                        |
| [defineEnvEffect](/docs/api/config#defineenveffect)                         | Value | `@relkit/config` | [API example](/docs/api/config#defineenveffect)                                                                  |
| [env](/docs/api/config#env)                                                 | Value | `@relkit/config` | [API example](/docs/api/config#env)                                                                              |
| [EnvBuilder](/docs/api/config#envbuilder-interface)                         | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilder-interface)                                                             |
| [EnvBuilderBase](/docs/api/config#envbuilderbase-interface)                 | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilderbase-interface)                                                         |
| [EnvBuilderFactory](/docs/api/config#envbuilderfactory-interface)           | Type  | `@relkit/config` | [API example](/docs/api/config#envbuilderfactory-interface)                                                      |
| [EnvDefinition](/docs/api/config#envdefinition-type-alias)                  | Type  | `@relkit/config` | [API example](/docs/api/config#envdefinition-type-alias)                                                         |
| [EnvIssue](/docs/api/config#envissue-interface)                             | Type  | `@relkit/config` | [API example](/docs/api/config#envissue-interface)                                                               |
| [EnvMetadata](/docs/api/config#envmetadata-interface)                       | Type  | `@relkit/config` | [API example](/docs/api/config#envmetadata-interface)                                                            |
| [EnvMetadataMap](/docs/api/config#envmetadatamap-type-alias)                | Type  | `@relkit/config` | [API example](/docs/api/config#envmetadatamap-type-alias)                                                        |
| [EnvProjection](/docs/api/config#envprojection-interface)                   | Type  | `@relkit/config` | [API example](/docs/api/config#envprojection-interface)                                                          |
| [EnvRef](/docs/api/config#envref-interface)                                 | Type  | `@relkit/config` | [API example](/docs/api/config#envref-interface)                                                                 |
| [EnvResolutionError](/docs/api/config#envresolutionerror-class)             | Value | `@relkit/config` | [API example](/docs/api/config#envresolutionerror-class)                                                         |
| [EnvShape](/docs/api/config#envshape-type-alias)                            | Type  | `@relkit/config` | [API example](/docs/api/config#envshape-type-alias)                                                              |
| [EnvSource](/docs/api/config#envsource-type-alias)                          | Type  | `@relkit/config` | [API example](/docs/api/config#envsource-type-alias)                                                             |
| [EnvValueType](/docs/api/config#envvaluetype-type-alias)                    | Type  | `@relkit/config` | [API example](/docs/api/config#envvaluetype-type-alias)                                                          |
| [InferEnvValue](/docs/api/config#inferenvvalue-type-alias)                  | Type  | `@relkit/config` | [API example](/docs/api/config#inferenvvalue-type-alias)                                                         |
| [InferEnvValues](/docs/api/config#inferenvvalues-type-alias)                | Type  | `@relkit/config` | [API example](/docs/api/config#inferenvvalues-type-alias)                                                        |
| [isBindingValueRef](/docs/api/provider#isbindingvalueref)                   | Value | `@relkit/config` | [API example](/docs/api/provider#isbindingvalueref)                                                              |
| [isEnvRef](/docs/api/config#isenvref)                                       | Value | `@relkit/config` | [API example](/docs/api/config#isenvref)                                                                         |
| [isEnvRefEffect](/docs/api/config#isenvrefeffect)                           | Value | `@relkit/config` | [API example](/docs/api/config#isenvrefeffect)                                                                   |
| [JsonValue](/docs/api/config#jsonvalue-type-alias)                          | Type  | `@relkit/config` | [API example](/docs/api/config#jsonvalue-type-alias)                                                             |
| [LiteralValue](/docs/api/config#literalvalue-type-alias)                    | Type  | `@relkit/config` | [API example](/docs/api/config#literalvalue-type-alias)                                                          |
| [parseEnvBuilderEffect](/docs/api/config#parseenvbuildereffect)             | Value | `@relkit/config` | [API example](/docs/api/config#parseenvbuildereffect)                                                            |
| [projectEnv](/docs/api/config#projectenv-1)                                 | Value | `@relkit/config` | [API example](/docs/api/config#projectenv-1)                                                                     |
| [projectEnvEffect](/docs/api/config#projectenveffect-1)                     | Value | `@relkit/config` | [API example](/docs/api/config#projectenveffect-1)                                                               |
| [ResolvedEnv](/docs/api/config#resolvedenv-type-alias)                      | Type  | `@relkit/config` | [API example](/docs/api/config#resolvedenv-type-alias)                                                           |
| [resolveEnv](/docs/api/config#resolveenv-1)                                 | Value | `@relkit/config` | [API example](/docs/api/config#resolveenv-1)                                                                     |
| [resolveEnvEffect](/docs/api/config#resolveenveffect-1)                     | Value | `@relkit/config` | [API example](/docs/api/config#resolveenveffect-1)                                                               |
| [ResolveEnvOptions](/docs/api/config#resolveenvoptions-interface)           | Type  | `@relkit/config` | [API example](/docs/api/config#resolveenvoptions-interface)                                                      |

## `config-observability.ts`

### ConfigOperation

**Signature**

```ts
declare const ConfigOperation: ConfigOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L4)

### ConfigTelemetry (class)

Injectable telemetry for environment operations.

**Example**

```ts
Effect.provide(resolveEnvEffect(definition, options), ConfigTelemetryLive);
```

**Signature**

```ts
declare class ConfigTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L9)

### ConfigTelemetryLive

Live spans and bounded operation metrics.

**Example**

```ts
Effect.runSync(Effect.provide(projectEnvEffect(definition), ConfigTelemetryLive));
```

**Signature**

```ts
declare const ConfigTelemetryLive: Layer.Layer<ConfigTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L16)

### ConfigTelemetryService

**Signature**

```ts
declare const ConfigTelemetryService: ConfigTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L4)

### observeConfig

Observe an Effect operation with a stable span and operation metrics.

**Example**

```ts
observeConfig("project", Effect.succeed([]));
```

**Signature**

```ts
declare const observeConfig: <A, E, R>(
  operation: ConfigOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L30)

### runConfigSync

Run a synchronous compatibility adapter while retaining its original failure.

**Throws**

The domain error, original defect, or mapped compatibility TypeError.

**Example**

```ts
runConfigSync(Effect.succeed("ready"));
```

**Signature**

```ts
declare const runConfigSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.ts#L69)

## `config-observability.types.ts`

### ConfigOperation (type alias)

Stable, bounded names for environment configuration operations.

**Signature**

```ts
type ConfigOperation =
  | "define"
  | "resolve"
  | "resolve-provider"
  | "project"
  | "is-ref"
  | "create-ref"
  | "json-value"
  | "parse-number"
  | "parse-port"
  | "parse-boolean"
  | "parse-literal"
  | "builder-create"
  | "builder-get-default"
  | "builder-parse"
  | "builder-literal"
  | "builder-or-binding"
  | "parse-url"
  | "parse-json"
  | "builder-default"
  | "builder-optional"
  | "builder-required-in"
  | "builder-description"
  | "builder-example";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.types.ts#L4)

### ConfigTelemetryService (interface)

Substitutable observer used by the config Effect operations.

**Signature**

```ts
export interface ConfigTelemetryService {
  /** Observe one operation without changing its success or error.
   * @param operation - Stable bounded operation name.
   * @param effect - Effect to instrument.
   * @returns The original Effect success and error channels.
   * @example observe("resolve", Effect.succeed({ MODE: "test" }));
   */
  readonly observe: <A, E, R>(
    operation: ConfigOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-observability.types.ts#L30)

## `config-validation-error.ts`

### ConfigValidationError (class)

Expected invalid config declaration or value with a stable failure tag.

**Example**

```ts
new ConfigValidationError({ message: "Expected a finite number" });
```

**Signature**

```ts
declare class ConfigValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/config-validation-error.ts#L6)

## `env-builder-metadata.ts`

### metadata

Build initial immutable metadata inside the observed builder creation.

**Example**

```ts
metadata("string", false);
```

**Signature**

```ts
declare const metadata: (
  type: EnvValueType,
  sensitive: boolean,
  values?: readonly LiteralValue[],
) => EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder-metadata.ts#L10)

### updateMetadata

Copy metadata inside an observed fluent builder operation.

**Example**

```ts
updateMetadata(env.string().metadata, { optional: true });
```

**Signature**

```ts
declare const updateMetadata: (value: EnvMetadata, changes: Record<string, unknown>) => EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder-metadata.ts#L31)

## `env-builder.ts`

### createEnvBuilder

Create a field builder synchronously for existing callers.

**Example**

```ts
createEnvBuilder("string", (value) => value);
```

**Signature**

```ts
declare const createEnvBuilder: <T>(
  type: EnvValueType,
  parse: Parse<T>,
  sensitive?: boolean,
  values?: readonly LiteralValue[],
) => EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L190)

### createEnvBuilderEffect

Create a frozen field builder through the Effect path.

**Example**

```ts
Effect.runSync(createEnvBuilderEffect("string", (value) => value));
```

**Signature**

```ts
declare const createEnvBuilderEffect: <T>(
  type: EnvValueType,
  parse: Parse<T>,
  sensitive?: boolean,
  values?: readonly LiteralValue[],
) => Effect.Effect<EnvBuilder<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L170)

### parseEnvBuilderEffect

Parse a builder's raw input through an observable, typed Effect.

**Example**

```ts
Effect.runSync(parseEnvBuilderEffect(Number, "2"));
```

**Signature**

```ts
declare const parseEnvBuilderEffect: <T>(
  parse: Parse<T>,
  value: string,
) => Effect.Effect<Exclude<T, undefined>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.ts#L131)

## `env-builder.types.ts`

Synchronous parser type retained for public field compatibility.

**Example**

```ts
const parse: Parse<number> = Number;
```

### DefaultFactory (type alias)

Lazy default factory type invoked only when source input is absent.

**Example**

```ts
const fallback: DefaultFactory<string> = () => "test";
```

**Signature**

```ts
type DefaultFactory<T> = () => Exclude<T, undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.types.ts#L9)

### Parse (type alias)

Synchronous parser type retained for public field compatibility.

**Example**

```ts
const parse: Parse<number> = Number;
```

**Signature**

```ts
type Parse<T> = (value: string) => Exclude<T, undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-builder.types.ts#L4)

## `env-factory.ts`

### bindingOrBuilderEffect

Build an environment field or a named binding reference.

**Example**

```ts
Effect.runSync(bindingOrBuilderEffect(undefined, "string", (value) => value));
```

**Signature**

```ts
declare const bindingOrBuilderEffect: <Value>(
  name: string | undefined,
  type: BindingValueType,
  parse: (value: string) => Exclude<Value, undefined>,
  sensitive?: boolean,
) => Effect.Effect<EnvBuilder<Value> | BindingValueRef<string, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L80)

### env

Factory of value-free fields and named binding-local references.

**Example**

```ts
const declaration = defineEnv({ MODE: env.string() });
```

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L14)

### literalBuilderEffect

Build a literal field while rejecting non-finite choices.

**Example**

```ts
Effect.runSync(literalBuilderEffect("test", "prod"));
```

**Signature**

```ts
declare const literalBuilderEffect: <
  const Values extends readonly [LiteralValue, ...LiteralValue[]],
>(
  ...values: Values
) => Effect.Effect<EnvBuilder<Values[number]>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L50)

### parseJsonEffect

Parse JSON and normalize it to immutable metadata-safe values.

**Example**

```ts
Effect.runSync(parseJsonEffect('{"count":2}'));
```

**Signature**

```ts
declare const parseJsonEffect: (
  value: string,
) => Effect.Effect<JsonValue, ConfigValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L125)

### parseUrlEffect

Parse a URL with a tagged failure for malformed input.

**Example**

```ts
Effect.runSync(parseUrlEffect("https://example.test"));
```

**Signature**

```ts
declare const parseUrlEffect: (value: string) => Effect.Effect<URL, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.ts#L100)

## `env-factory.types.ts`

### EnvBuilderFactory (interface)

Public overloads for field builders and named binding references.
Calling without a name declares a field; passing a name creates a binding reference.

**Example**

```ts
const mode = env.string();
const cache = env.secret("CACHE_URL");
```

**Signature**

```ts
export interface EnvBuilderFactory {
  /** Declare a string field.
   * @returns A string builder.
   * @example env.string();
   */
  string(): EnvBuilder<string>;
  /** Reference a named string binding.
   * @param name - Binding environment name.
   * @returns A value-free string binding reference.
   * @example env.string("MODE");
   */
  string<const Name extends string>(name: Name): BindingValueRef<Name, string, "string">;
  /** Declare a finite number field.
   * @returns A number builder.
   * @example env.number();
   */
  number(): EnvBuilder<number>;
  /** Reference a named number binding.
   * @param name - Binding environment name.
   * @returns A number binding reference.
   * @example env.number("RETRIES");
   */
  number<const Name extends string>(name: Name): BindingValueRef<Name, number, "number">;
  /** Declare an exact Boolean field.
   * @returns A Boolean builder.
   * @example env.boolean();
   */
  boolean(): EnvBuilder<boolean>;
  /** Reference a named Boolean binding.
   * @param name - Binding environment name.
   * @returns A Boolean binding reference.
   * @example env.boolean("ENABLED");
   */
  boolean<const Name extends string>(name: Name): BindingValueRef<Name, boolean, "boolean">;
  /** Declare a TCP port field.
   * @returns A port builder.
   * @example env.port();
   */
  port(): EnvBuilder<number>;
  /** Reference a named port binding.
   * @param name - Binding environment name.
   * @returns A port binding reference.
   * @example env.port("SERVICE_PORT");
   */
  port<const Name extends string>(name: Name): BindingValueRef<Name, number, "port">;
  /** Declare finite literal choices.
   * @param values - Nonempty list of allowed choices.
   * @returns A literal builder.
   * @throws TypeError when a numeric choice is not finite.
   * @example env.literal("test", "production");
   */
  literal<const Values extends readonly [LiteralValue, ...LiteralValue[]]>(
    ...values: Values
  ): EnvBuilder<Values[number]>;
  /** Declare a URL field.
   * @returns A URL builder.
   * @example env.url();
   */
  url(): EnvBuilder<URL>;
  /** Reference a named URL binding.
   * @param name - Binding environment name.
   * @returns A URL binding reference.
   * @example env.url("ORIGIN");
   */
  url<const Name extends string>(name: Name): BindingValueRef<Name, URL, "url">;
  /** Declare a JSON field.
   * @returns A JSON builder.
   * @example env.json();
   */
  json(): EnvBuilder<JsonValue>;
  /** Reference a named JSON binding.
   * @param name - Binding environment name.
   * @returns A JSON binding reference.
   * @example env.json("SETTINGS");
   */
  json<const Name extends string>(name: Name): BindingValueRef<Name, JsonValue, "json">;
  /** Declare a sensitive string field.
   * @returns A secret string builder.
   * @example env.secret();
   */
  secret(): EnvBuilder<string>;
  /** Reference a named secret binding.
   * @param name - Binding environment name.
   * @returns A secret binding reference.
   * @example env.secret("API_TOKEN");
   */
  secret<const Name extends string>(name: Name): BindingValueRef<Name, string, "secret-string">;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-factory.types.ts#L9)

## `env-json.ts`

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L6)

### toJsonValue

Convert an example synchronously for existing callers.

**Throws**

TypeError for unsupported values or accessors.

**Example**

```ts
toJsonValue({ count: 2 });
```

**Signature**

```ts
declare const toJsonValue: (value: unknown) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L23)

### toJsonValueEffect

Convert declaration examples to immutable, JSON-safe values.

**Example**

```ts
Effect.runSync(toJsonValueEffect({ count: 2 }));
```

**Signature**

```ts
declare const toJsonValueEffect: (
  value: unknown,
) => Effect.Effect<JsonValue, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.ts#L13)

## `env-json.types.ts`

Deeply JSON-safe value suitable for declaration metadata.

**Example**

```ts
const example: JsonValue = { enabled: true };
```

### JsonValue (type alias)

Deeply JSON-safe value suitable for declaration metadata.

**Example**

```ts
const example: JsonValue = { enabled: true };
```

**Signature**

```ts
type JsonValue =
  string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-json.types.ts#L4)

## `env-parsers.ts`

### parseBoolean

Parse an exact Boolean synchronously.

**Throws**

TypeError for any other token.

**Example**

```ts
parseBoolean("false");
```

**Signature**

```ts
declare const parseBoolean: (value: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L88)

### parseBooleanEffect

Parse an exact Boolean environment token.

**Example**

```ts
Effect.runSync(parseBooleanEffect("true"));
```

**Signature**

```ts
declare const parseBooleanEffect: (value: string) => Effect.Effect<boolean, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L71)

### parseLiteral

Match a literal synchronously.

**Throws**

TypeError when there is no match.

**Example**

```ts
parseLiteral("test", ["test", "prod"]);
```

**Signature**

```ts
declare const parseLiteral: <T extends LiteralValue>(value: string, values: readonly T[]) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L123)

### parseLiteralEffect

Match a raw value against declared literal choices.

**Example**

```ts
Effect.runSync(parseLiteralEffect("test", ["test", "prod"]));
```

**Signature**

```ts
declare const parseLiteralEffect: <T extends LiteralValue>(
  value: string,
  values: readonly T[],
) => Effect.Effect<T, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L98)

### parseNumber

Parse a finite number synchronously.

**Throws**

TypeError when the value is not finite.

**Example**

```ts
parseNumber("42");
```

**Signature**

```ts
declare const parseNumber: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L32)

### parseNumberEffect

Parse a finite number from an environment string.

**Example**

```ts
Effect.runSync(parseNumberEffect("42"));
```

**Signature**

```ts
declare const parseNumberEffect: (value: string) => Effect.Effect<number, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L11)

### parsePort

Parse a TCP port synchronously.

**Throws**

TypeError for an invalid port.

**Example**

```ts
parsePort("3000");
```

**Signature**

```ts
declare const parsePort: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L62)

### parsePortEffect

Parse a TCP port from an environment string.

**Example**

```ts
Effect.runSync(parsePortEffect("3000"));
```

**Signature**

```ts
declare const parsePortEffect: (value: string) => Effect.Effect<number, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-parsers.ts#L41)

## `env-ref.ts`

### createEnvRef

Create a field reference synchronously for a declaration.

**Example**

```ts
createEnvRef("MODE", env.string());
```

**Signature**

```ts
declare const createEnvRef: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L65)

### createEnvRefEffect

Create an immutable typed field reference.

**Example**

```ts
Effect.runSync(createEnvRefEffect("MODE", env.string()));
```

**Signature**

```ts
declare const createEnvRefEffect: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => Effect.Effect<EnvRef<Name, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L40)

### isEnvRef

Check a reference synchronously for existing callers.

**Example**

```ts
isEnvRef(definition.MODE);
```

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L30)

### isEnvRefEffect

Check whether a value is a typed environment reference.

**Example**

```ts
Effect.runSync(isEnvRefEffect(definition.MODE));
```

**Signature**

```ts
declare const isEnvRefEffect: (value: unknown) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-ref.ts#L10)

## `env-resolution-error.ts`

### EnvResolutionError (class)

Tagged failure containing ordered field issues.

**Example**

```ts
new EnvResolutionError([
  { name: "TOKEN", code: "missing", message: "Required value is missing", sensitive: true },
]);
```

**Signature**

```ts
declare class EnvResolutionError {
  constructor(issues: readonly EnvIssue[]);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-resolution-error.ts#L7)

### name (property)

**Signature**

```ts
readonly name: "EnvResolutionError"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env-resolution-error.ts#L11)

## `env.ts`

### defineEnv

Build a declaration synchronously for existing callers.

**Throws**

TypeError for a reserved name or invalid builder.

**Example**

```ts
import { defineEnv, env } from "@relkit/config";
const environment = defineEnv({ MODE: env.string().default("development") });
```

**Signature**

```ts
declare const defineEnv: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L105)

Since v0.1.0

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L14)

### EnvBuilder

**Signature**

```ts
declare const EnvBuilder: EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L11)

### EnvBuilderBase

**Signature**

```ts
declare const EnvBuilderBase: EnvBuilderBase;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L12)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L13)

### EnvDefinition

**Signature**

```ts
declare const EnvDefinition: EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L15)

### EnvMetadata

**Signature**

```ts
declare const EnvMetadata: EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L16)

### EnvMetadataMap

**Signature**

```ts
declare const EnvMetadataMap: EnvMetadataMap<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L17)

### EnvRef

**Signature**

```ts
declare const EnvRef: EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L20)

### EnvShape

**Signature**

```ts
declare const EnvShape: EnvShape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L18)

### EnvValueType

**Signature**

```ts
declare const EnvValueType: EnvValueType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L19)

### InferEnvValue

**Signature**

```ts
declare const InferEnvValue: InferEnvValue<B>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L21)

### InferEnvValues

**Signature**

```ts
declare const InferEnvValues: InferEnvValues<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L22)

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L9)

### LiteralValue

**Signature**

```ts
declare const LiteralValue: LiteralValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L23)

### defineEnvEffect

Build an immutable declaration without reading runtime values.

**Example**

```ts
Effect.runSync(defineEnvEffect({ MODE: env.string() }));
```

**Signature**

```ts
declare const defineEnvEffect: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => Effect.Effect<EnvDefinition<S>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L31)

### env

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L7)

### isEnvRef

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.ts#L8)

## `env.types.ts`

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L3)

### EnvBuilder (interface)

Value-free field declaration with immutable fluent metadata methods.
Every method returns a new frozen builder; the original remains unchanged.

**Example**

```ts
const mode = env.string().default("test").description("Runtime mode");
```

**Signature**

```ts
export interface EnvBuilder<T> extends EnvBuilderBase {
  readonly parse: (value: string) => Exclude<T, undefined>;
  readonly getDefault: () => Exclude<T, undefined> | undefined;
  /** Attach a lazy or literal default.
   * @param value - Default literal or factory, invoked during resolution.
   * @returns A new builder whose value is required when present.
   * @example env.string().default("test");
   */
  default(
    value: Exclude<T, undefined> | (() => Exclude<T, undefined>),
  ): EnvBuilder<Exclude<T, undefined>>;
  /** Allow absence outside explicitly required environments.
   * @returns A new builder whose value may be undefined.
   * @example env.string().optional();
   */
  optional(): EnvBuilder<T | undefined>;
  /** Require the field in named environments.
   * @param environments - Environment names, with duplicates removed.
   * @returns A new builder with merged requirement metadata.
   * @throws TypeError when a name is empty.
   * @example env.string().requiredIn("production");
   */
  requiredIn(...environments: readonly string[]): EnvBuilder<T>;
  /** Add human-readable field guidance.
   * @param text - Description shown in metadata.
   * @returns A new builder with a description.
   * @example env.string().description("Public origin");
   */
  description(text: string): EnvBuilder<T>;
  /** Add a JSON-safe example, redacting sensitive fields.
   * @param value - Example value.
   * @returns A new builder with example metadata.
   * @throws TypeError when a public example is not JSON-safe.
   * @example env.url().example(new URL("https://example.test"));
   */
  example(value: T): EnvBuilder<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L71)

### EnvBuilderBase (interface)

Minimum builder contract used during resolution.
`parse` and `getDefault` remain synchronous compatibility callbacks.

**Example**

```ts
const field: EnvBuilderBase = env.string();
```

**Signature**

```ts
export interface EnvBuilderBase {
  readonly kind: "env-builder";
  readonly metadata: EnvMetadata;
  /** Parse a raw string through the field's Effect-backed compatibility adapter.
   * @param value - Raw environment value.
   * @returns Parsed field value.
   * @throws TypeError for invalid built-in values; custom parsers may throw.
   * @example env.number().parse("2");
   */
  readonly parse: (value: string) => unknown;
  /** Produce a lazy default only when resolution needs it.
   * @returns Default value or undefined.
   * @throws A user default factory's original error.
   * @example env.string().default("test").getDefault();
   */
  readonly getDefault: () => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L49)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L4)

### EnvDefinition (type alias)

Immutable, value-free declaration returned by `defineEnv`.
Field references are non-enumerable; shape and metadata are frozen.

**Example**

```ts
const declaration: EnvDefinition<{ MODE: EnvBuilder<string> }> = defineEnv({ MODE: env.string() });
```

**Signature**

```ts
type EnvDefinition<S extends EnvShape> = {
  readonly kind: "env-definition";
  readonly shape: S;
  readonly metadata: EnvMetadataMap<S>;
} & {
  readonly [K in keyof S]: EnvRef<K & string, InferEnvValue<S[K]>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L134)

### EnvMetadata (interface)

JSON-safe metadata emitted by an environment declaration.
Defaults are represented by `hasDefault` and never exposed here.

**Example**

```ts
const metadata = env.secret().metadata;
```

**Signature**

```ts
export interface EnvMetadata {
  readonly type: EnvValueType;
  readonly requiredIn: readonly string[];
  readonly hasDefault: boolean;
  readonly optional: boolean;
  readonly sensitive: boolean;
  readonly values?: readonly LiteralValue[];
  readonly description?: string;
  readonly example?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L21)

### EnvMetadataMap (type alias)

Infer a metadata map from a declaration shape.

**Example**

```ts
type Metadata = EnvMetadataMap<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type EnvMetadataMap<S extends EnvShape> = {
  readonly [K in keyof S]: EnvMetadata;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L126)

### EnvRef (interface)

Typed, value-free reference to one declared variable.
`__value` is phantom typing; the declaration never reads source values.

**Example**

```ts
const reference = defineEnv({ MODE: env.string() }).MODE;
```

**Signature**

```ts
export interface EnvRef<Name extends string = string, Value = unknown> {
  readonly kind: "env-ref";
  readonly name: Name;
  readonly type: EnvValueType;
  readonly sensitive: boolean;
  readonly metadata: EnvMetadata;
  readonly __value?: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L36)

### EnvShape (type alias)

Map field names to builders without reading runtime values.

**Example**

```ts
const shape: EnvShape = { MODE: env.string() };
```

**Signature**

```ts
type EnvShape = { readonly [name: string]: EnvBuilderBase };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L112)

### EnvValueType (type alias)

Stable field type emitted in metadata.

**Example**

```ts
const type: EnvValueType = "secret-string";
```

**Signature**

```ts
type EnvValueType =
  "string" | "number" | "boolean" | "port" | "literal" | "url" | "json" | "secret-string";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L14)

### InferEnvValue (type alias)

Extract a field builder's resolved value type.

**Example**

```ts
type Mode = InferEnvValue<ReturnType<typeof env.string>>;
```

**Signature**

```ts
type InferEnvValue<B> = B extends EnvBuilder<infer T> ? T : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L116)

### InferEnvValues (type alias)

Infer the immutable runtime value object from a declaration shape.

**Example**

```ts
type Values = InferEnvValues<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type InferEnvValues<S extends EnvShape> = {
  readonly [K in keyof S]: InferEnvValue<S[K]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L120)

### LiteralValue (type alias)

Scalar literals accepted by `env.literal`.

**Example**

```ts
env.literal("test", "production");
```

**Signature**

```ts
type LiteralValue = string | number | boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/env.types.ts#L9)

## `index.ts`

### BindingValueRef

**Signature**

```ts
declare const BindingValueRef: BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L9)

### ConfigOperation

**Signature**

```ts
declare const ConfigOperation: ConfigOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L4)

### ConfigTelemetry

**Signature**

```ts
declare const ConfigTelemetry: typeof ConfigTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L3)

### ConfigTelemetryLive

**Signature**

```ts
declare const ConfigTelemetryLive: Layer<ConfigTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L3)

### ConfigTelemetryService

**Signature**

```ts
declare const ConfigTelemetryService: ConfigTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L4)

### ConfigValidationError

**Signature**

```ts
declare const ConfigValidationError: typeof ConfigValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L5)

### EnvBuilder

**Signature**

```ts
declare const EnvBuilder: EnvBuilder<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L10)

### EnvBuilderBase

**Signature**

```ts
declare const EnvBuilderBase: EnvBuilderBase;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L11)

### EnvBuilderFactory

**Signature**

```ts
declare const EnvBuilderFactory: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L12)

### EnvDefinition

**Signature**

```ts
declare const EnvDefinition: EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L13)

### EnvIssue

**Signature**

```ts
declare const EnvIssue: EnvIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L32)

### EnvMetadata

**Signature**

```ts
declare const EnvMetadata: EnvMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L14)

### EnvMetadataMap

**Signature**

```ts
declare const EnvMetadataMap: EnvMetadataMap<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L15)

### EnvProjection

**Signature**

```ts
declare const EnvProjection: EnvProjection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L33)

### EnvRef

**Signature**

```ts
declare const EnvRef: EnvRef<Name, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L18)

### EnvResolutionError

**Signature**

```ts
declare const EnvResolutionError: typeof EnvResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L25)

### EnvShape

**Signature**

```ts
declare const EnvShape: EnvShape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L16)

### EnvSource

**Signature**

```ts
declare const EnvSource: Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L34)

### EnvValueType

**Signature**

```ts
declare const EnvValueType: EnvValueType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L17)

### InferEnvValue

**Signature**

```ts
declare const InferEnvValue: InferEnvValue<B>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L19)

### InferEnvValues

**Signature**

```ts
declare const InferEnvValues: InferEnvValues<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L20)

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L21)

### LiteralValue

**Signature**

```ts
declare const LiteralValue: LiteralValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L22)

### ResolveEnvOptions

**Signature**

```ts
declare const ResolveEnvOptions: ResolveEnvOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L35)

### ResolvedEnv

**Signature**

```ts
declare const ResolvedEnv: Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L36)

### createEnvRefEffect

**Signature**

```ts
declare const createEnvRefEffect: <Name extends string, Value>(
  name: Name,
  field: EnvBuilderBase,
) => Effect<EnvRef<Name, Value>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L2)

### defineEnv

**Signature**

```ts
declare const defineEnv: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => EnvDefinition<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### defineEnvEffect

**Signature**

```ts
declare const defineEnvEffect: <const S extends EnvShape>(
  shape: S & { readonly PORT?: never; readonly RELKIT_ENV?: never },
) => Effect<EnvDefinition<S>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### env

**Signature**

```ts
declare const env: EnvBuilderFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### isBindingValueRef

**Signature**

```ts
declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L7)

### isEnvRef

**Signature**

```ts
declare const isEnvRef: (value: unknown) => value is EnvRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L1)

### isEnvRefEffect

**Signature**

```ts
declare const isEnvRefEffect: (value: unknown) => Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L2)

### parseEnvBuilderEffect

**Signature**

```ts
declare const parseEnvBuilderEffect: <T>(
  parse: Parse<T>,
  value: string,
) => Effect<Exclude<T, undefined>, ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L6)

### projectEnv

**Signature**

```ts
declare const projectEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => readonly EnvProjection[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L26)

### projectEnvEffect

**Signature**

```ts
declare const projectEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => Effect<readonly EnvProjection[], ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L27)

### resolveEnv

**Signature**

```ts
declare const resolveEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => ResolvedEnv<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L28)

### resolveEnvEffect

**Signature**

```ts
declare const resolveEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => Effect<ResolvedEnv<S>, ConfigValidationError | EnvResolutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/index.ts#L29)

## `config.ts`

### resolveEnvWithEffect

Promise compatibility adapter for the internal ConfigProvider bridge.

**Example**

```ts
await resolveEnvWithEffect(definition, { MODE: "test" }, "test");
```

**Signature**

```ts
declare const resolveEnvWithEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  source: EnvSource,
  environment: string,
) => Promise<ResolvedEnv<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/internal/config.ts#L39)

### resolveEnvWithEffectEffect

Resolve through an explicit Effect ConfigProvider.

**Example**

```ts
Effect.runPromise(resolveEnvWithEffectEffect(definition, { MODE: "test" }, "test"));
```

**Signature**

```ts
declare const resolveEnvWithEffectEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  source: EnvSource,
  environment: string,
) => Effect.Effect<ResolvedEnv<S>, Config.ConfigError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/internal/config.ts#L18)

## `resolve-helpers.ts`

### definitionIssue

Check the declaration shape before reading field callbacks.

**Example**

```ts
definitionIssue(defineEnv({ MODE: env.string() }));
```

**Signature**

```ts
declare const definitionIssue: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L9)

### optionsIssue

Check an explicit environment name and source map.

**Example**

```ts
optionsIssue({ environment: "test", source: {} });
```

**Signature**

```ts
declare const optionsIssue: (options: ResolveEnvOptions) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L31)

### resolveField

Resolve one field while appending issues in declaration order.

**Example**

```ts
resolveField("MODE", env.string(), { MODE: "test" }, "test", values, issues);
```

**Signature**

```ts
declare const resolveField: (
  name: string,
  builder: EnvBuilderBase,
  source: EnvSource,
  environment: string,
  values: Record<string, unknown>,
  issues: EnvIssue[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve-helpers.ts#L54)

## `resolve.ts`

### EnvIssue

**Signature**

```ts
declare const EnvIssue: EnvIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L11)

### EnvProjection

**Signature**

```ts
declare const EnvProjection: EnvProjection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L12)

### EnvResolutionError

**Signature**

```ts
declare const EnvResolutionError: typeof EnvResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L9)

### EnvSource

**Signature**

```ts
declare const EnvSource: Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L13)

### ResolveEnvOptions

**Signature**

```ts
declare const ResolveEnvOptions: ResolveEnvOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L14)

### ResolvedEnv

**Signature**

```ts
declare const ResolvedEnv: Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L15)

### projectEnv

Project metadata synchronously for existing callers.

**Throws**

TypeError for a malformed definition.

**Example**

```ts
projectEnv(defineEnv({ MODE: env.string() }));
```

**Signature**

```ts
declare const projectEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => readonly EnvProjection[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L97)

### projectEnvEffect

Project sorted, JSON-safe metadata without source values.

**Example**

```ts
Effect.runSync(projectEnvEffect(defineEnv({ MODE: env.string() })));
```

**Signature**

```ts
declare const projectEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
) => Effect.Effect<readonly EnvProjection[], ConfigValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L74)

### resolveEnv

Resolve a declaration synchronously for existing callers.

**Throws**

TypeError for invalid inputs; EnvResolutionError for field issues.

**Example**

```ts
resolveEnv(defineEnv({ MODE: env.string() }), { environment: "test", source: { MODE: "ready" } });
```

**Signature**

```ts
declare const resolveEnv: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => ResolvedEnv<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L62)

### resolveEnvEffect

Resolve all declared values with ordered, typed failures.

**Example**

```ts
Effect.runSync(
  resolveEnvEffect(defineEnv({ MODE: env.string() }), {
    environment: "test",
    source: { MODE: "ready" },
  }),
);
```

**Signature**

```ts
declare const resolveEnvEffect: <S extends EnvShape>(
  definition: EnvDefinition<S>,
  options: ResolveEnvOptions,
) => Effect.Effect<ResolvedEnv<S>, ConfigValidationError | EnvResolutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.ts#L24)

## `resolve.types.ts`

### EnvIssue (interface)

One invalid or missing declared field.
Sensitive messages are redacted before an issue is exposed.

**Example**

```ts
const issue: EnvIssue = {
  name: "MODE",
  code: "missing",
  message: "Required value is missing",
  sensitive: false,
};
```

**Signature**

```ts
export interface EnvIssue {
  readonly name: string;
  readonly code: "missing" | "invalid";
  readonly message: string;
  readonly sensitive: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L20)

### EnvProjection (interface)

Public, value-free metadata for one field.

**Example**

```ts
const fields: readonly EnvProjection[] = projectEnv(definition);
```

**Signature**

```ts
export interface EnvProjection extends EnvMetadata {
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L35)

### EnvSource (type alias)

Explicit source values; resolution never reads the process environment.

**Example**

```ts
const source: EnvSource = { MODE: "test" };
```

**Signature**

```ts
type EnvSource = Readonly<Record<string, string | undefined>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L6)

### ResolveEnvOptions (interface)

Inputs for resolving an environment declaration.

**Example**

```ts
const options: ResolveEnvOptions = { environment: "test", source: {} };
```

**Signature**

```ts
export interface ResolveEnvOptions {
  readonly environment: string;
  readonly source: EnvSource;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L11)

### ResolvedEnv (type alias)

Immutable values inferred from a declaration shape.

**Example**

```ts
type Values = ResolvedEnv<{ MODE: EnvBuilder<string> }>;
```

**Signature**

```ts
type ResolvedEnv<S extends EnvShape> = Readonly<InferEnvValues<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/config/src/resolve.types.ts#L30)

---

# Project generator API
Source: https://relkit.dev/docs/api/create-relkit

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [automation](/docs/modules/cli/automation).

## Public imports

- `create-relkit` — 113 exports
- `create-relkit/cli` — 1 exports
- `create-relkit/launcher` — 1 exports
- `create-relkit/catalog-resolution` — 2 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                            | Kind  | Import from                                         | Example                                                                                                                                    |
| ---------------------------------------------------------------------------------------------- | ----- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| [ADD_FAILURE_CODES](/docs/api/create-relkit#add_failure_codes)                                 | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches-asset.cases.ts#L67)         |
| [ADD_KINDS](/docs/api/create-relkit#add_kinds)                                                 | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddFailureCode](/docs/api/create-relkit#addfailurecode-type-alias)                            | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddKind](/docs/api/create-relkit#addkind-type-alias)                                          | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddRequest](/docs/api/create-relkit#addrequest-type-alias)                                    | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddRequestBase](/docs/api/create-relkit#addrequestbase-interface)                             | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddResult](/docs/api/create-relkit#addresult-interface)                                       | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [AddScaffoldError](/docs/api/create-relkit#addscaffolderror-class)                             | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/native-transaction.fixture.ts#L99)             |
| [assertCreateCapability](/docs/api/create-relkit#assertcreatecapability)                       | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L22)                 |
| [CatalogManifest](/docs/api/create-relkit#catalogmanifest-type-alias)                          | Type  | `create-relkit`, `create-relkit/catalog-resolution` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ChoicePromptOptions](/docs/api/create-relkit#choicepromptoptions-interface)                   | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_CAPABILITY_TABLE](/docs/api/create-relkit#create_capability_table)                     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L12)                 |
| [CREATE_CLOUDS](/docs/api/create-relkit#create_clouds)                                         | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_DEPLOYMENTS](/docs/api/create-relkit#create_deployments)                               | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_JOBS](/docs/api/create-relkit#create_jobs)                                             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CREATE_OPTION_DEFAULTS](/docs/api/create-relkit#create_option_defaults)                       | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/fixtures/inspector/generated-app.ts#L18)                                |
| [CREATE_TEMPLATES](/docs/api/create-relkit#create_templates)                                   | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix.test.ts#L21)                                    |
| [CreateCapabilityEvidence](/docs/api/create-relkit#createcapabilityevidence-interface)         | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCapabilityIdentity](/docs/api/create-relkit#createcapabilityidentity-interface)         | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCapabilityTuple](/docs/api/create-relkit#createcapabilitytuple-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [createClackPromptDriver](/docs/api/create-relkit#createclackpromptdriver)                     | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateCloud](/docs/api/create-relkit#createcloud-type-alias)                                  | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateDeployment](/docs/api/create-relkit#createdeployment-type-alias)                        | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [createGenerateNextSteps](/docs/api/create-relkit#creategeneratenextsteps)                     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/generation-output.effect.test.ts#L12)            |
| [CreateJobs](/docs/api/create-relkit#createjobs-type-alias)                                    | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateOptions](/docs/api/create-relkit#createoptions-interface)                               | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix-fixture.ts#L25)                                 |
| [CreateOptionsContext](/docs/api/create-relkit#createoptionscontext-interface)                 | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateOptionsError](/docs/api/create-relkit#createoptionserror-class)                         | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateScaffoldPlan](/docs/api/create-relkit#createscaffoldplan-interface)                     | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateTemplate](/docs/api/create-relkit#createtemplate-type-alias)                            | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateValidationContext](/docs/api/create-relkit#createvalidationcontext-interface)           | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [CreateValidationError](/docs/api/create-relkit#createvalidationerror-class)                   | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [currentCreateCapabilityIdentity](/docs/api/create-relkit#currentcreatecapabilityidentity)     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L23)                 |
| [DatabaseDialect](/docs/api/create-relkit#databasedialect-type-alias)                          | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [DependencySection](/docs/api/create-relkit#dependencysection-type-alias)                      | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [domainError](/docs/api/create-relkit#domainerror)                                             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [domainTry](/docs/api/create-relkit#domaintry)                                                 | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/observation.effect.test.ts#L83)                  |
| [errorMessage](/docs/api/create-relkit#errormessage)                                           | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [formatCreatePlan](/docs/api/create-relkit#formatcreateplan)                                   | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [formatGenerateResult](/docs/api/create-relkit#formatgenerateresult)                           | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/generation-output.effect.test.ts#L14)            |
| [GenerateCommandResult](/docs/api/create-relkit#generatecommandresult-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GenerateCommandRunner](/docs/api/create-relkit#generatecommandrunner-type-alias)              | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GenerateFailurePoint](/docs/api/create-relkit#generatefailurepoint-type-alias)                | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L14)                                  |
| [GenerateNextSteps](/docs/api/create-relkit#generatenextsteps-interface)                       | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generateProject](/docs/api/create-relkit#generateproject)                                     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/dependency-patch-generation.test.ts#L20)         |
| [GenerateProjectContext](/docs/api/create-relkit#generateprojectcontext-interface)             | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L101)                                 |
| [generateProjectEffect](/docs/api/create-relkit#generateprojecteffect)                         | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L45)            |
| [GenerateProjectError](/docs/api/create-relkit#generateprojecterror-class)                     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/failure-cleanup.test.ts#L29)                                  |
| [GenerateProjectResult](/docs/api/create-relkit#generateprojectresult-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorCleanupFailure](/docs/api/create-relkit#generatorcleanupfailure-interface)           | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorCleanupFailures](/docs/api/create-relkit#generatorcleanupfailures)                   | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-lifecycle.effect.test.ts#L69)      |
| [GeneratorCommandResult](/docs/api/create-relkit#generatorcommandresult-interface)             | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorCommandRunner](/docs/api/create-relkit#generatorcommandrunner-type-alias)            | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorDirectoryEntry](/docs/api/create-relkit#generatordirectoryentry-interface)           | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorDomainError](/docs/api/create-relkit#generatordomainerror-class)                     | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorEntryKind](/docs/api/create-relkit#generatorentrykind-type-alias)                    | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorFileMetadata](/docs/api/create-relkit#generatorfilemetadata-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorFileSystem](/docs/api/create-relkit#generatorfilesystem-class)                       | Value | `create-relkit`                                     | [API example](/docs/api/create-relkit#generatorfilesystem-class)                                                                           |
| [generatorFileSystemLive](/docs/api/create-relkit#generatorfilesystemlive)                     | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L67)            |
| [GeneratorFileSystemService](/docs/api/create-relkit#generatorfilesystemservice-interface)     | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-services-directories.fixture.ts#L14) |
| [GeneratorIoError](/docs/api/create-relkit#generatorioerror-class)                             | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-services.fixture.ts#L51)             |
| [GeneratorPaths](/docs/api/create-relkit#generatorpaths-class)                                 | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/contributor/workspace.fixture.ts#L74)                      |
| [generatorPathsLive](/docs/api/create-relkit#generatorpathslive)                               | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L69)            |
| [GeneratorPathsService](/docs/api/create-relkit#generatorpathsservice-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorProcess](/docs/api/create-relkit#generatorprocess-class)                             | Value | `create-relkit`                                     | [API example](/docs/api/create-relkit#generatorprocess-class)                                                                              |
| [GeneratorProcessError](/docs/api/create-relkit#generatorprocesserror-class)                   | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/transaction-lifecycle.effect.test.ts#L99)      |
| [generatorProcessLayer](/docs/api/create-relkit#generatorprocesslayer)                         | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorProcessLive](/docs/api/create-relkit#generatorprocesslive)                           | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L68)            |
| [GeneratorProcessService](/docs/api/create-relkit#generatorprocessservice-interface)           | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [GeneratorPrompt](/docs/api/create-relkit#generatorprompt-class)                               | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L48)            |
| [GeneratorPromptError](/docs/api/create-relkit#generatorprompterror-class)                     | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [generatorPromptLayer](/docs/api/create-relkit#generatorpromptlayer)                           | Value | `create-relkit`                                     | [API example](/docs/api/create-relkit#generatorpromptlayer)                                                                                |
| [GeneratorPromptService](/docs/api/create-relkit#generatorpromptservice-interface)             | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [hasErrno](/docs/api/create-relkit#haserrno)                                                   | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [isValidPackageName](/docs/api/create-relkit#isvalidpackagename)                               | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/option-matrix-destinations.test.ts#L32)                       |
| [launchBun](/docs/api/create-relkit#launchbun)                                                 | Value | `create-relkit/launcher`                            | [Module example](/docs/modules/cli/automation)                                                                                             |
| [main](/docs/api/create-relkit#main)                                                           | Value | `create-relkit/cli`                                 | [Module example](/docs/modules/cli/automation)                                                                                             |
| [normalizeCreateOptions](/docs/api/create-relkit#normalizecreateoptions)                       | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts#L9)                                  |
| [planCreate](/docs/api/create-relkit#plancreate)                                               | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts#L16)                                 |
| [planCreateEffect](/docs/api/create-relkit#plancreateeffect)                                   | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ProjectGeneration](/docs/api/create-relkit#projectgeneration-class)                           | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [projectGenerationLive](/docs/api/create-relkit#projectgenerationlive)                         | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L66)            |
| [PromptDriver](/docs/api/create-relkit#promptdriver-interface)                                 | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/invocation/interaction.test.ts#L14)                        |
| [PromptOption](/docs/api/create-relkit#promptoption-interface)                                 | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [publicFailure](/docs/api/create-relkit#publicfailure)                                         | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/planning.effect.test.ts#L129)                  |
| [recordCleanupFailure](/docs/api/create-relkit#recordcleanupfailure)                           | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/observation.effect.test.ts#L94)                  |
| [resolveCatalogVersion](/docs/api/create-relkit#resolvecatalogversion)                         | Value | `create-relkit`, `create-relkit/catalog-resolution` | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolveCreateContext](/docs/api/create-relkit#resolvecreatecontext-interface)                 | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateDestination](/docs/api/create-relkit#resolvecreatedestination)                   | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateDestinationEffect](/docs/api/create-relkit#resolvecreatedestinationeffect)       | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateOptions](/docs/api/create-relkit#resolvecreateoptions)                           | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveCreateOptionsDetails](/docs/api/create-relkit#resolvecreateoptionsdetails)             | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/generator/add-resolver.creation.cases.ts#L32)                           |
| [resolveCreateOptionsDetailsEffect](/docs/api/create-relkit#resolvecreateoptionsdetailseffect) | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ResolvedCreateOptions](/docs/api/create-relkit#resolvedcreateoptions-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveTemplateRoot](/docs/api/create-relkit#resolvetemplateroot)                             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [resolveTemplateRootEffect](/docs/api/create-relkit#resolvetemplaterooteffect)                 | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [RouteMethod](/docs/api/create-relkit#routemethod-type-alias)                                  | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [SCAFFOLD_DEPENDENCIES](/docs/api/create-relkit#scaffold_dependencies)                         | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches-selection.cases.ts#L67)     |
| [scaffoldDependency](/docs/api/create-relkit#scaffolddependency-1)                             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldDependency](/docs/api/create-relkit#scaffolddependency-interface)                     | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldDependencyName](/docs/api/create-relkit#scaffolddependencyname-type-alias)            | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/dependency-patches.fixture.ts#L38)             |
| [scaffoldErrors](/docs/api/create-relkit#scaffolderrors)                                       | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldFileOperation](/docs/api/create-relkit#scaffoldfileoperation-interface)               | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldPlan](/docs/api/create-relkit#scaffoldplan-interface)                                 | Type  | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/scaffolding/generator-environment.probe.ts#L27)            |
| [ScaffoldVerification](/docs/api/create-relkit#scaffoldverification-type-alias)                | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ScaffoldWarning](/docs/api/create-relkit#scaffoldwarning-interface)                           | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ServiceInclude](/docs/api/create-relkit#serviceinclude-type-alias)                            | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [supported](/docs/api/create-relkit#supported)                                                 | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [supportedCreateTemplates](/docs/api/create-relkit#supportedcreatetemplates)                   | Value | `create-relkit`                                     | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/tests/create-capabilities.test.ts#L24)                 |
| [TextPromptOptions](/docs/api/create-relkit#textpromptoptions-interface)                       | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [transferCleanupFailures](/docs/api/create-relkit#transfercleanupfailures)                     | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validateCreateOptions](/docs/api/create-relkit#validatecreateoptions)                         | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validateCreateOptionsEffect](/docs/api/create-relkit#validatecreateoptionseffect)             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [ValidatedCreateOptions](/docs/api/create-relkit#validatedcreateoptions-interface)             | Type  | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |
| [validatePackageName](/docs/api/create-relkit#validatepackagename)                             | Value | `create-relkit`                                     | [Module example](/docs/modules/cli/automation)                                                                                             |

## `add-transaction-files.ts`

Snapshots, writes and restores transaction-owned files and lock artifacts using the creator filesystem service; rollback preserves original bytes and modes.

### FileSnapshot

**Signature**

```ts
declare const FileSnapshot: FileSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L13)

### applyFileOperations

**Signature**

```ts
declare const applyFileOperations: (
  root: string,
  operations: readonly ScaffoldFileOperation[],
  createdDirectories: Set<string>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L150)

### applyFileOperationsEffect

Applies planned files in order; each temporary atomic-write asset has its own scope.

**Signature**

```ts
declare const applyFileOperationsEffect: (
  root: string,
  operations: ReadonlyArray<ScaffoldFileOperation>,
  createdDirectories: Set<string>,
) => Effect.Effect<void, GeneratorDomainError | GeneratorIoError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L92)

### operationPath

Resolves one relative operation while rejecting broad and escaping paths.

**Signature**

```ts
declare const operationPath: (root: string, path: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L20)

### restoreFiles

**Signature**

```ts
declare const restoreFiles: (
  snapshots: readonly FileSnapshot[],
  createdDirectories: ReadonlySet<string>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L151)

### restoreFilesEffect

Restores all touched files even when one restoration fails, then removes only owned empty directories.

**Signature**

```ts
declare const restoreFilesEffect: (
  snapshots: ReadonlyArray<FileSnapshot>,
  createdDirectories: ReadonlySet<string>,
) => Effect.Effect<undefined, GeneratorIoError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L114)

### snapshotFiles

**Signature**

```ts
declare const snapshotFiles: (
  root: string,
  operations: readonly ScaffoldFileOperation[],
  includeLock: boolean,
) => Promise<readonly FileSnapshot[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L148)

### snapshotFilesEffect

Snapshots bytes and modes, including both Bun lock formats when installation is required.

**Signature**

```ts
declare const snapshotFilesEffect: (
  root: string,
  operations: ReadonlyArray<ScaffoldFileOperation>,
  includeLock: boolean,
) => Effect.Effect<
  Array<
    | { path: string; content?: never; mode?: never }
    | { path: string; content: Uint8Array<ArrayBufferLike>; mode: number }
  >,
  GeneratorDomainError | GeneratorIoError,
  GeneratorFileSystem
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L37)

### validateOperationActions

**Signature**

```ts
declare const validateOperationActions: (
  root: string,
  operations: readonly ScaffoldFileOperation[],
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L149)

### validateOperationActionsEffect

Validates every destination before any transaction write, retaining deterministic error order.

**Signature**

```ts
declare const validateOperationActionsEffect: (
  root: string,
  operations: ReadonlyArray<ScaffoldFileOperation>,
) => Effect.Effect<void, GeneratorDomainError | GeneratorIoError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-transaction-files.ts#L65)

## `add-types.ts`

Supported artifact kinds accepted by relkit add.

### ADD_FAILURE_CODES

Stable public diagnostic codes for scaffold failure categories.

**Signature**

```ts
declare const ADD_FAILURE_CODES: Readonly<{
  readonly usage: "RELKIT_ADD_USAGE";
  readonly invalidProject: "RELKIT_ADD_INVALID_PROJECT";
  readonly collision: "RELKIT_ADD_COLLISION";
  readonly unsupportedSourceShape: "RELKIT_ADD_UNSUPPORTED_SOURCE_SHAPE";
  readonly installation: "RELKIT_ADD_INSTALLATION_FAILED";
  readonly validation: "RELKIT_ADD_VALIDATION_FAILED";
  readonly cancellation: "RELKIT_ADD_CANCELLED";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L165)

### ADD_KINDS

Supported artifact kinds accepted by relkit add.

**Signature**

```ts
declare const ADD_KINDS: readonly [
  "service",
  "function",
  "error",
  "event",
  "event-function",
  "task",
  "job",
  "cache",
  "bucket",
  "tool",
  "prompt",
  "agent",
  "constants",
  "route",
  "middleware",
  "transform",
  "database",
  "auth",
  "inspector",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L2)

### AddFailureCode (type alias)

Stable public diagnostic category of AddScaffoldError.

**Signature**

```ts
type AddFailureCode = (typeof ADD_FAILURE_CODES)[keyof typeof ADD_FAILURE_CODES];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L175)

### AddKind (type alias)

Supported relkit add artifact discriminant.

**Signature**

```ts
type AddKind = (typeof ADD_KINDS)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L24)

### AddRequest (type alias)

Validated discriminated union of supported artifact scaffold requests.

**Signature**

```ts
type AddRequest =
  | NamedRequest<"service", { full: boolean; include: readonly ServiceInclude[] }>
  | NamedRequest<"function", { internal: boolean }>
  | NamedRequest<"error">
  | NamedRequest<"event", { internal: boolean; profile?: string }>
  | NamedRequest<
      "event-function",
      { event: string; delivery: "transient" | "durable"; profile?: string }
    >
  | NamedRequest<"task", { version: string; execution: "durable" | "retryable" }>
  | NamedRequest<"job", { target: string; profile?: string }>
  | NamedRequest<
      "cache",
      {
        profile?: string;
        provider?: "redis" | "cloudflare-kv";
        source?: "docker" | "connected" | "aws";
      }
    >
  | NamedRequest<
      "bucket",
      {
        profile?: string;
        provider?: "s3" | "cloudflare-r2";
        source?: "docker" | "connected" | "aws";
      }
    >
  | NamedRequest<
      "tool",
      {
        target: string;
        createFunction?: boolean;
        sideEffect: "none" | "read" | "write" | "external";
        approval: "never" | "on-write" | "always";
      }
    >
  | NamedRequest<"prompt", { text: readonly string[] }>
  | NamedRequest<
      "agent",
      {
        model?: string;
        tools: readonly string[];
        prompt?: string;
        instructions?: string;
      }
    >
  | NamedRequest<"constants">
  | (AddRequestBase & {
      readonly kind: "route";
      readonly path: string;
      readonly mode: "route" | "service-route";
      readonly maps: Readonly<Partial<Record<RouteMethod, string>>>;
    })
  | NamedRequest<"middleware", { path: string }>
  | NamedRequest<"transform">
  | (AddRequestBase & {
      readonly kind: "database";
      readonly orm: "drizzle";
      readonly dialect: DatabaseDialect;
      readonly authSchema?: boolean;
    })
  | (AddRequestBase & {
      readonly kind: "auth";
      readonly adapter: "better-auth";
      readonly databaseDialect: DatabaseDialect;
      readonly basePath: string;
    })
  /** Enables the development bridge and installs the project-local inspector UI. */
  | (AddRequestBase & { readonly kind: "inspector" });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L50)

### AddRequestBase (interface)

Project, installation and optional service selection shared by all add requests.

**Signature**

```ts
export interface AddRequestBase {
  readonly projectRoot: string;
  readonly service?: string;
  readonly createService?: string;
  readonly install: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L35)

### AddResult (interface)

Completed add transaction's files, packages, warnings, verification and next steps.

**Signature**

```ts
export interface AddResult {
  readonly ok: true;
  readonly command: "add";
  readonly kind: AddKind;
  readonly projectRoot: string;
  readonly createdFiles: readonly string[];
  readonly updatedFiles: readonly string[];
  readonly installedPackages: readonly string[];
  readonly warnings: readonly ScaffoldWarning[];
  readonly verification: ScaffoldVerification;
  readonly nextSteps: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L152)

### AddScaffoldError (class)

Public scaffold failure retaining its stable code, name and category-specific exit status.

**Signature**

```ts
declare class AddScaffoldError { constructor(
    readonly code: AddFailureCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L177)

### exitCode (property)

**Signature**

```ts
readonly exitCode: 1 | 2 | 130
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L178)

### DatabaseDialect (type alias)

Supported database dialect for Drizzle and authentication scaffolds.

**Signature**

```ts
type DatabaseDialect = "sqlite" | "postgresql" | "mysql";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L33)

### RouteMethod (type alias)

Supported HTTP method used by generated route mappings.

**Signature**

```ts
type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L31)

### ScaffoldFileOperation (interface)

One ordered project-relative create/update operation with complete content and optional mode.

**Signature**

```ts
export interface ScaffoldFileOperation {
  readonly path: string;
  readonly action: "create" | "update";
  readonly content: string;
  readonly mode?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L125)

### ScaffoldPlan (interface)

Complete conflict-checked request, ordered writes, concrete dependencies and follow-up details.

**Signature**

```ts
export interface ScaffoldPlan {
  readonly request: AddRequest;
  readonly projectRoot: string;
  readonly operations: readonly ScaffoldFileOperation[];
  readonly dependencies: Readonly<Record<string, string>>;
  readonly artifacts: readonly Readonly<{
    kind: string;
    path: string;
    id: string;
    binding: string;
  }>[];
  readonly profiles: readonly Readonly<{ capability: string; name: string }>[];
  readonly warnings: readonly ScaffoldWarning[];
  readonly nextSteps: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L132)

### ScaffoldVerification (type alias)

Public result of the requested post-mutation project check.

**Signature**

```ts
type ScaffoldVerification =
  | { readonly status: "passed"; readonly command: string }
  | { readonly status: "skipped"; readonly reason: string; readonly command: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L148)

### ScaffoldWarning (interface)

Stable warning category and user-facing message retained in plans and results.

**Signature**

```ts
export interface ScaffoldWarning {
  readonly code: string;
  readonly message: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L120)

### ServiceInclude (type alias)

Artifact kinds that can be included in a generic service scaffold.

**Signature**

```ts
type ServiceInclude = Exclude<
  AddKind,
  "service" | "database" | "auth" | "inspector" | "middleware" | "transform"
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/add-types.ts#L26)

## `build-catalog.ts`

### buildCatalogDependency

Reads a concrete dependency version materialized into this package at build time.

**Signature**

```ts
declare const buildCatalogDependency: (name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/build-catalog.ts#L10)

### buildCatalogPatch

Validates the patch descriptor against its centrally materialized dependency version.

**Signature**

```ts
declare const buildCatalogPatch: (name: string) => DependencyPatchDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/build-catalog.ts#L34)

### buildCatalogProvider

Reads a selected provider's own version independently of the application API version.

**Signature**

```ts
declare const buildCatalogProvider: (name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/build-catalog.ts#L15)

## `catalog-resolution.ts`

### CatalogManifest

**Signature**

```ts
declare const CatalogManifest: CatalogManifest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/catalog-resolution.ts#L2)

### resolveCatalogVersion

Resolves one dependency against its owning default or named Bun catalog.

**Throws**

When the reference, catalog, or catalog entry is missing or recursive.

**Signature**

```ts
declare const resolveCatalogVersion: (
  manifest: CatalogManifest,
  name: string,
  spec: unknown,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/catalog-resolution.ts#L25)

## `catalog-resolution.types.ts`

JSON package metadata accepted by the shared strict catalog resolver.

### CatalogManifest (type alias)

JSON package metadata accepted by the shared strict catalog resolver.

**Signature**

```ts
type CatalogManifest = Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/catalog-resolution.types.ts#L2)

## `cli.ts`

Builds the creator command presentation and signal scope around pure project creation, returning JSON or terminal results after owned work settles.

### main

Runs the executable presentation boundary with invocation-owned signal listeners.

**Signature**

```ts
declare const main: (args: readonly string[]) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/cli.ts#L23)

## `create-capabilities.ts`

Packaged creation support is an allow-list backed by exact packed readiness evidence.
Candidate literals remain parseable so explicit unsupported requests can return
a precise pre-staging diagnostic instead of masquerading as syntax errors.

### CREATE_CAPABILITY_TABLE

**Signature**

```ts
declare const CREATE_CAPABILITY_TABLE: Readonly<{
  version: 1;
  entries: ReadonlyArray<CreateCapabilityEvidence>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L43)

### CreateCapabilityEvidence

**Signature**

```ts
declare const CreateCapabilityEvidence: CreateCapabilityEvidence;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L20)

### CreateCapabilityIdentity

**Signature**

```ts
declare const CreateCapabilityIdentity: CreateCapabilityIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L19)

### CreateCapabilityTuple

**Signature**

```ts
declare const CreateCapabilityTuple: CreateCapabilityTuple;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L18)

### assertCreateCapability

Rejects missing or stale tuples before destination planning or installation.

**Signature**

```ts
declare const assertCreateCapability: (
  options: Pick<CreateOptions, "template" | "cloud" | "deploy" | "jobs" | "examples">,
  identity?: CreateCapabilityIdentity,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L70)

### currentCreateCapabilityIdentity

Reads the executing SDK's release and pinned dependency catalog without acquiring application clients.

**Signature**

```ts
declare const currentCreateCapabilityIdentity: () => CreateCapabilityIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L52)

### supported

Checks every field of a complete tuple and its exact tool identity.

**Signature**

```ts
declare const supported: (
  options: Pick<CreateOptions, "template" | "cloud" | "deploy" | "jobs" | "examples">,
  identity?: CreateCapabilityIdentity,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L101)

### supportedCreateTemplates

Filters interactive template choices through the same evidence allow-list.

**Signature**

```ts
declare const supportedCreateTemplates: (
  options: PartialCreateCapability,
  identity?: CreateCapabilityIdentity,
) => readonly CreateTemplate[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.ts#L86)

## `create-capabilities.types.ts`

Describes exact creation tuples and their recorded package, tool and template evidence identities.

### CreateCapabilityEvidence (interface)

Offered tuple backed by complete fresh and restart measurements for its template bytes.

**Signature**

```ts
export interface CreateCapabilityEvidence extends CreateCapabilityTuple {
  /** Exact tool and package catalog identity measured by the recorded certification host. */
  readonly identity: CreateCapabilityIdentity;
  /** SHA-256 over ordered template paths and their complete bytes. */
  readonly templateDigest: string;
  /** Repository-relative complete 20-attempt fresh report. */
  readonly freshEvidence: string;
  /** Repository-relative complete 20-attempt restart report. */
  readonly restartEvidence: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.types.ts#L36)

### CreateCapabilityIdentity (interface)

Every field must match the running packaged tool before a tuple is offered.

**Signature**

```ts
export interface CreateCapabilityIdentity {
  /** Exact first-party release version. */
  readonly release: string;
  /** Pinned native Bun version. */
  readonly bun: string;
  /** Exact TypeScript package version. */
  readonly typescript: string;
  /** SHA-256 of the complete tool dependency catalog. */
  readonly packageCatalogDigest: string;
  /** Exact source template directory identity. */
  readonly template: string;
  /** Prepared-input snapshot protocol version. */
  readonly snapshotProtocol: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.types.ts#L20)

### CreateCapabilityTuple (interface)

Complete public creation combination; absence of jobs preserves the native no-jobs option.

**Signature**

```ts
export interface CreateCapabilityTuple {
  /** Authored starter selected by the public CLI. */
  readonly template: CreateOptions["template"];
  /** Explicit cloud ownership selection. */
  readonly cloud: CreateOptions["cloud"];
  /** Explicit deployment engine selection. */
  readonly deploy: CreateOptions["deploy"];
  /** Optional durable-job integration selection. */
  readonly jobs?: CreateOptions["jobs"];
  /** Whether the starter's example sources are retained. */
  readonly examples: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.types.ts#L6)

### PartialCreateCapability (type alias)

Unresolved interactive choices used only to filter certified complete tuples.

**Signature**

```ts
type PartialCreateCapability = Readonly<{
  /** Optional starter choice. */
  template?: string;
  /** Optional cloud choice. */
  cloud?: string;
  /** Optional deployment choice. */
  deploy?: string;
  /** Optional job choice; undefined retains the native prompt semantics. */
  jobs?: string | undefined;
  /** Optional example choice. */
  examples?: boolean;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-capabilities.types.ts#L48)

## `create-preview.ts`

Builds a no-install creation preview from maintained template bytes and metadata without importing or evaluating authored template configuration.

### CreateScaffoldPlan

**Signature**

```ts
declare const CreateScaffoldPlan: CreateScaffoldPlan;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-preview.ts#L14)

### formatCreatePlan

Formats an immutable preview as the existing human-readable terminal output.

**Signature**

```ts
declare const formatCreatePlan: (plan: CreateScaffoldPlan) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-preview.ts#L88)

### planCreate

Preserves the existing preview Promise API.

**Signature**

```ts
declare const planCreate: (
  options: CreateOptions,
  context?: Pick<GenerateProjectContext, "cwd" | "templateRoot">,
) => Promise<CreateScaffoldPlan>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-preview.ts#L76)

### planCreateEffect

Previews explicit creation flags without mutating project or staging paths.

**Signature**

```ts
declare const planCreateEffect: (
  options: CreateOptions,
  context?: Pick<GenerateProjectContext, "cwd" | "templateRoot"> | undefined,
) => Effect.Effect<
  Readonly<{
    destination: string;
    files: ReadonlyArray<string>;
    dependencies: Readonly<{ [k: string]: string }>;
    profiles: ReadonlyArray<never>;
    warnings: ReadonlyArray<never>;
  }>,
  GeneratorDomainError | GeneratorIoError,
  GeneratorFileSystem | GeneratorPaths
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-preview.ts#L25)

## `create-preview.types.ts`

Existing read-only creation preview result.

### CreateScaffoldPlan (interface)

Existing read-only creation preview result.

**Signature**

```ts
export interface CreateScaffoldPlan {
  readonly destination: string;
  readonly files: readonly string[];
  readonly dependencies: Readonly<Record<string, string>>;
  readonly profiles: readonly string[];
  readonly warnings: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-preview.types.ts#L2)

## `create-resolver.ts`

Resolves creation options and certified template choices through the prompt service while preserving headless defaults and explicit user arguments.

### ResolveCreateContext

**Signature**

```ts
declare const ResolveCreateContext: ResolveCreateContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.ts#L13)

### ResolvedCreateOptions

**Signature**

```ts
declare const ResolvedCreateOptions: ResolvedCreateOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.ts#L13)

### resolveCreateOptions

Preserves normalized creation's Promise compatibility API.

**Signature**

```ts
declare const resolveCreateOptions: (
  args: readonly string[],
  context?: ResolveCreateContext,
) => Promise<CreateOptions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.ts#L105)

### resolveCreateOptionsDetails

Preserves detailed creation resolution with the shared interactive choices.

**Signature**

```ts
declare const resolveCreateOptionsDetails: (
  args: readonly string[],
  context?: ResolveCreateContext,
) => Promise<ResolvedCreateOptions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.ts#L118)

### resolveCreateOptionsDetailsEffect

Resolves explicit flags and prompts for missing name, template, jobs and destination choices.

**Signature**

```ts
declare const resolveCreateOptionsDetailsEffect: (
  args: ReadonlyArray<string>,
  context?: ResolveCreateContext | undefined,
) => Effect.Effect<
  { options: CreateOptions; prompted: boolean },
  GeneratorDomainError | GeneratorPromptError,
  GeneratorPrompt
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.ts#L27)

## `create-resolver.types.ts`

### ResolveCreateContext (interface)

Existing create-resolution settings; noninteractive input never needs prompt authority.

**Signature**

```ts
export interface ResolveCreateContext {
  readonly json?: boolean;
  readonly interactive?: boolean;
  readonly promptDriver?: PromptDriver;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.types.ts#L5)

### ResolvedCreateOptions (interface)

Existing resolver result; prompted records whether any creation choice was requested.

**Signature**

```ts
export interface ResolvedCreateOptions {
  readonly options: CreateOptions;
  readonly prompted: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/create-resolver.types.ts#L13)

## `dependency-patch-installation.ts`

### dependencyPatchNeedsInstall

Preserves the patch-installation Promise compatibility API.

**Signature**

```ts
declare const dependencyPatchNeedsInstall: (plan: ScaffoldPlan) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patch-installation.ts#L50)

### dependencyPatchNeedsInstallEffect

Detects patch-only installation requirements before a transaction mutates the project.

**Signature**

```ts
declare const dependencyPatchNeedsInstallEffect: (
  plan: ScaffoldPlan,
) => Effect.Effect<boolean, GeneratorDomainError | GeneratorIoError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patch-installation.ts#L15)

## `dependency-patches.ts`

Loads and plans the canonical selected Drizzle repair, validating conflicts before delivery and preserving its release pin and exact patch bytes.

### planDependencyPatch

Preserves patch planning's Promise API and collision constructors.

**Signature**

```ts
declare const planDependencyPatch: (
  projectRoot: string,
  source: string,
  patch: DependencyPatch,
) => Promise<DependencyPatchPlan>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L139)

### planDependencyPatchEffect

Plans byte-identical repair ownership without mutating project assets.

**Signature**

```ts
declare const planDependencyPatchEffect: (
  projectRoot: string,
  source: string,
  patch: DependencyPatch,
) => Effect.Effect<
  { operation?: { path: string; action: "create"; content: string }; content: string },
  GeneratorDomainError | GeneratorIoError,
  GeneratorFileSystem
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L50)

### prepareProjectDependencyPatch

Preserves staging repair delivery's Promise API.

**Signature**

```ts
declare const prepareProjectDependencyPatch: (projectRoot: string) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L152)

### prepareProjectDependencyPatchEffect

Delivers repair assets before the first installation inside a generation-owned stage.

**Signature**

```ts
declare const prepareProjectDependencyPatchEffect: (
  projectRoot: string,
) => Effect.Effect<void, GeneratorDomainError | GeneratorIoError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L99)

### readDrizzlePatch

Preserves the verified repair Promise API.

**Signature**

```ts
declare const readDrizzlePatch: () => Promise<DependencyPatch>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L128)

### readDrizzlePatchEffect

Loads verified Drizzle declaration repairs from source or the owning packed release.

**Signature**

```ts
declare const readDrizzlePatchEffect: () => Effect.Effect<
  Readonly<{
    path: `patches/${string}.patch`;
    content: string;
    version: string;
    key: string;
    asset: string;
    hash: string;
  }>,
  GeneratorDomainError | GeneratorIoError,
  GeneratorFileSystem
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/dependency-patches.ts#L25)

## `generate-output.ts`

Renders local onboarding from the generated project's actual installation state.
Pure command construction exposes finite preparation after skipped installation;
schema guards recognize presentation values without promoting arbitrary output
into the generated-result contract. Formatting performs no runtime acquisition.

### GenerateNextSteps

**Signature**

```ts
declare const GenerateNextSteps: GenerateNextSteps;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-output.ts#L107)

### createGenerateNextSteps

Builds local commands and endpoints for a generated project.

**Signature**

```ts
declare const createGenerateNextSteps: (
  options: Pick<CreateOptions, "examples" | "install">,
  destination: string,
  cwd?: string,
) => GenerateNextSteps;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-output.ts#L28)

### formatGenerateResult

Formats a recognizable generation result for terminal display.

**Signature**

```ts
declare const formatGenerateResult: <T>(value: T) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-output.ts#L65)

## `generate-output.types.ts`

Local commands and endpoints displayed after successful project creation.

### GenerateNextSteps (interface)

Local commands and endpoints displayed after successful project creation.

**Signature**

```ts
export interface GenerateNextSteps {
  readonly commands: Readonly<{
    readonly cd: string;
    readonly install?: "bun install";
    /** Finite validation/preparation required after a skipped dependency installation. */
    readonly prepare?: "bunx --no-install relkit dev --prepare";
    readonly dev: "bun run dev";
    readonly test: "bun run test";
    readonly check: "bun run check";
    readonly build: "bun run build";
  }>;
  readonly endpoints: Readonly<{
    /** A served backend URL: the example route, or the API reference without examples. */
    readonly backend:
      "http://localhost:3000/hello?name=RelKit" | "http://localhost:3000/_relkit/v1/api-reference";
    readonly inspector: "http://localhost:3210";
    readonly openapi: "http://localhost:3000/_relkit/v1/openapi.json";
    /** Present when the generated application selects the Scalar reference UI (the template default). */
    readonly apiReference?: "http://localhost:3000/_relkit/v1/api-reference";
    readonly route?: "GET http://localhost:3000/hello?name=RelKit";
  }>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-output.types.ts#L4)

## `generate-process.ts`

Runs creation installation and verification commands through the selected process service, retaining local executable resolution and cleanup boundaries.

### generationError

Maps a boundary failure to the public generation error contract.

**Signature**

```ts
declare const generationError: (
  error: unknown,
  fallback: string,
  cleanup?: StageCleanupResult,
) => GenerateProjectError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L24)

### injectGenerateFailure

Runs deterministic failure injection for generation regression tests.

**Signature**

```ts
declare const injectGenerateFailure: (
  context: GenerateProjectContext,
  point: GenerateFailurePoint,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L65)

### resolveRelkitExecutable

**Signature**

```ts
declare const resolveRelkitExecutable: (
  context: GenerateProjectContext,
  root: string,
) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L153)

### resolveRelkitExecutableEffect

**Signature**

```ts
declare const resolveRelkitExecutableEffect: (
  context: Pick<GenerateProjectContext, "relkitExecutable" | "commandRunner">,
  root: string,
) => Effect.Effect<string, GeneratorDomainError, GeneratorFileSystem>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L152)

### runProjectCommand

**Signature**

```ts
declare const runProjectCommand: (
  command: readonly string[],
  cwd: string,
  signal?: AbortSignal,
) => Promise<GenerateCommandResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L154)

### runProjectStep

Preserves generation step's public Promise adapter.

**Signature**

```ts
declare const runProjectStep: (
  context: GenerateProjectContext,
  command: readonly string[],
  cwd: string,
  step: string,
  point: GenerateFailurePoint,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L125)

### runProjectStepEffect

Executes one generation step through scoped process authority.

**Signature**

```ts
declare const runProjectStepEffect: (
  context: GenerateProjectContext,
  command: ReadonlyArray<string>,
  cwd: string,
  step: string,
  point: GenerateFailurePoint,
) => Effect.Effect<undefined, GeneratorDomainError | GeneratorProcessError, GeneratorProcess>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L88)

### throwIfAborted

Throws the caller's existing cancellation reason before any new work is started.

**Signature**

```ts
declare const throwIfAborted: (signal: AbortSignal | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-process.ts#L145)

## `generate-types.ts`

### GenerateCommandResult (interface)

Native process exit status and captured standard output/error.

**Signature**

```ts
export interface GenerateCommandResult {
  readonly exitCode: number;
  readonly stdout?: string;
  readonly stderr?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L9)

### GenerateCommandRunner (type alias)

Existing Promise process adapter receiving literal arguments, cwd and optional cancellation.

**Signature**

```ts
type GenerateCommandRunner = (
  command: readonly string[],
  cwd: string,
  signal?: AbortSignal,
) => Promise<GenerateCommandResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L18)

### GenerateFailurePoint (type alias)

Named generation stages available for deterministic failure injection.

**Signature**

```ts
type GenerateFailurePoint =
  "copy" | "substitute" | "install" | "git" | "doctor" | "check" | "rename";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L27)

### GenerateProjectContext (interface)

Caller-owned templates, process/prompt adapters, cancellation and progress settings.

**Signature**

```ts
export interface GenerateProjectContext {
  readonly cwd?: string;
  readonly templateRoot?: string;
  readonly commandRunner?: GenerateCommandRunner;
  readonly bunExecutable?: string;
  readonly gitExecutable?: string;
  readonly relkitExecutable?: string;
  readonly signal?: AbortSignal;
  /**
   * Reports the current step through the caller's progress sink.
   * @param message - User-facing progress text for the current step.
   * @returns Completion after the sink receives one progress message.
   */
  readonly onProgress?: (message: string) => void;
  /**
   * Injects a failure at a named stage for deterministic generation tests.
   * @param point - Fixed deterministic generation failure-injection point.
   * @returns Completion after the hook runs; a thrown failure aborts that stage.
   */
  readonly failAt?: (point: GenerateFailurePoint) => void;
  readonly interactive?: boolean;
  readonly promptDriver?: PromptDriver;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L33)

### GenerateProjectError (class)

Public generation failure carrying its diagnostic code, exit status and optional staging path.

**Signature**

```ts
declare class GenerateProjectError { constructor(
    readonly code: string,
    message: string,
    temporaryPath?: string,
    exitCode: 1 | 2 | 130 | 143 = defaultExitCode(code),
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L79)

### exitCode (property)

**Signature**

```ts
readonly exitCode: 1 | 2 | 130 | 143
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L80)

### temporaryPath (property)

**Signature**

```ts
readonly temporaryPath: string | undefined
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L81)

### GenerateProjectResult (interface)

Published project's options, destination, files, warnings and local next steps.

**Signature**

```ts
export interface GenerateProjectResult {
  readonly ok: true;
  readonly command: "create";
  readonly name: string;
  readonly template: CreateOptions["template"];
  readonly cloud: CreateOptions["cloud"];
  readonly deploy: CreateOptions["deploy"];
  readonly destination: string;
  readonly files: readonly string[];
  readonly installed: boolean;
  readonly gitInitialized: boolean;
  readonly additions: readonly AddResult[];
  readonly warnings: readonly ScaffoldWarning[];
  readonly nextSteps: GenerateNextSteps;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate-types.ts#L60)

## `generate.ts`

### ProjectGeneration (class)

Owns one complete creation workflow, including consent and atomic publication.

**Signature**

```ts
declare class ProjectGeneration
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate.ts#L34)

### generateProject

Preserves the public Promise API, flags, errors and generated result shape.

**Signature**

```ts
declare const generateProject: (
  options: CreateOptions,
  context?: GenerateProjectContext,
) => Promise<GenerateProjectResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate.ts#L87)

### generateProjectEffect

Generates a project through explicitly acquired creation authority.

**Signature**

```ts
declare const generateProjectEffect: (
  options: CreateOptions,
  context?: GenerateProjectContext | undefined,
) => Effect.Effect<
  GenerateProjectResult,
  GeneratorDomainError | GeneratorIoError | GeneratorPromptError | GeneratorProcessError,
  ProjectGeneration
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate.ts#L74)

### projectGenerationLive

Generation captures explicit filesystem, path, process and prompt authority at acquisition.

**Signature**

```ts
declare const projectGenerationLive: Layer.Layer<
  ProjectGeneration,
  never,
  GeneratorFileSystem | GeneratorPaths | GeneratorPrompt | GeneratorProcess
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generate.ts#L43)

## `generator-cleanup.ts`

### GeneratorCleanupFailure

**Signature**

```ts
declare const GeneratorCleanupFailure: GeneratorCleanupFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-cleanup.ts#L4)

### generatorCleanupFailures

Reads secondary cleanup evidence without changing error identity or enumerable JSON contracts.

**Signature**

```ts
declare const generatorCleanupFailures: (value: unknown) => readonly GeneratorCleanupFailure[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-cleanup.ts#L14)

### recordCleanupFailure

Attaches bounded release evidence to the original scoped exit's public owner.

**Signature**

```ts
declare const recordCleanupFailure: (
  exit: Exit.Exit<unknown, unknown>,
  operation: GeneratorCleanupFailure["operation"],
  cause: unknown,
  ownerOverride?: unknown,
) => Effect.Effect<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-cleanup.ts#L27)

### transferCleanupFailures

Retains release diagnostics when an existing compatibility contract translates a native failure.

**Signature**

```ts
declare const transferCleanupFailures: <A extends object>(original: unknown, translated: A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-cleanup.ts#L63)

## `generator-cleanup.types.ts`

Secondary resource-release evidence, separated from the authoritative public failure.

### GeneratorCleanupFailure (interface)

Secondary resource-release evidence, separated from the authoritative public failure.

**Signature**

```ts
export interface GeneratorCleanupFailure {
  readonly operation: "temporary-file" | "rollback" | "marker" | "stage" | "process";
  readonly cause: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-cleanup.types.ts#L2)

## `generator-errors.ts`

### GeneratorDomainError (class)

An expected legacy domain failure carried through a typed Effect workflow.

**Signature**

```ts
declare class GeneratorDomainError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L26)

### GeneratorIoError (class)

A failed native filesystem operation, retaining its original diagnostic.

**Signature**

```ts
declare class GeneratorIoError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L7)

### GeneratorProcessError (class)

A failed child-process adapter operation. Command arguments are never telemetry labels.

**Signature**

```ts
declare class GeneratorProcessError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L14)

### GeneratorPromptError (class)

A failed or cancelled prompt adapter operation.

**Signature**

```ts
declare class GeneratorPromptError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L20)

### domainError

Carries an expected public error through internal domain composition.

**Signature**

```ts
declare const domainError: (cause: unknown) => GeneratorDomainError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L59)

### domainTry

Executes a pure validation boundary without converting downstream defects or interruption.

**Signature**

```ts
declare const domainTry: <A>(evaluate: () => A) => Effect.Effect<A, GeneratorDomainError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L37)

### errorMessage

Formats diagnostic text without assuming an Error instance.

**Signature**

```ts
declare const errorMessage: (cause: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L82)

### hasErrno

Tests an adapter rejection's native errno without an unchecked assertion.

**Signature**

```ts
declare const hasErrno: (cause: unknown, code: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L92)

### publicFailure

Restores the original rejection at a public Promise or synchronous adapter.

**Signature**

```ts
declare const publicFailure: (error: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L68)

### scaffoldErrors

Translates only existing synchronous scaffold validators into the typed channel.

**Signature**

```ts
declare const scaffoldErrors: <A, E, R>(
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | GeneratorDomainError, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-errors.ts#L105)

## `generator-filesystem.ts`

Provides injectable filesystem operations used by creation and transaction workflows, preserving native I/O failures and atomic file ownership.

### GeneratorFileSystem (class)

Native filesystem authority supplied through live or deterministic test Layers.

**Example**

```ts
import { Effect } from "effect";
import { GeneratorFileSystem, generatorFileSystemLive } from "create-relkit";
const inspect = GeneratorFileSystem.use((fs) => fs.metadata("./package.json"));
const supplied = inspect.pipe(Effect.provide(generatorFileSystemLive));
```

**Signature**

```ts
declare class GeneratorFileSystem
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.ts#L25)

### generatorFileSystemLive

Live Node/Bun adapter. Mutating calls settle before scoped transaction cleanup can run.

**Signature**

```ts
declare const generatorFileSystemLive: Layer.Layer<GeneratorFileSystem, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.ts#L34)

## `generator-filesystem.types.ts`

### GeneratorDirectoryEntry (interface)

A directory entry read without following symlinks.

**Signature**

```ts
export interface GeneratorDirectoryEntry {
  readonly name: string;
  readonly kind: GeneratorEntryKind;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.types.ts#L14)

### GeneratorEntryKind (type alias)

Native entry classification without following symlinks.

**Signature**

```ts
type GeneratorEntryKind = "file" | "directory" | "symlink" | "other";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.types.ts#L5)

### GeneratorFileMetadata (interface)

Filesystem metadata needed for safe mutation and mode restoration.

**Signature**

```ts
export interface GeneratorFileMetadata {
  readonly kind: GeneratorEntryKind;
  readonly mode: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.types.ts#L8)

### GeneratorFileSystemService (interface)

Explicit native filesystem authority for generator workflows.

**Signature**

```ts
export interface GeneratorFileSystemService {
  /**
   * Reads UTF-8 file contents with interruptible native read authority.
   * @param path - Path inside the current project or owned resource.
   * @returns File contents, or a typed native read failure.
   */
  readonly readText: (path: string) => Effect.Effect<string, GeneratorIoError>;
  /**
   * Reads original file bytes for exact rollback snapshots.
   * @param path - Path inside the current project or owned resource.
   * @returns File bytes, or a typed native read failure.
   */
  readonly readBytes: (path: string) => Effect.Effect<Uint8Array, GeneratorIoError>;
  /**
   * Checks native accessibility without granting file mutation.
   * @param path - Path inside the current project or owned resource.
   * @returns Completion when the destination is accessible.
   */
  readonly access: (path: string) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Reads kind and permissions without dereferencing symlinks.
   * @param path - Path inside the current project or owned resource.
   * @returns Entry kind and mode, undefined when absent; symlinks are not followed.
   */
  readonly metadata: (
    path: string,
  ) => Effect.Effect<GeneratorFileMetadata | undefined, GeneratorIoError>;
  /**
   * Reads directory entries for deterministic declaration traversal.
   * @param path - Path inside the current project or owned resource.
   * @returns Directory entries without following symlinks.
   */
  readonly entries: (
    path: string,
  ) => Effect.Effect<readonly GeneratorDirectoryEntry[], GeneratorIoError>;
  /**
   * Writes complete content and waits for physical native settlement.
   * @param path - Path inside the current project or owned resource.
   * @param content - Complete bytes or text planned for the destination.
   * @param options - Explicit options retaining existing defaults.
   * @returns Completion after native bytes physically settle, before rollback can run.
   */
  readonly write: (
    path: string,
    content: string | Uint8Array,
    options?: { readonly mode?: number; readonly flag?: "wx" },
  ) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Creates owned directories and waits for physical native settlement.
   * @param path - Path inside the current project or owned resource.
   * @param options - Explicit options retaining existing defaults.
   * @returns Completion after native directory creation physically settles.
   */
  readonly mkdir: (
    path: string,
    options?: { readonly recursive?: boolean; readonly mode?: number },
  ) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Acquires a unique staging directory from its literal prefix.
   * @param prefix - Literal sibling-stage prefix owned by this invocation.
   * @returns The owned staging path after creation settles.
   */
  readonly temporaryDirectory: (prefix: string) => Effect.Effect<string, GeneratorIoError>;
  /**
   * Atomically moves an owned native path and waits for settlement.
   * @param from - Owned source path.
   * @param to - Validated destination path.
   * @returns Completion after the atomic native handoff settles.
   */
  readonly rename: (from: string, to: string) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Removes an owned native path with explicit recursive and force policy.
   * @param path - Path inside the current project or owned resource.
   * @param options - Explicit options retaining existing defaults.
   * @returns Completion after owned path removal settles.
   */
  readonly remove: (
    path: string,
    options?: { readonly recursive?: boolean; readonly force?: boolean },
  ) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Removes an owned directory only when it is empty.
   * @param path - Path inside the current project or owned resource.
   * @returns Completion after removing an owned empty directory.
   */
  readonly removeDirectory: (path: string) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Restores or sets native permission bits after content settlement.
   * @param path - Path inside the current project or owned resource.
   * @param mode - Optional restored or generated permission mode.
   * @returns Completion after native permission restoration settles.
   */
  readonly chmod: (path: string, mode: number) => Effect.Effect<void, GeneratorIoError>;
  /**
   * Enumerates sorted source paths with a declaration-owned glob pattern.
   * @param root - Absolute project or owned resource root.
   * @param pattern - Declaration-owned glob or ignore pattern.
   * @returns Sorted source-relative paths matching the declaration pattern.
   */
  readonly glob: (
    root: string,
    pattern: string,
  ) => Effect.Effect<readonly string[], GeneratorIoError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-filesystem.types.ts#L20)

## `generator-paths.ts`

### GeneratorPaths (class)

Read-only path authority; synchronous compatibility does not grant filesystem mutation.

**Signature**

```ts
declare class GeneratorPaths
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-paths.ts#L9)

### generatorPathsLive

Native read-only path adapter used by both Effect workflows and synchronous public validators.

**Signature**

```ts
declare const generatorPathsLive: Layer.Layer<GeneratorPaths, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-paths.ts#L17)

## `generator-paths.types.ts`

### GeneratorPathsService (interface)

Read-only native path authority that preserves existing synchronous validation APIs.

**Signature**

```ts
export interface GeneratorPathsService {
  /**
   * Reads kind and permissions without dereferencing symlinks.
   * @param path - Path inside the current project or owned resource.
   * @returns Entry kind and mode, undefined when absent; symlinks are not followed.
   */
  readonly metadata: (
    path: string,
  ) => Effect.Effect<GeneratorFileMetadata | undefined, GeneratorIoError>;
  /**
   * Reads directory entries for deterministic declaration traversal.
   * @param path - Path inside the current project or owned resource.
   * @returns Directory entries without following symlinks.
   */
  readonly entries: (path: string) => Effect.Effect<readonly string[], GeneratorIoError>;
  /**
   * Canonicalizes an existing path for safe destination validation.
   * @param path - Path inside the current project or owned resource.
   * @returns Canonical existing path, or a typed native failure.
   */
  readonly realpath: (path: string) => Effect.Effect<string, GeneratorIoError>;
  /**
   * Reads the composition root's native current directory.
   * @returns Current native working directory.
   */
  readonly cwd: () => Effect.Effect<string>;
  /**
   * Reads the user's native home directory for destination safety.
   * @returns Native user home directory.
   */
  readonly home: () => Effect.Effect<string>;
  /**
   * Reads the native temporary root for destination safety.
   * @returns Native temporary directory root.
   */
  readonly temporaryRoot: () => Effect.Effect<string>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-paths.types.ts#L6)

## `generator-process.ts`

Provides the scoped native process adapter for creator workflows, joining exit and output drains before release or transactional rollback.

### GeneratorProcess (class)

Child-process authority, replaceable at the same Layer boundary in tests.

**Example**

```ts
import { Effect } from "effect";
import { GeneratorProcess, generatorProcessLive } from "create-relkit";
const locate = GeneratorProcess.use((process) => process.which("bun"));
const supplied = locate.pipe(Effect.provide(generatorProcessLive));
```

**Signature**

```ts
declare class GeneratorProcess
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.ts#L19)

### generatorProcessLayer

Constructs a live process adapter or adapts an existing injected command runner.

**Signature**

```ts
declare const generatorProcessLayer: (
  runner?: GeneratorCommandRunner,
) => Layer.Layer<GeneratorProcess>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.ts#L31)

### generatorProcessLive

Live scoped Bun child-process implementation.

**Signature**

```ts
declare const generatorProcessLive: Layer.Layer<GeneratorProcess, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.ts#L24)

## `generator-process.types.ts`

### GeneratorCommandResult (interface)

Captured process result, matching both existing command-runner compatibility contracts.

**Signature**

```ts
export interface GeneratorCommandResult {
  readonly exitCode: number;
  readonly stdout?: string;
  readonly stderr?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.types.ts#L5)

### GeneratorCommandRunner (type alias)

Existing external runner adapter; its signal is aborted when the owning fiber is interrupted.

**Signature**

```ts
type GeneratorCommandRunner = (
  command: readonly string[],
  cwd: string,
  signal?: AbortSignal,
) => Promise<GeneratorCommandResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.types.ts#L32)

### GeneratorProcessService (interface)

Explicit process-spawning authority. Each invocation owns its child through completion.

**Signature**

```ts
export interface GeneratorProcessService {
  /**
   * Owns one command, output drains and child settlement through scope release.
   * @param command - Literal executable and argument vector.
   * @param cwd - Working directory for the operation.
   * @returns Captured output and exit status after child settlement and scoped cleanup.
   */
  readonly run: (
    command: readonly string[],
    cwd: string,
  ) => Effect.Effect<GeneratorCommandResult, GeneratorProcessError>;
  /**
   * Locates an executable through the native process adapter.
   * @param executable - Executable name resolved through the native search path.
   * @returns Executable path, or null when unavailable.
   */
  readonly which: (executable: string) => Effect.Effect<string | null, GeneratorProcessError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-process.types.ts#L12)

## `generator-prompt.ts`

Provides the prompt service adapter used by creation and CLI scaffolding while preserving cancellation and the selected prompt driver's values.

### GeneratorPrompt (class)

Prompt authority; interactive workflows cannot run without an explicit live or test adapter.

**Signature**

```ts
declare class GeneratorPrompt
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-prompt.ts#L10)

### generatorPromptLayer

Adapts the existing public prompt driver to typed, interruptible operations.

**Example**

```ts
import { Effect } from "effect";
import { GeneratorPrompt, generatorPromptLayer, createClackPromptDriver } from "create-relkit";
const confirmed = GeneratorPrompt.use((prompt) => prompt.confirm({ message: "Continue?" }));
const run = confirmed.pipe(Effect.provide(generatorPromptLayer(createClackPromptDriver())));
```

**Signature**

```ts
declare const generatorPromptLayer: (driver: PromptDriver) => Layer.Layer<GeneratorPrompt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-prompt.ts#L26)

## `generator-prompt.types.ts`

### GeneratorPromptService (interface)

Explicit interactive input authority, shared by Clack and deterministic test drivers.

**Signature**

```ts
export interface GeneratorPromptService {
  /**
   * Asks for text through the explicit, cancellation-aware native driver.
   * @param options - Explicit options retaining existing defaults.
   * @returns Decoded text; prompt interruption propagates to the native driver.
   */
  readonly text: (options: TextPromptOptions) => Effect.Effect<string, GeneratorPromptError>;
  /**
   * Asks for one declared option and decodes the native answer.
   * @typeParam Value - Union of declared prompt option values.
   * @param options - Question, declared choices and optional initial selection.
   * @returns One decoded declared option; invalid native answers fail.
   */
  readonly select: <Value extends string>(
    options: ChoicePromptOptions<Value>,
  ) => Effect.Effect<Value, GeneratorPromptError>;
  /**
   * Asks for declared options and decodes their ordered native answers.
   * @typeParam Value - Union of declared prompt option values.
   * @param options - Question, declared choices and optional required-selection policy.
   * @returns Decoded declared options in driver order.
   */
  readonly multiselect: <Value extends string>(
    options: ChoicePromptOptions<Value> & { readonly required?: boolean },
  ) => Effect.Effect<readonly Value[], GeneratorPromptError>;
  /**
   * Asks for boolean consent and decodes the native answer.
   * @param options - Explicit options retaining existing defaults.
   * @returns Decoded consent; cancellation retains its original rejection.
   */
  readonly confirm: (options: {
    readonly message: string;
    readonly initialValue?: boolean;
  }) => Effect.Effect<boolean, GeneratorPromptError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-prompt.types.ts#L6)

## `generator-runtime.ts`

### runGeneratorPromise

Runs a public Promise compatibility edge without changing rejection identity.

**Signature**

```ts
declare const runGeneratorPromise: <A, E>(
  effect: Effect.Effect<A, E, GeneratorFileSystem | GeneratorProcess | GeneratorPaths>,
  signal?: AbortSignal,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-runtime.ts#L23)

### runGeneratorSync

Runs a pure synchronous compatibility edge in the shared owner.

**Signature**

```ts
declare const runGeneratorSync: <A, E>(effect: Effect.Effect<A, E, GeneratorPaths>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/generator-runtime.ts#L41)

## `index.ts`

Publishes pure project creation, normalized options and portable template metadata; existing-project AST discovery and add execution belong to the CLI.

### "./add-types.js" (namespace export)

Re-exports all named exports from the "./add-types.js" module.

**Signature**

```ts
export * from "./add-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L5)

### "./create-capabilities.js" (namespace export)

Re-exports all named exports from the "./create-capabilities.js" module.

**Signature**

```ts
export * from "./create-capabilities.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L4)

### "./create-preview.js" (namespace export)

Re-exports all named exports from the "./create-preview.js" module.

**Signature**

```ts
export * from "./create-preview.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L11)

### "./create-resolver.js" (namespace export)

Re-exports all named exports from the "./create-resolver.js" module.

**Signature**

```ts
export * from "./create-resolver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L10)

### "./generate-output.js" (namespace export)

Re-exports all named exports from the "./generate-output.js" module.

**Signature**

```ts
export * from "./generate-output.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L16)

### "./generate-types.js" (namespace export)

Re-exports all named exports from the "./generate-types.js" module.

**Signature**

```ts
export * from "./generate-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L15)

### "./generate.js" (namespace export)

Re-exports all named exports from the "./generate.js" module.

**Signature**

```ts
export * from "./generate.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L14)

### "./generator-cleanup.js" (namespace export)

Re-exports all named exports from the "./generator-cleanup.js" module.

**Signature**

```ts
export * from "./generator-cleanup.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L26)

### "./generator-errors.js" (namespace export)

Re-exports all named exports from the "./generator-errors.js" module.

**Signature**

```ts
export * from "./generator-errors.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L27)

### "./generator-filesystem.js" (namespace export)

Re-exports all named exports from the "./generator-filesystem.js" module.

**Signature**

```ts
export * from "./generator-filesystem.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L18)

### "./generator-filesystem.types.js" (namespace export)

Re-exports all named exports from the "./generator-filesystem.types.js" module.

**Signature**

```ts
export * from "./generator-filesystem.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L19)

### "./generator-paths.js" (namespace export)

Re-exports all named exports from the "./generator-paths.js" module.

**Signature**

```ts
export * from "./generator-paths.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L22)

### "./generator-paths.types.js" (namespace export)

Re-exports all named exports from the "./generator-paths.types.js" module.

**Signature**

```ts
export * from "./generator-paths.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L23)

### "./generator-process.js" (namespace export)

Re-exports all named exports from the "./generator-process.js" module.

**Signature**

```ts
export * from "./generator-process.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L20)

### "./generator-process.types.js" (namespace export)

Re-exports all named exports from the "./generator-process.types.js" module.

**Signature**

```ts
export * from "./generator-process.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L21)

### "./generator-prompt.js" (namespace export)

Re-exports all named exports from the "./generator-prompt.js" module.

**Signature**

```ts
export * from "./generator-prompt.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L24)

### "./generator-prompt.types.js" (namespace export)

Re-exports all named exports from the "./generator-prompt.types.js" module.

**Signature**

```ts
export * from "./generator-prompt.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L25)

### "./options.js" (namespace export)

Re-exports all named exports from the "./options.js" module.

**Signature**

```ts
export * from "./options.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L3)

### "./prompt-driver.js" (namespace export)

Re-exports all named exports from the "./prompt-driver.js" module.

**Signature**

```ts
export * from "./prompt-driver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L9)

### "./scaffold-catalog.js" (namespace export)

Re-exports all named exports from the "./scaffold-catalog.js" module.

**Signature**

```ts
export * from "./scaffold-catalog.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L6)

### "./template-root.js" (namespace export)

Re-exports all named exports from the "./template-root.js" module.

**Signature**

```ts
export * from "./template-root.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L12)

### "./validate.js" (namespace export)

Re-exports all named exports from the "./validate.js" module.

**Signature**

```ts
export * from "./validate.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L13)

### CatalogManifest

**Signature**

```ts
declare const CatalogManifest: CatalogManifest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L8)

### resolveCatalogVersion

**Signature**

```ts
declare const resolveCatalogVersion: (
  manifest: CatalogManifest,
  name: string,
  spec: unknown,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/index.ts#L7)

## `launcher.ts`

Owns one Bun child until exit, forwarding terminal cancellation before releasing listeners.

### launchBun

Executes a literal entrypoint under Bun and joins its actual completion.

**Signature**

```ts
declare const launchBun: (entry: string, args: readonly string[], cwd?: string) => Promise<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/launcher.ts#L12)

## `options.ts`

Validates and normalizes pure creation options before selecting templates, destinations and optional installation or Git initialization.

### CREATE_CLOUDS

Supported cloud selections; none is the default.

**Signature**

```ts
declare const CREATE_CLOUDS: readonly ["aws", "none"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L9)

### CREATE_DEPLOYMENTS

Supported deployment selections; none is the default.

**Signature**

```ts
declare const CREATE_DEPLOYMENTS: readonly ["pulumi", "none"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L13)

### CREATE_JOBS

Supported explicit local job-provider selections.

**Signature**

```ts
declare const CREATE_JOBS: readonly ["inngest-docker", "effect-mq-docker", "trigger-docker"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L17)

### CREATE_OPTION_DEFAULTS

Minimal local defaults applied before explicit create flags are parsed.

**Signature**

```ts
declare const CREATE_OPTION_DEFAULTS: Readonly<{
  template: CreateTemplate;
  cloud: CreateCloud;
  deploy: CreateDeployment;
  jobs: CreateJobs | undefined;
  install: boolean;
  git: boolean;
  examples: boolean;
  forceEmptyDirectory: boolean;
  json: boolean;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L21)

### CREATE_TEMPLATES

Templates supported by explicit --template selection.

**Signature**

```ts
declare const CREATE_TEMPLATES: readonly ["minimal", "api", "agent", "fullstack"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L5)

### CreateCloud (type alias)

Supported cloud choice for project generation.

**Signature**

```ts
type CreateCloud = (typeof CREATE_CLOUDS)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L11)

### CreateDeployment (type alias)

Supported deployment choice for project generation.

**Signature**

```ts
type CreateDeployment = (typeof CREATE_DEPLOYMENTS)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L15)

### CreateJobs (type alias)

Supported local job provider selected by an explicit creation flag.

**Signature**

```ts
type CreateJobs = (typeof CREATE_JOBS)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L19)

### CreateOptions (interface)

Normalized creation flags preserving omitted directory and job-provider fields.

**Signature**

```ts
export interface CreateOptions {
  readonly name: string;
  readonly template: CreateTemplate;
  readonly cloud: CreateCloud;
  readonly deploy: CreateDeployment;
  readonly jobs?: CreateJobs;
  readonly install: boolean;
  readonly git: boolean;
  readonly examples: boolean;
  readonly directory?: string;
  readonly forceEmptyDirectory: boolean;
  readonly json: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L33)

### CreateOptionsContext (interface)

Additional JSON output policy used while parsing creation flags.

**Signature**

```ts
export interface CreateOptionsContext {
  readonly json?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L47)

### CreateOptionsError (class)

Public creation-flag usage failure with the stable RELKIT_CREATE_USAGE code.

**Signature**

```ts
declare class CreateOptionsError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L51)

### code (property)

Stable usage code reported by CreateOptionsError.

**Signature**

```ts
readonly code: "RELKIT_CREATE_USAGE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L55)

### CreateTemplate (type alias)

Supported template selected by an explicit creation flag.

**Signature**

```ts
type CreateTemplate = (typeof CREATE_TEMPLATES)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L7)

### normalizeCreateOptions

Parses non-interactive create flags and applies the cloud-free defaults.

**Signature**

```ts
declare const normalizeCreateOptions: (
  args: readonly string[],
  context?: CreateOptionsContext,
) => CreateOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/options.ts#L72)

## `project-manifest.schemas.ts`

### JsonObject

JSON object boundary, retaining unrelated package and workspace fields.

**Signature**

```ts
declare const JsonObject: Schema.$Record<Schema.String, Schema.Unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/project-manifest.schemas.ts#L4)

### ProjectManifest

Validated string-valued package fields owned by scaffold planning.

**Signature**

```ts
declare const ProjectManifest: Schema.StructWithRest<
  Schema.Struct<{
    readonly dependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
    readonly devDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
    readonly scripts: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
    readonly patchedDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
  }>,
  readonly [Schema.$Record<Schema.String, Schema.Unknown>]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/project-manifest.schemas.ts#L17)

### ScaffoldManifestSchema

Owned manifest fields; unrelated metadata keeps its authored order and shape.

**Signature**

```ts
declare const ScaffoldManifestSchema: Schema.StructWithRest<
  Schema.Struct<{
    readonly dependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
    readonly devDependencies: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
    readonly scripts: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
  }>,
  readonly [Schema.$Record<Schema.String, Schema.Unknown>]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/project-manifest.schemas.ts#L7)

### TemplateManifest

Required starter fields used by deployment customization.

**Signature**

```ts
declare const TemplateManifest: Schema.StructWithRest<
  Schema.Struct<{
    readonly dependencies: Schema.$Record<Schema.String, Schema.String>;
    readonly scripts: Schema.$Record<Schema.String, Schema.String>;
  }>,
  readonly [Schema.$Record<Schema.String, Schema.Unknown>]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/project-manifest.schemas.ts#L28)

## `prompt-driver.ts`

Defines the prompt driver's text, choice and cancellation contract shared by creator workflows and CLI scaffolding adapters.

### ChoicePromptOptions

**Signature**

```ts
declare const ChoicePromptOptions: ChoicePromptOptions<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.ts#L6)

### PromptDriver

**Signature**

```ts
declare const PromptDriver: PromptDriver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.ts#L7)

### PromptOption

**Signature**

```ts
declare const PromptOption: PromptOption<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.ts#L8)

### TextPromptOptions

**Signature**

```ts
declare const TextPromptOptions: TextPromptOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.ts#L9)

### createClackPromptDriver

Creates the public Clack adapter, forwarding fiber-owned cancellation to native prompts.

**Signature**

```ts
declare const createClackPromptDriver: (cancellationCode?: string) => PromptDriver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.ts#L17)

## `prompt-driver.types.ts`

One declared prompt choice with a label and optional explanatory hint.

### ChoicePromptOptions (interface)

Question and finite choices accepted by a prompt adapter.

**Signature**

```ts
export interface ChoicePromptOptions<Value extends string> {
  readonly message: string;
  readonly options: readonly PromptOption<Value>[];
  readonly initialValue?: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.types.ts#L30)

### PromptDriver (interface)

Clack-compatible native questions and progress output, with optional caller cancellation.

**Signature**

```ts
export interface PromptDriver {
  /**
   * Asks for text through the explicit, cancellation-aware native driver.
   * @param options - Explicit options retaining existing defaults.
   * @param signal - Optional caller cancellation signal.
   * @returns Decoded text; prompt interruption propagates to the native driver.
   */
  readonly text: (options: TextPromptOptions, signal?: AbortSignal) => Promise<string>;
  /**
   * Asks the native driver for one declared choice.
   * @typeParam Value - Union of declared native choice values.
   * @param options - Question, declared choices and optional initial selection.
   * @param signal - Optional caller cancellation signal.
   * @returns A Promise for the native choice; cancellation rejects with the configured public code.
   */
  readonly select: <Value extends string>(
    options: ChoicePromptOptions<Value>,
    signal?: AbortSignal,
  ) => Promise<Value>;
  /**
   * Asks the native driver for declared choices in selection order.
   * @typeParam Value - Union of declared native choice values.
   * @param options - Question, declared choices and optional required-selection policy.
   * @param signal - Optional caller cancellation signal.
   * @returns A Promise for selected native choices; cancellation rejects with the configured public code.
   */
  readonly multiselect: <Value extends string>(
    options: ChoicePromptOptions<Value> & { readonly required?: boolean },
    signal?: AbortSignal,
  ) => Promise<readonly Value[]>;
  /**
   * Asks for boolean consent and decodes the native answer.
   * @param options - Explicit options retaining existing defaults.
   * @param signal - Optional caller cancellation signal.
   * @returns Decoded consent; cancellation retains its original rejection.
   */
  readonly confirm: (
    options: {
      readonly message: string;
      readonly initialValue?: boolean;
    },
    signal?: AbortSignal,
  ) => Promise<boolean>;
  /**
   * Presents an existing explanatory note through the terminal adapter.
   * @param message - Existing user-facing diagnostic.
   * @param title - Title displayed by the native progress/prompt sink.
   * @returns Completion after the existing contract has been applied.
   */
  readonly note: (message: string, title?: string) => void;
  /**
   * Presents the existing flow introduction through the terminal adapter.
   * @param title - Title displayed by the native progress/prompt sink.
   * @returns Completion after the existing contract has been applied.
   */
  readonly intro: (title: string) => void;
  /**
   * Presents the existing flow completion through the terminal adapter.
   * @param message - Existing user-facing diagnostic.
   * @returns Completion after the existing contract has been applied.
   */
  readonly outro: (message: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.types.ts#L39)

### PromptOption (interface)

One declared prompt choice with a label and optional explanatory hint.

**Signature**

```ts
export interface PromptOption<Value extends string = string> {
  readonly value: Value;
  readonly label: string;
  readonly hint?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.types.ts#L5)

### TextPromptOptions (interface)

Text question with optional initial input and native validation callback.

**Signature**

```ts
export interface TextPromptOptions {
  readonly message: string;
  readonly placeholder?: string;
  readonly initialValue?: string;
  /**
   * Returns a user-facing validation message for unacceptable native text input.
   * @param value - Current native text input, possibly undefined.
   * @returns A rejection message/Error, or undefined when the text is acceptable.
   */
  readonly validate?: (value: string | undefined) => string | Error | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/prompt-driver.types.ts#L14)

## `scaffold-catalog.ts`

Declares portable feature dependency metadata and selected SDK owners used by creation and add manifest producers.

### DependencySection

**Signature**

```ts
declare const DependencySection: DependencySection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.ts#L6)

### SCAFFOLD_DEPENDENCIES

Versions copied into generated projects from each package's own release metadata.

**Signature**

```ts
declare const SCAFFOLD_DEPENDENCIES: Readonly<{
  "@cloudflare/workers-types": { version: string; section: "devDependencies" };
  "@relkit/aws": { version: string; section: "dependencies" };
  "@relkit/better-auth": { version: string; section: "dependencies" };
  "@relkit/cloudflare": { version: string; section: "dependencies" };
  "@relkit/docker": { version: string; section: "dependencies" };
  "@relkit/effect-mq": { version: string; section: "dependencies" };
  "@relkit/inspector": { version: string; section: "devDependencies" };
  "@relkit/inngest": { version: string; section: "dependencies" };
  "@relkit/drizzle": { version: string; section: "dependencies" };
  "@relkit/local": { version: string; section: "dependencies" };
  "@relkit/langchain": { version: string; section: "dependencies" };
  "@relkit/pulumi": { version: string; section: "dependencies" };
  "@relkit/redis": { version: string; section: "dependencies" };
  "@relkit/s3": { version: string; section: "dependencies" };
  "@relkit/trigger": { version: string; section: "dependencies" };
  "better-auth": { version: string; section: "dependencies" };
  "drizzle-kit": { version: string; section: "devDependencies" };
  "drizzle-orm": { version: string; section: "dependencies" };
  langchain: { version: string; section: "dependencies" };
  "@langchain/core": { version: string; section: "dependencies" };
  "@langchain/langgraph": { version: string; section: "dependencies" };
  langsmith: { version: string; section: "dependencies" };
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.ts#L12)

### ScaffoldDependency

**Signature**

```ts
declare const ScaffoldDependency: ScaffoldDependency;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.ts#L7)

### ScaffoldDependencyName

**Signature**

```ts
declare const ScaffoldDependencyName:
  | "drizzle-orm"
  | "@cloudflare/workers-types"
  | "@relkit/aws"
  | "@relkit/better-auth"
  | "@relkit/cloudflare"
  | "@relkit/docker"
  | "@relkit/effect-mq"
  | "@relkit/inspector"
  | "@relkit/inngest"
  | "@relkit/drizzle"
  | "@relkit/local"
  | "@relkit/langchain"
  | "@relkit/pulumi"
  | "@relkit/redis"
  | "@relkit/s3"
  | "@relkit/trigger"
  | "better-auth"
  | "drizzle-kit"
  | "langchain"
  | "@langchain/core"
  | "@langchain/langgraph"
  | "langsmith";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.ts#L8)

### scaffoldDependency

Selects one supported dependency from the release's portable scaffold catalog.

**Signature**

```ts
declare const scaffoldDependency: (name: ScaffoldDependencyName) => ScaffoldDependency;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.ts#L66)

## `scaffold-catalog.types.ts`

### DependencySection (type alias)

Manifest section in which a scaffold introduces a supported dependency.

**Signature**

```ts
type DependencySection = "dependencies" | "devDependencies";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.types.ts#L4)

### ScaffoldDependency (interface)

Concrete release-supported version and owning project manifest section.

**Signature**

```ts
export interface ScaffoldDependency {
  readonly version: string;
  readonly section: DependencySection;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.types.ts#L7)

### ScaffoldDependencyName (type alias)

Intentional scaffold dependency names, retaining their literal keyed catalog contract.

**Signature**

```ts
type ScaffoldDependencyName = keyof typeof SCAFFOLD_DEPENDENCIES;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/scaffold-catalog.types.ts#L13)

## `template-root.ts`

### resolveTemplateRoot

Preserves synchronous template-root resolution without a hidden filesystem dependency.

**Signature**

```ts
declare const resolveTemplateRoot: (
  context: Pick<GenerateProjectContext, "cwd" | "templateRoot">,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/template-root.ts#L32)

### resolveTemplateRootEffect

Finds explicit, packed or source-owned templates through read-only path authority.

**Signature**

```ts
declare const resolveTemplateRootEffect: (
  context: Pick<GenerateProjectContext, "cwd" | "templateRoot">,
) => Effect.Effect<string, GeneratorIoError, GeneratorPaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/template-root.ts#L14)

## `validate-errors.ts`

Stable public creation-validation constructor, independent of native I/O adapters.

### CreateValidationError (class)

Stable public creation-validation constructor, independent of native I/O adapters.

**Signature**

```ts
declare class CreateValidationError { constructor(
    readonly code: string,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-errors.ts#L2)

## `validate-paths.ts`

### canonicalizeMissingPathEffect

Canonicalizes missing child segments only after proving the existing parent is a directory.

**Signature**

```ts
declare const canonicalizeMissingPathEffect: (
  path: string,
) => Effect.Effect<string, GeneratorDomainError, GeneratorPaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L52)

### existingDirectoryEffect

Resolves an existing real directory without permitting symlink indirection.

**Signature**

```ts
declare const existingDirectoryEffect: (
  path: string,
  label: string,
) => Effect.Effect<string, GeneratorDomainError, GeneratorPaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L96)

### failure

Constructs a typed failure retaining the exact public validation code and message.

**Signature**

```ts
declare const failure: (
  code: string,
  message: string,
) => Effect.Effect<never, GeneratorDomainError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L140)

### inspectDestinationEffect

Inspects only an absent or real directory destination without following symlinks.

**Signature**

```ts
declare const inspectDestinationEffect: (
  path: string,
) => Effect.Effect<DestinationState, GeneratorDomainError, GeneratorPaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L19)

### invalid

Carries existing validation failures in the internal typed channel.

**Signature**

```ts
declare const invalid: (message: string) => GeneratorDomainError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L130)

### isAncestorOrSame

Checks a canonical path relationship using no I/O.

**Signature**

```ts
declare const isAncestorOrSame: (parent: string, child: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate-paths.ts#L120)

## `validate.ts`

### CreateValidationContext

**Signature**

```ts
declare const CreateValidationContext: CreateValidationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L17)

### CreateValidationError

**Signature**

```ts
declare const CreateValidationError: typeof CreateValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L21)

### ValidatedCreateOptions

**Signature**

```ts
declare const ValidatedCreateOptions: ValidatedCreateOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L17)

### isValidPackageName

Checks unscoped or scoped npm names without filesystem or Effect authority.

**Signature**

```ts
declare const isValidPackageName: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L43)

### resolveCreateDestination

Preserves synchronous safe-destination resolution and its stable public errors.

**Signature**

```ts
declare const resolveCreateDestination: (
  options: Pick<CreateOptions, "name" | "directory">,
  context?: CreateValidationContext,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L155)

### resolveCreateDestinationEffect

Resolves a safe creation destination through explicit read-only path authority.

**Signature**

```ts
declare const resolveCreateDestinationEffect: (
  options: Pick<CreateOptions, "directory" | "name">,
  context?: CreateValidationContext | undefined,
) => Effect.Effect<string, GeneratorDomainError, GeneratorPaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L71)

### validateCreateOptions

Preserves synchronous destination validation and its existing immutable result.

**Signature**

```ts
declare const validateCreateOptions: (
  options: CreateOptions,
  context?: CreateValidationContext,
) => ValidatedCreateOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L168)

### validateCreateOptionsEffect

Validates destination state using the same path service as the existing synchronous API.

**Signature**

```ts
declare const validateCreateOptionsEffect: (
  options: CreateOptions,
  context?: CreateValidationContext | undefined,
) => Effect.Effect<
  Readonly<{
    destination: string;
    destinationExists: boolean;
    destinationEmpty: boolean;
    name: string;
    template: CreateTemplate;
    cloud: CreateCloud;
    deploy: CreateDeployment;
    jobs?: CreateJobs;
    install: boolean;
    git: boolean;
    examples: boolean;
    directory?: string;
    forceEmptyDirectory: boolean;
    json: boolean;
  }>,
  GeneratorDomainError,
  GeneratorPaths
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L117)

### validatePackageName

Asserts the existing package-name contract using its unchanged public constructor.

**Signature**

```ts
declare const validatePackageName: (value: unknown) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.ts#L57)

## `validate.types.ts`

### CreateValidationContext (interface)

Existing read-only creation-validation context.

**Signature**

```ts
export interface CreateValidationContext {
  readonly cwd?: string;
  readonly homeDirectory?: string;
  readonly temporaryDirectory?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.types.ts#L4)

### DestinationState (interface)

Destination facts obtained before any generation mutation.

**Signature**

```ts
export interface DestinationState {
  readonly exists: boolean;
  readonly empty: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.types.ts#L18)

### ValidatedCreateOptions (interface)

Existing validated creation result with inspected destination state.

**Signature**

```ts
export interface ValidatedCreateOptions extends CreateOptions {
  readonly destination: string;
  readonly destinationExists: boolean;
  readonly destinationEmpty: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/create-relkit/src/validate.types.ts#L11)

---

# Drizzle API
Source: https://relkit.dev/docs/api/drizzle

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineDrizzleService](/docs/api/drizzle#definedrizzleservice)
- [defineModel](/docs/api/drizzle#definemodel)
- [activateDrizzleService](/docs/api/drizzle#activatedrizzleservice)

For configuration and examples, read [Database](/docs/modules/database), [local docker](/docs/modules/database/local-docker), [drizzle](/docs/modules/database/drizzle).

For a complete workflow, follow [register users in a transaction](/guides/database/register-users-in-a-transaction), [email password sign in](/guides/auth/email-password-sign-in).

## Public imports

- `@relkit/drizzle` — 23 exports
- `@relkit/drizzle/sqlite` — 24 exports
- `@relkit/drizzle/pg` — 24 exports
- `@relkit/drizzle/mysql` — 24 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                               | Kind  | Import from                                                                                | Example                                                                                                                           |
| --------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| [activateDrizzleService](/docs/api/drizzle#activatedrizzleservice)                | Value | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/better-auth/tests/auth/acquisition.test.ts#L55)             |
| [ApplicationEnv](/docs/api/drizzle#applicationenv-type-alias)                     | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [BaseOperations](/docs/api/drizzle#baseoperations-interface)                      | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [DatabaseContext](/docs/api/drizzle#databasecontext-type-alias)                   | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/tests/effect/review-regressions.test.ts#L98)        |
| [defineDrizzleService](/docs/api/drizzle#definedrizzleservice-1)                  | Value | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [API example](/docs/api/drizzle#definedrizzleservice-1)                                                                           |
| [defineModel](/docs/api/drizzle#definemodel-1)                                    | Value | `@relkit/drizzle`                                                                          | [API example](/docs/api/drizzle#definemodel-1)                                                                                    |
| [defineModel](/docs/api/drizzle#definemodel-4)                                    | Value | `@relkit/drizzle/sqlite`                                                                   | [Source example](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/models/users.model.ts#L6)  |
| [defineModel](/docs/api/drizzle#definemodel-3)                                    | Value | `@relkit/drizzle/pg`                                                                       | [Module example](/docs/modules/database)                                                                                          |
| [defineModel](/docs/api/drizzle#definemodel-2)                                    | Value | `@relkit/drizzle/mysql`                                                                    | [Module example](/docs/modules/database)                                                                                          |
| [DeleteArgs](/docs/api/drizzle#deleteargs-interface)                              | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [DialectDatabase](/docs/api/drizzle#dialectdatabase-type-alias-2)                 | Type  | `@relkit/drizzle/sqlite`                                                                   | [Module example](/docs/modules/database)                                                                                          |
| [DialectDatabase](/docs/api/drizzle#dialectdatabase-type-alias-1)                 | Type  | `@relkit/drizzle/pg`                                                                       | [Module example](/docs/modules/database)                                                                                          |
| [DialectDatabase](/docs/api/drizzle#dialectdatabase-type-alias)                   | Type  | `@relkit/drizzle/mysql`                                                                    | [Module example](/docs/modules/database)                                                                                          |
| [DrizzleActivationOptions](/docs/api/drizzle#drizzleactivationoptions-interface)  | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [DrizzleCapability](/docs/api/drizzle#drizzlecapability-interface)                | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [DrizzleOverrides](/docs/api/drizzle#drizzleoverrides-type-alias)                 | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [DrizzleServiceDescriptor](/docs/api/drizzle#drizzleservicedescriptor-type-alias) | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [FindManyArgs](/docs/api/drizzle#findmanyargs-interface)                          | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [FindOneArgs](/docs/api/drizzle#findoneargs-interface)                            | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [InsertArgs](/docs/api/drizzle#insertargs-interface)                              | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [ModelDescriptor](/docs/api/drizzle#modeldescriptor-interface)                    | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [ModelExtensionContext](/docs/api/drizzle#modelextensioncontext-interface)        | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [Row](/docs/api/drizzle#row-type-alias)                                           | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [TableOverrides](/docs/api/drizzle#tableoverrides-type-alias)                     | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [TableZodSchemas](/docs/api/drizzle#tablezodschemas-interface)                    | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [Update](/docs/api/drizzle#update-type-alias)                                     | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [UpdateArgs](/docs/api/drizzle#updateargs-interface)                              | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Source example](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/models/users.model.ts#L14) |
| [UpsertArgs](/docs/api/drizzle#upsertargs-interface)                              | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |
| [Where](/docs/api/drizzle#where-type-alias)                                       | Type  | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql` | [Module example](/docs/modules/database)                                                                                          |

## `activate.ts`

Validates the selected ORM before loading runtime activation or calling the native factory.

### activateDrizzleService

Acquires a database using the existing owner after selected dependency validation.

**Signature**

```ts
declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activate.ts#L12)

## `activation.ts`

### activateDrizzleService

Activates a service once per descriptor object and returns its client, context, and close hook.
Repeated calls share the first activation; close does not evict the cached activation.
Isolated acquisition bypasses that cache and transfers close ownership to the caller.

**Example**

```ts
import { activateDrizzleService, defineDrizzleService } from "@relkit/drizzle";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

if (typeof Bun !== "undefined") {
  const { Database } = await import("bun:sqlite");
  const { drizzle } = await import("drizzle-orm/bun-sqlite");
  const users = sqliteTable("users", { id: integer().primaryKey() });
  const service = defineDrizzleService({
    schema: { users },
    client: () => drizzle({ client: new Database(":memory:") }),
    dispose: (database) => database.$client.close(),
  });
  const active = await activateDrizzleService(service, {});
  try {
    console.assert(active.context.users !== undefined);
  } finally {
    await active.close();
  }
}
```

**Signature**

```ts
declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activation.ts#L58)

Since v0.1.0

### DrizzleActivation

**Signature**

```ts
declare const DrizzleActivation: DrizzleActivation<Service>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activation.ts#L22)

### DrizzleActivationOptions

**Signature**

```ts
declare const DrizzleActivationOptions: DrizzleActivationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activation.ts#L22)

## `activation.types.ts`

### DrizzleActivation (interface)

Frozen public activation; resource ownership ends at close.

**Signature**

```ts
export interface DrizzleActivation<Service extends DrizzleServiceDescriptor<any, any, any, any>> {
  /** Native escape hatch; callers must use admitted APIs to guarantee orderly close. */
  readonly client: Service extends DrizzleServiceDescriptor<any, infer Client, any, any>
    ? Client
    : never;
  readonly context: DatabaseContext<Service>;
  /**
   * Stops admission and releases the owner after admitted native work settles.
   * @returns Shared close Promise; later calls observe the same completion.
   */
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activation.types.ts#L16)

### DrizzleActivationOptions (interface)

Acquisition policy for an application that owns its database lifetime.

**Signature**

```ts
export interface DrizzleActivationOptions {
  /** Bypasses descriptor sharing; the caller must close this activation. */
  readonly isolated?: boolean;
  /** Configured observation services captured by the compatibility owner. */
  readonly instrumentation?: Context.Context<never>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/activation.types.ts#L5)

## `context.ts`

### createDatabaseContext

Constructs models without acquiring another client.

**See**

- `activateDrizzleService` for the checked public owner lifecycle.

**Signature**

```ts
declare const createDatabaseContext: <Service extends DrizzleServiceDescriptor<any, any, any, any>>(
  service: Service,
  runtime: DrizzleServiceRuntime,
  database: unknown,
  run: ContextRunner,
) => DatabaseContext<Service>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/context.ts#L22)

## `context.types.ts`

### ContextRunner (type alias)

Executes work at the existing owner edge; transaction children borrow their parent lease.

**Signature**

```ts
type ContextRunner = <A>(effect: Effect.Effect<A, DrizzleFailure>, operation: string) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/context.types.ts#L11)

## `coordination.ts`

### withDrizzleSqliteWork

Coordinates raw specialized SDK work with portable SQLite operations.

**Signature**

```ts
declare const withDrizzleSqliteWork: <A, E, R>(
  activation: object,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | DrizzleFailure, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/coordination.ts#L17)

## `failure.ts`

### DrizzleFailure (class)

Expected native database, validation or owner-admission failure.

**Signature**

```ts
declare class DrizzleFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/failure.ts#L6)

### nativeCall

Suspends an uncancellable SDK call until actual completion.

**See**

- `runDrizzlePromise` for execution at the owning runtime boundary.

**Signature**

```ts
declare const nativeCall: <A>(
  operation: string,
  run: () => A | PromiseLike<A>,
) => Effect.Effect<A, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/failure.ts#L20)

### runDrizzlePromise

Executes a compatibility edge retaining original native rejection identity.

**Example**

```ts
import { Effect, Layer, ManagedRuntime } from "effect";
import { runDrizzlePromise } from "@relkit/drizzle/internal";
const owner = ManagedRuntime.make(Layer.empty);
try {
  await runDrizzlePromise(owner, Effect.succeed(1));
} finally {
  await owner.dispose();
}
```

**Signature**

```ts
declare const runDrizzlePromise: <A, E, R, ER>(
  runtime: ManagedRuntime.ManagedRuntime<R, ER>,
  effect: Effect.Effect<A, E, R>,
  options?: Effect.RunOptions,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/failure.ts#L50)

### squashDrizzleCause

Translates one native failure without erasing mixed cleanup/interruption causes.

**Signature**

```ts
declare const squashDrizzleCause: <E>(cause: Cause.Cause<E>) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/failure.ts#L66)

## `index.ts`

Lazy Drizzle declarations and stable Promise model/transaction compatibility APIs.

### ApplicationEnv

**Signature**

```ts
declare const ApplicationEnv: Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L10)

### BaseOperations

**Signature**

```ts
declare const BaseOperations: BaseOperations<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L11)

### DatabaseContext

**Signature**

```ts
declare const DatabaseContext: DatabaseContext<Service>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L12)

### DeleteArgs

**Signature**

```ts
declare const DeleteArgs: DeleteArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L13)

### DrizzleActivationOptions

**Signature**

```ts
declare const DrizzleActivationOptions: DrizzleActivationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L6)

### DrizzleCapability

**Signature**

```ts
declare const DrizzleCapability: DrizzleCapability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L14)

### DrizzleOverrides

**Signature**

```ts
declare const DrizzleOverrides: DrizzleOverrides<Tables>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L15)

### DrizzleServiceDescriptor

**Signature**

```ts
declare const DrizzleServiceDescriptor: DrizzleServiceDescriptor<Id, Client, Schema, Models>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L16)

### FindManyArgs

**Signature**

```ts
declare const FindManyArgs: FindManyArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L17)

### FindOneArgs

**Signature**

```ts
declare const FindOneArgs: FindOneArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L18)

### InsertArgs

**Signature**

```ts
declare const InsertArgs: InsertArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L19)

### ModelDescriptor

**Signature**

```ts
declare const ModelDescriptor: ModelDescriptor<T, Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L20)

### ModelExtensionContext

**Signature**

```ts
declare const ModelExtensionContext: ModelExtensionContext<T, Database>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L21)

### Row

**Signature**

```ts
declare const Row: {
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L22)

### TableOverrides

**Signature**

```ts
declare const TableOverrides: TableOverrides<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L23)

### TableZodSchemas

**Signature**

```ts
declare const TableZodSchemas: TableZodSchemas<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L24)

### Update

**Signature**

```ts
declare const Update: Partial<{
  [
    K in keyof ({
      [
        Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
      ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    } & {
      [
        Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<
          Key,
          T["_"]["columns"][Key],
          false
        >
      ]?:
        | (T["_"]["columns"][Key]["_"]["notNull"] extends true
            ? T["_"]["columns"][Key]["_"]["data"]
            : T["_"]["columns"][Key]["_"]["data"] | null)
        | undefined;
    })
  ]: ({
    [
      Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
    ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  } & {
    [
      Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<Key, T["_"]["columns"][Key], false>
    ]?:
      | (T["_"]["columns"][Key]["_"]["notNull"] extends true
          ? T["_"]["columns"][Key]["_"]["data"]
          : T["_"]["columns"][Key]["_"]["data"] | null)
      | undefined;
  })[K];
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L25)

### UpdateArgs

**Signature**

```ts
declare const UpdateArgs: UpdateArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L26)

### UpsertArgs

**Signature**

```ts
declare const UpsertArgs: UpsertArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L27)

### Where

**Signature**

```ts
declare const Where: Partial<{
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L28)

### activateDrizzleService

**Signature**

```ts
declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L5)

### defineDrizzleService

**Signature**

```ts
declare const defineDrizzleService: <
  Client,
  const Schema extends Readonly<Record<string, unknown>>,
  const Models extends DrizzleModelMap<TablesOf<Schema>> = {},
>(
  options: DefineDrizzleServiceOptions<Client, Schema, Models>,
) => DrizzleServiceDescriptor<string, Client, Schema, Models>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L8)

### defineModel

**Signature**

```ts
declare const defineModel: <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/index.ts#L7)

## `internal.ts`

Server-only runtime ownership, typed failures and borrowed-work composition.

### DrizzleActivation

**Signature**

```ts
declare const DrizzleActivation: DrizzleActivation<Service>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L6)

### DrizzleFailure

**Signature**

```ts
declare const DrizzleFailure: typeof DrizzleFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L9)

### DrizzleOwner

**Signature**

```ts
declare const DrizzleOwner: typeof DrizzleOwner;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L11)

### DrizzleOwnerInterface

**Signature**

```ts
declare const DrizzleOwnerInterface: DrizzleOwnerInterface;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L18)

### DrizzleServiceDescriptor

**Signature**

```ts
declare const DrizzleServiceDescriptor: DrizzleServiceDescriptor<Id, Client, Schema, Models>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L8)

### activateDrizzleService

**Signature**

```ts
declare const activateDrizzleService: <
  Service extends DrizzleServiceDescriptor<any, any, any, any>,
>(
  service: Service,
  env: Readonly<Record<string, unknown>>,
  options?: DrizzleActivationOptions,
) => Promise<DrizzleActivation<Service>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L5)

### drizzleInstrumentationOf

**Signature**

```ts
declare const drizzleInstrumentationOf: (activation: object) => Context<never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L14)

### drizzleOwnerLayer

**Signature**

```ts
declare const drizzleOwnerLayer: (
  declaration: DrizzleServiceRuntime,
  env: Readonly<Record<string, unknown>>,
) => Layer<DrizzleOwner, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L12)

### drizzleRuntimeOf

**Signature**

```ts
declare const drizzleRuntimeOf: (value: object) => DrizzleServiceRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L7)

### inheritNativeLeases

**Signature**

```ts
declare const inheritNativeLeases: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L21)

### nativeCall

**Signature**

```ts
declare const nativeCall: <A>(
  operation: string,
  run: () => A | PromiseLike<A>,
) => Effect<A, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L9)

### observeSpecializedOperation

**Signature**

```ts
declare const observeSpecializedOperation: <A, E, R>(
  operation: `database.${string}` | `auth.${string}`,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L17)

### operationEffect

**Signature**

```ts
declare const operationEffect: (
  binding: ModelBinding,
  name: string,
  args: unknown,
) => Effect<unknown, DrizzleFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L19)

### redactSpecializedTrace

**Signature**

```ts
declare const redactSpecializedTrace: <A, E, R>(
  effect: Effect<A, E, R>,
) => Effect<A, E, Exclude<R, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L22)

### runDrizzlePromise

**Signature**

```ts
declare const runDrizzlePromise: <A, E, R, ER>(
  runtime: ManagedRuntime<R, ER>,
  effect: Effect<A, E, R>,
  options?: RunOptions,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L9)

### runDrizzleWorkPromise

**Signature**

```ts
declare const runDrizzleWorkPromise: <A, E>(activation: object, effect: Effect<A, E>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L15)

### runSpecializedTrace

**Signature**

```ts
declare const runSpecializedTrace: <A>(operation: string, run: () => Promise<A>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L17)

### squashDrizzleCause

**Signature**

```ts
declare const squashDrizzleCause: <E>(cause: Cause<E>) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L9)

### withDrizzleSqliteWork

**Signature**

```ts
declare const withDrizzleSqliteWork: <A, E, R>(
  activation: object,
  effect: Effect<A, E, R>,
) => Effect<A, E | DrizzleFailure, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L20)

### withDrizzleWork

**Signature**

```ts
declare const withDrizzleWork: <A, E, R>(
  activation: object,
  effect: Effect<A, E, R>,
) => Effect<A, E | DrizzleFailure, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/internal.ts#L13)

## `metadata.ts`

Extracts native table and column metadata for portable model validation and activation.
Dialect table utilities avoid importing unrelated native driver database declarations.

### dialectFor

Resolves a supported table dialect using Drizzle's entity guards.

**Throws**

TypeError for unsupported entities.

**Signature**

```ts
declare const dialectFor: (table: Table) => "pg" | "mysql" | "sqlite";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/metadata.ts#L54)

### extractTables

Filters relations and other schema values from supported tables.

**Throws**

TypeError when no supported table exists.

**Signature**

```ts
declare const extractTables: (schema: Readonly<Record<string, unknown>>) => TableMap;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/metadata.ts#L40)

### inspectTables

Discovers one consistent dialect and unique table selectors.

**Throws**

TypeError for absent tables or mixed/unsupported dialects.

**Signature**

```ts
declare const inspectTables: (tables: TableMap) => {
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly metadata: Readonly<Record<string, TableMetadata>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/metadata.ts#L18)

## `model.ts`

Declares frozen model extensions and binds their native calls to the owning database admission scope.
Dialect leaves provide precise database methods while shared descriptors preserve authored operation inference.

### defineModel

Adds named table methods with an injected table and transaction-aware Drizzle client.
Use service overrides, not extensions, to replace the six reserved CRUD operations.
Select a dialect entrypoint when an extension uses the injected native database.

**Throws**

TypeError for missing, non-callable or reserved extensions.

**Example**

```ts
import { defineModel } from "@relkit/drizzle/sqlite";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const users = sqliteTable("users", { id: integer().primaryKey() });
const model = defineModel({
  table: users,
  extend: { firstTen: ({ table, database }) => database.select().from(table).limit(10) },
});
console.assert(model.extensionNames.includes("firstTen"));
```

**Signature**

```ts
declare const defineModel: <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.ts#L54)

Since v0.1.0

### RESERVED_OPERATIONS

Reserved base operations; authored extensions may not shadow these names.

**Signature**

```ts
declare const RESERVED_OPERATIONS: readonly [
  "findOne",
  "findMany",
  "insert",
  "update",
  "upsert",
  "delete",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.ts#L20)

### createBoundModel

Binds public Promise methods to the owning Effect workflows.

**Signature**

```ts
declare const createBoundModel: (binding: ModelBinding, model?: ModelDescriptorAny) => object;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.ts#L101)

### modelRuntimeOf

Resolves hidden pure extension metadata.

**Throws**

TypeError for invalid descriptors.

**Signature**

```ts
declare const modelRuntimeOf: (value: ModelDescriptorAny) => ModelRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.ts#L87)

## `model.types.ts`

Native model injection contracts without an implicit database driver selection.

### DefineModel (type alias)

Native model authoring signature specialized by an explicitly selected dialect entrypoint.

**Signature**

```ts
type DefineModel<Database> = <
  const T extends Table,
  const Extensions extends ModelExtensionMap<T, Database>,
>(options: {
  readonly table: T;
  readonly extend: NonEmptyExtensions<Extensions>;
}) => ModelDescriptor<T, Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L60)

### ModelDescriptor (interface)

Frozen lazy model descriptor retaining authored extension types.

**Signature**

```ts
export interface ModelDescriptor<
  T extends Table,
  Extensions extends ModelExtensionMap<T> = ModelExtensionMap<T>,
> {
  readonly table: T;
  readonly extensionNames: readonly Extract<keyof Extensions, string>[];
  readonly [MODEL_TYPES]: Extensions;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L47)

### ModelDescriptorAny (type alias)

Internal erased model descriptor used for pure discovery.

**Signature**

```ts
type ModelDescriptorAny = ModelDescriptor<Table, ModelExtensionMap<Table>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L57)

### ModelExtension (type alias)

Authored native extension with inferred caller arguments/results.

**Signature**

```ts
type ModelExtension<T extends Table, Database = never> = (
  context: ModelExtensionContext<T, Database>,
  ...args: any[]
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L20)

### ModelExtensionContext (interface)

Injected table and transaction-bound native database.

**Signature**

```ts
export interface ModelExtensionContext<T extends Table, Database = never> {
  readonly table: T;
  readonly database: Database;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L8)

### ModelExtensionMap (type alias)

Named authored extension functions.

**Signature**

```ts
type ModelExtensionMap<T extends Table, Database = never> = Readonly<
  Record<string, ModelExtension<T, Database>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L29)

### NonEmptyExtensions (type alias)

Rejects declarations without any custom methods.

**Signature**

```ts
type NonEmptyExtensions<Extensions extends Readonly<Record<string, unknown>>> =
  keyof Extensions extends never ? never : Extensions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/model.types.ts#L37)

## `mutations.ts`

### insert

Inserts one row, recovering MySQL rows via a declared unique key.

**Signature**

```ts
declare const insert: (
  binding: ModelBinding,
  data: unknown,
) => Effect.Effect<unknown, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mutations.ts#L14)

### remove

Deletes one row while preserving dialect return behavior.

**Signature**

```ts
declare const remove: (
  binding: ModelBinding,
  where: Record<string, unknown>,
) => Effect.Effect<{} | null, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mutations.ts#L77)

### update

Updates one selected row with dialect-aware returning/recovery.

**Signature**

```ts
declare const update: (
  binding: ModelBinding,
  where: Record<string, unknown>,
  data: unknown,
) => Effect.Effect<{} | null, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mutations.ts#L44)

## `mysql.ts`

mysql native model typing; imports only this selected dialect's upstream declarations.

### "./index.js" (namespace export)

Re-exports all named exports from the "./index.js" module.

**Signature**

```ts
export * from "./index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mysql.ts#L5)

### DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

**Signature**

```ts
type DialectDatabase = Omit<MySqlAsyncDatabase<any, any>, "query">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mysql.ts#L8)

### defineModel

Declares lazy native extensions with this dialect's real transaction client type.

**Signature**

```ts
declare const defineModel: DefineModel<DialectDatabase>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/mysql.ts#L11)

## `native-leases.ts`

### NativeLeases

Effect-local owner/physical-client leases, absent for independent callers.

**Signature**

```ts
declare const NativeLeases: Context.Reference<NativeLeaseContext>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L8)

### closeNativeLease

Drains retained descendants, then atomically closes the token at zero.

**Signature**

```ts
declare const closeNativeLease: (lease: NativeLease) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L96)

### inheritNativeLeases

Carries active parent leases into a new native Promise execution edge.

**Signature**

```ts
declare const inheritNativeLeases: <A, E, R>(
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L20)

### makeNativeLease

Creates an Effect-owned descendant lease.

**Signature**

```ts
declare const makeNativeLease: (key: object) => Effect.Effect<
  {
    key: object;
    state: Ref.Ref<{ accepting: boolean; closing: boolean; borrowers: number }>;
    drained: Latch.Latch;
  },
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L47)

### releaseNativeLease

Releases one retained descendant after safe native settlement.

**Signature**

```ts
declare const releaseNativeLease: (lease: NativeLease) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L79)

### retainNativeLease

Retains a still-active parent token atomically.

**Signature**

```ts
declare const retainNativeLease: (lease: NativeLease) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L62)

### runWithNativeLeases

Makes native SDK callbacks inherit the currently retained Effect leases.

**Signature**

```ts
declare const runWithNativeLeases: <A>(leases: NativeLeaseContext, run: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.ts#L38)

## `native-leases.types.ts`

### NativeLease (interface)

Effect-owned ephemeral lease with a drain barrier for retained descendants.

**Signature**

```ts
export interface NativeLease {
  readonly key: object;
  readonly state: Ref.Ref<{
    readonly accepting: boolean;
    readonly closing: boolean;
    readonly borrowers: number;
  }>;
  readonly drained: Latch.Latch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.types.ts#L4)

### NativeLeaseContext (interface)

Native transport for exact owner and physical client capabilities.

**Signature**

```ts
export interface NativeLeaseContext {
  readonly owner?: NativeLease;
  readonly sqlite?: NativeLease;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/native-leases.types.ts#L15)

## `operation-tracing.ts`

### observeSpecializedOperation

Observes specialized work once through the configured caller sinks.

**Example**

```ts
import { Effect } from "effect";
import { observeSpecializedOperation } from "@relkit/drizzle/internal";
await Effect.runPromise(observeSpecializedOperation("auth.session", Effect.succeed(null)));
```

**Signature**

```ts
declare const observeSpecializedOperation: <A, E, R>(
  operation: `database.${string}` | `auth.${string}`,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operation-tracing.ts#L39)

### runSpecializedTrace

Bridges invocation parenting without capturing native rows or auth sessions.

**Signature**

```ts
declare const runSpecializedTrace: <A>(operation: string, run: () => Promise<A>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operation-tracing.ts#L62)

## `operations.ts`

### operationEffect

Composes overrides and MySQL write/recovery transaction ownership.

**Example**

````ts
Compose a page with an existing owner and table binding
```ts
import { Effect } from "effect";
import type { ManagedRuntime } from "effect";
import { DrizzleFailure, DrizzleOwner, operationEffect, runDrizzlePromise } from "@relkit/drizzle/internal";
function page(owner: ManagedRuntime.ManagedRuntime<DrizzleOwner, DrizzleFailure>, binding: Parameters<typeof operationEffect>[0]) {
  return runDrizzlePromise(owner, Effect.gen(function* () {
    const service = yield* DrizzleOwner;
    return yield* service.work(operationEffect(binding, "findMany", { limit: 10 }));
  }));
}
````

````

**Signature**

```ts
declare const operationEffect: (binding: ModelBinding, name: string, args: unknown) => Effect.Effect<unknown, DrizzleFailure>
````

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.ts#L41)

### runOperation

Runs one lazy CRUD workflow at its compatibility edge.

**Signature**

```ts
declare const runOperation: (
  binding: ModelBinding,
  name: string,
  args: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.ts#L18)

## `operations.types.ts`

### BaseOperations (interface)

Stable public Promise CRUD contract over one table.

**Signature**

```ts
export interface BaseOperations<T extends Table> {
  /**
   * Selects one row by a complete unique key.
   * @param args - Unique selector.
   * @returns Matching row or null, rejecting invalid selectors/native failures.
   */
  findOne(args: FindOneArgs<T>): Promise<Row<T> | null>;

  /**
   * Selects a bounded ordered page.
   * @param args - Optional filters, ordering and pagination.
   * @returns Validated rows in driver order.
   */
  findMany(args?: FindManyArgs<T>): Promise<Row<T>[]>;

  /**
   * Inserts one row without automatic retries.
   * @param args - Insert values.
   * @returns Validated inserted row.
   */
  insert(args: InsertArgs<T>): Promise<Row<T>>;

  /**
   * Updates one selected row without automatic retries.
   * @param args - Unique selector and partial update values.
   * @returns Updated row or null when absent.
   */
  update(args: UpdateArgs<T>): Promise<Row<T> | null>;

  /**
   * Selects then inserts or updates using portable dialect semantics.
   * @param args - Unique selector and create/update branches.
   * @returns Resulting row; this portable read/write sequence is not an atomic SQL upsert.
   */
  upsert(args: UpsertArgs<T>): Promise<Row<T>>;

  /**
   * Removes one selected row without automatic retries.
   * @param args - Complete unique selector.
   * @returns Deleted row or null when absent.
   */
  delete(args: DeleteArgs<T>): Promise<Row<T> | null>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L88)

### DeleteArgs (interface)

Complete unique selector for deletion.

**Signature**

```ts
export interface DeleteArgs<T extends Table> {
  readonly where: Where<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L80)

### FindManyArgs (interface)

Bounded ordered page filters; default limit is 100.

**Signature**

```ts
export interface FindManyArgs<T extends Table> {
  readonly where?: Where<T>;
  readonly orderBy?: {
    readonly field: Extract<keyof Row<T>, string>;
    readonly direction: "asc" | "desc";
  };
  readonly limit?: number;
  readonly offset?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L39)

### FindOneArgs (interface)

Complete unique selector for one row.

**Signature**

```ts
export interface FindOneArgs<T extends Table> {
  readonly where: Where<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L31)

### Insert (type alias)

Insert values retaining nullable, default and generated-column inference.

**Signature**

```ts
type Insert<T extends Table> = InferInsertModel<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L13)

### InsertArgs (interface)

Single-row insertion values.

**Signature**

```ts
export interface InsertArgs<T extends Table> {
  readonly data: Insert<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L53)

### Row (type alias)

Persisted row inferred from a table.

**Signature**

```ts
type Row<T extends Table> = InferSelectModel<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L7)

### Update (type alias)

Partial insert-compatible update values.

**Signature**

```ts
type Update<T extends Table> = Partial<Insert<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L19)

### UpdateArgs (interface)

Complete selector and partial update values.

**Signature**

```ts
export interface UpdateArgs<T extends Table> {
  readonly where: Where<T>;
  readonly data: Update<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L61)

### UpsertArgs (interface)

Selector and separate create/update branches.

**Signature**

```ts
export interface UpsertArgs<T extends Table> {
  readonly where: Where<T>;
  readonly create: Insert<T>;
  readonly update: Update<T>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L70)

### Where (type alias)

Column equality filter; unique operations require a complete selector.

**Signature**

```ts
type Where<T extends Table> = Partial<Row<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.types.ts#L25)

## `operations.utils.ts`

### call

Calls a checked native method with its original receiver.

**Throws**

TypeError when the method is unavailable.

**Signature**

```ts
declare const call: (target: unknown, name: string, ...args: unknown[]) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L77)

### clause

Builds equality predicates, treating null as SQL IS NULL.

**Throws**

TypeError for undefined values or unknown columns.

**Signature**

```ts
declare const clause: (binding: ModelBinding, where: Record<string, unknown>) => SQL | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L47)

### columnFor

Resolves one declared column.

**Throws**

TypeError for unknown fields.

**Signature**

```ts
declare const columnFor: (binding: ModelBinding, key: string) => Column;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L63)

### hasMethod

Inspects a native capability without invoking it.

**Signature**

```ts
declare const hasMethod: (target: unknown, name: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L91)

### integer

Checks bounded pagination without coercing strings.

**Throws**

TypeError for invalid pagination.

**Signature**

```ts
declare const integer: (value: unknown, name: string, fallback: number, maximum?: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L118)

### isRecord

Checks argument records without invoking getters.

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L146)

### record

Requires a plain argument record.

**Throws**

TypeError for null, arrays and scalar arguments.

**Signature**

```ts
declare const record: (value: unknown) => Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L104)

### recoverable

Finds a complete key for MySQL row recovery after writes.

**Signature**

```ts
declare const recoverable: (
  binding: ModelBinding,
  value: Record<string, unknown>,
) => Record<string, unknown> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L30)

### requiredRow

Requires a successful mutation row.

**Throws**

TypeError when no row was returned.

**Signature**

```ts
declare const requiredRow: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L136)

### selector

Requires a complete non-null unique selector.

**Throws**

TypeError for invalid keys or incomplete uniqueness.

**Signature**

```ts
declare const selector: (binding: ModelBinding, value: unknown) => Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/operations.utils.ts#L11)

## `owner.ts`

### DrizzleOwner (class)

Client lifetime/admission contract, substitutable through live/test Layers.

**See**

- `drizzleOwnerLayer` for checked acquisition/provisioning/cleanup composition.

**Signature**

```ts
declare class DrizzleOwner
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L20)

### drizzleInstrumentationOf

Reads the observation context captured at activation.

**Signature**

```ts
declare const drizzleInstrumentationOf: (activation: object) => Context.Context<never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L209)

### drizzleOwnerLayer

Acquires one client into a Layer scope.

**Example**

```ts
import { ManagedRuntime } from "effect";
import { sqliteTable, integer } from "drizzle-orm/sqlite-core";
import { defineDrizzleService } from "@relkit/drizzle";
import { DrizzleOwner, drizzleOwnerLayer, drizzleRuntimeOf } from "@relkit/drizzle/internal";
const records = sqliteTable("records", { id: integer().primaryKey() });
const declaration = drizzleRuntimeOf(
  defineDrizzleService({ schema: { records }, client: () => ({}) }),
);
const owner = ManagedRuntime.make(drizzleOwnerLayer(declaration, {}));
try {
  await owner.runPromise(DrizzleOwner);
} finally {
  await owner.dispose();
}
```

**Signature**

```ts
declare const drizzleOwnerLayer: (
  declaration: DrizzleServiceRuntime,
  env: Readonly<Record<string, unknown>>,
) => Layer.Layer<DrizzleOwner, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L45)

### makeDrizzleOwner

Creates the service contract for live acquisition or deterministic fake clients.

**See**

- `drizzleOwnerLayer` for the owning Layer and execution boundary.

**Signature**

```ts
declare const makeDrizzleOwner: (
  client: unknown,
) => Effect.Effect<DrizzleOwnerInterface, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L89)

### owners

Weak association preserving the exact frozen public activation shape.

**Signature**

```ts
declare const owners: WeakMap<object, OwnerBinding>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L25)

### runDrizzleWorkPromise

Executes one admitted Promise compatibility edge.

**See**

- `withDrizzleWork` for the equivalent Effect-native borrowed lease.

**Signature**

```ts
declare const runDrizzleWorkPromise: <A, E>(
  activation: object,
  effect: Effect.Effect<A, E>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L222)

### withDrizzleWork

Admits lazy work and releases its lease after safe native settlement.

**Example**

````ts
Compose work with an existing activation
```ts
import { Effect } from "effect";
import { activateDrizzleService } from "@relkit/drizzle";
import { withDrizzleWork } from "@relkit/drizzle/internal";
function borrowedWork(active: Awaited<ReturnType<typeof activateDrizzleService>>) {
  return withDrizzleWork(active, Effect.succeed(1));
}
````

````

**Signature**

```ts
declare const withDrizzleWork: <A, E, R>(activation: object, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DrizzleFailure, R>
````

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.ts#L138)

## `owner.types.ts`

### AdmissionState (interface)

Atomic owner admission state; close is monotonic.

**Signature**

```ts
export interface AdmissionState {
  readonly closing: boolean;
  readonly active: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.types.ts#L6)

### DrizzleOwnerInterface (interface)

Shared live/test contract for one client lifetime.

**Signature**

```ts
export interface DrizzleOwnerInterface {
  readonly client: unknown;
  readonly admission: Ref.Ref<AdmissionState>;
  readonly drained: Latch.Latch;

  /**
   * Admits lazy work while preserving its caller requirements and causes.
   * @typeParam A - Successful caller result.
   * @typeParam E - Caller typed failure.
   * @typeParam R - Required caller services.
   * @param effect - SDK adapter work retaining its lease until native settlement.
   * @returns Lazy caller work or a typed closed-owner admission failure.
   */
  readonly work: <A, E, R>(
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E | DrizzleFailure, R>;

  /**
   * Marks admission closed monotonically.
   * @returns Lazy state transition; already admitted work retains its lease.
   */
  readonly beginClose: () => Effect.Effect<void>;

  /**
   * Awaits all previously admitted native work.
   * @returns Lazy drain barrier; resource disposal must follow this completion.
   */
  readonly awaitDrained: () => Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.types.ts#L12)

### OwnerBinding (interface)

Private association; the public activation remains frozen.

**Signature**

```ts
export interface OwnerBinding {
  readonly dialect: "sqlite" | "pg" | "mysql";
  readonly service: DrizzleOwnerInterface;
  readonly runtime: ManagedRuntime.ManagedRuntime<DrizzleOwner, DrizzleFailure>;
  readonly instrumentation: Context.Context<never>;
  readonly run: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/owner.types.ts#L43)

## `pg.ts`

pg native model typing; imports only this selected dialect's upstream declarations.

### "./index.js" (namespace export)

Re-exports all named exports from the "./index.js" module.

**Signature**

```ts
export * from "./index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/pg.ts#L5)

### DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

**Signature**

```ts
type DialectDatabase = Omit<PgAsyncDatabase<any, any>, "query">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/pg.ts#L8)

### defineModel

Declares lazy native extensions with this dialect's real transaction client type.

**Signature**

```ts
declare const defineModel: DefineModel<DialectDatabase>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/pg.ts#L11)

## `queries.ts`

### checked

Converts expected synchronous argument/native-builder exceptions.

**Signature**

```ts
declare const checked: <A>(run: () => A) => Effect.Effect<A, DrizzleFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/queries.ts#L86)

### findMany

Selects a bounded ordered page.

**Signature**

```ts
declare const findMany: (
  binding: ModelBinding,
  args: Record<string, unknown>,
) => Effect.Effect<Array<unknown>, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/queries.ts#L39)

### findOne

Selects one unique row and validates persisted data.

**Signature**

```ts
declare const findOne: (
  binding: ModelBinding,
  where: Record<string, unknown>,
) => Effect.Effect<{} | null, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/queries.ts#L14)

### rows

Awaits native rows then validates sequentially without starting new SDK work.

**Signature**

```ts
declare const rows: (
  binding: ModelBinding,
  query: unknown,
) => Effect.Effect<Array<unknown>, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/queries.ts#L69)

## `runtime-types.ts`

### DRIZZLE_RUNTIME

Stable hidden descriptor brand; shared across module copies.

**Signature**

```ts
declare const DRIZZLE_RUNTIME: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L8)

### DrizzleServiceRuntime (interface)

Pure declaration dependencies; accessing this object never acquires a client.

**Signature**

```ts
export interface DrizzleServiceRuntime {
  readonly client: (context: { readonly env: Readonly<Record<string, unknown>> }) => unknown;
  readonly dispose?: (database: any) => unknown;
  readonly schema: Readonly<Record<string, unknown>>;
  readonly tables: TableMap;
  readonly models: DrizzleModelMap<TableMap>;
  readonly overrides: DrizzleOverrides<TableMap>;
  readonly metadata: Readonly<Record<string, TableMetadata>>;
  readonly zodSchemas: Readonly<Record<string, TableZodSchemas<Table>>>;
  readonly effectSchemas: Readonly<Record<string, ReturnType<typeof effectSchemasFor>>>;
  readonly dialect: "pg" | "mysql" | "sqlite";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L26)

### MODEL_RUNTIME

Stable hidden model descriptor brand.

**Signature**

```ts
declare const MODEL_RUNTIME: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L11)

### ModelBinding (interface)

Table operations bound to an owner or an already admitted transaction.

**Signature**

```ts
export interface ModelBinding {
  /**
   * Executes work at its owning runtime edge.
   * @typeParam A - Successful result.
   * @param effect - Lazy typed operation.
   * @param operation - Bounded diagnostic label.
   * @returns Public result or original native failure.
   */
  readonly run: <A>(effect: Effect.Effect<A, DrizzleFailure>, operation: string) => Promise<A>;
  readonly drizzle: unknown;
  readonly table: Table;
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly inTransaction: boolean;
  readonly metadata: TableMetadata;
  readonly override: Readonly<Record<string, unknown>>;
  readonly schemas: ReturnType<typeof effectSchemasFor>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L40)

### ModelRuntime (interface)

Opaque authored extensions retaining their native injected database contract.

**Signature**

```ts
export interface ModelRuntime {
  readonly table: Table;
  readonly extend: Readonly<Record<string, (context: any, ...args: any[]) => unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L20)

### TableMetadata (interface)

Pure table-column and complete unique-selector metadata.

**Signature**

```ts
export interface TableMetadata {
  readonly columns: Readonly<Record<string, unknown>>;
  readonly selectors: readonly (readonly string[])[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/runtime-types.ts#L14)

## `service.ts`

### defineDrizzleService

Defines the application's Drizzle service, table operations, and model customizations.
The client factory runs at activation, not during descriptor discovery.

**Throws**

TypeError for invalid declarations, dialects, models or overrides.

**Example**

```ts
import { defineDrizzleService } from "@relkit/drizzle";
import { integer, sqliteTable } from "drizzle-orm/sqlite-core";

const users = sqliteTable("users", { id: integer().primaryKey() });
const service = defineDrizzleService({
  schema: { users },
  client: () => {
    throw new Error("Configure a Drizzle driver before activation");
  },
});
console.assert(service.capability.dialect === "sqlite");
```

**Signature**

```ts
declare const defineDrizzleService: <
  Client,
  const Schema extends Readonly<Record<string, unknown>>,
  const Models extends DrizzleModelMap<TablesOf<Schema>> = {},
>(
  options: DefineDrizzleServiceOptions<Client, Schema, Models>,
) => DrizzleServiceDescriptor<string, Client, Schema, Models>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/service.ts#L39)

Since v0.1.0

### DefineDrizzleServiceOptions

**Signature**

```ts
declare const DefineDrizzleServiceOptions: DefineDrizzleServiceOptions<Client, Schema, Models>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/service.ts#L12)

### drizzleRuntimeOf

Resolves hidden runtime metadata without acquiring a client.

**Throws**

TypeError for unbranded declarations.

**Signature**

```ts
declare const drizzleRuntimeOf: (value: object) => DrizzleServiceRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/service.ts#L136)

## `service.types.ts`

### DefineDrizzleServiceOptions (interface)

Lazy authoring options preserving native client and model extension inference.

**Signature**

```ts
export interface DefineDrizzleServiceOptions<
  Client,
  Schema extends Readonly<Record<string, unknown>>,
  Models extends DrizzleModelMap<TablesOf<Schema>>,
> {
  readonly id?: string;
  readonly schema: Schema;
  /**
   * Acquires a native client when the owner Layer is first built.
   * @param context - First activation environment.
   * @returns Native client or acquisition Promise; failures retain native identity.
   */
  readonly client: (context: { readonly env: ApplicationEnv }) => Client | Promise<Client>;
  readonly models?: Models;
  readonly overrides?: DrizzleOverrides<TablesOf<Schema>>;
  /**
   * Releases the owned native client once admitted work has drained.
   * @param database - Successfully acquired client.
   * @returns Optional native completion; failure remains visible at close.
   */
  readonly dispose?: (database: Client) => unknown | Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/service.types.ts#L9)

## `sqlite.ts`

sqlite native model typing; imports only this selected dialect's upstream declarations.

### "./index.js" (namespace export)

Re-exports all named exports from the "./index.js" module.

**Signature**

```ts
export * from "./index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/sqlite.ts#L5)

### DialectDatabase (type alias)

Native database injected into model extensions for the selected dialect.

**Signature**

```ts
type DialectDatabase = Omit<SQLiteAsyncDatabase<any, any, any>, "query">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/sqlite.ts#L8)

### defineModel

Declares lazy native extensions with this dialect's real transaction client type.

**Signature**

```ts
declare const defineModel: DefineModel<DialectDatabase>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/sqlite.ts#L11)

## `table.schemas.ts`

### decodeTableValue

Validates unknown native rows or write data at the domain boundary.

**Signature**

```ts
declare const decodeTableValue: (
  schema: Schema.Codec<unknown, unknown>,
  value: unknown,
) => Effect.Effect<unknown, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/table.schemas.ts#L67)

### effectSchemasFor

Generates pinned Drizzle/Effect contracts without acquiring a database.

**Signature**

```ts
declare const effectSchemasFor: (table: Table) => Readonly<{
  select: BuildSchema<"select", Columns, { [x: string]: any }>;
  insert: BuildSchema<"insert", Columns, { [x: string]: any }>;
  update: BuildSchema<
    "update",
    Columns,
    { [k: string]: () => Schema.Codec<unknown, unknown, never, never> }
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/table.schemas.ts#L15)

## `trace-redaction.ts`

### redactSpecializedTrace

Protects configured tracers without changing authoritative workflow exits.

**Signature**

```ts
declare const redactSpecializedTrace: <A, E, R>(
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, Exclude<R, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/trace-redaction.ts#L13)

### specializedTracer

Adapts span completion before an external exporter can inspect native causes.

**Signature**

```ts
declare const specializedTracer: (tracer: Tracer.Tracer) => Tracer.Tracer;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/trace-redaction.ts#L24)

## `transaction.ts`

### transactionEffect

Executes a portable transaction under the physical SQLite client lock.

**Signature**

```ts
declare const transactionEffect: <A>(
  database: unknown,
  dialect: "sqlite" | "pg" | "mysql",
  run: (database: unknown, lease: NativeLease) => Promise<A>,
) => Effect.Effect<A, DrizzleFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/transaction.ts#L23)

### withSqlitePermit

Serializes conflicting SQLite work at the physical client boundary.

**Signature**

```ts
declare const withSqlitePermit: <A, E, R>(
  database: unknown,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E | DrizzleFailure, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/transaction.ts#L121)

### withTransactionWork

Retains a transaction callback while one child operation executes.

**Signature**

```ts
declare const withTransactionWork: <A, E, R>(
  lease: NativeLease,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, DrizzleFailure | E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/transaction.ts#L95)

## `types.ts`

Portable database contracts; native model database types belong to selected dialect entrypoints.

### ApplicationEnv (type alias)

Application declaration augmentation, falling back to string environment values.

**Signature**

```ts
type ApplicationEnv = keyof Relkit.ApplicationEnv extends never
  ? Readonly<Record<string, string>>
  : Readonly<Relkit.ApplicationEnv>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L116)

### BaseOperations

**Signature**

```ts
declare const BaseOperations: BaseOperations<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L41)

### DatabaseContext (type alias)

Public transaction-aware table operations and unchanged Zod schemas.

**Signature**

```ts
type DatabaseContext<Service extends DrizzleServiceDescriptor<any, any, any, any>> = {
  readonly [Name in keyof TablesOf<Service[typeof SERVICE_TYPES]["schema"]>]: BaseOperations<
    TablesOf<Service[typeof SERVICE_TYPES]["schema"]>[Name]
  > &
    (Name extends keyof Service[typeof SERVICE_TYPES]["models"]
      ? ConsumerExtensions<Service[typeof SERVICE_TYPES]["models"][Name]>
      : {});
} & {
  /**
   * Runs a callback in a portable transaction without nested portable transactions.
   * @typeParam Value - Callback result.
   * @param run - Callback receiving transaction-bound table operations.
   * @returns Callback result after native commit, or original failure after rollback.
   */
  readonly transaction: <Value>(
    run: (context: DatabaseContext<Service>) => MaybePromise<Value>,
  ) => Promise<Value>;
  readonly zodSchemas: {
    readonly [Name in keyof TablesOf<Service[typeof SERVICE_TYPES]["schema"]>]: TableZodSchemas<
      TablesOf<Service[typeof SERVICE_TYPES]["schema"]>[Name]
    >;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L168)

### DeleteArgs

**Signature**

```ts
declare const DeleteArgs: DeleteArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L40)

### DrizzleCapability (interface)

Pure compiler-visible dialect, tables, constraints and custom methods.

**Signature**

```ts
export interface DrizzleCapability {
  readonly kind: "drizzle";
  readonly dialect: "pg" | "mysql" | "sqlite";
  readonly tables: readonly {
    readonly name: string;
    readonly databaseName: string;
    readonly columns: readonly {
      readonly key: string;
      readonly name: string;
      readonly dataType: string;
      readonly notNull: boolean;
      readonly hasDefault: boolean;
      readonly primaryKey: boolean;
      readonly unique: boolean;
    }[];
    readonly selectors: readonly (readonly string[])[];
    readonly customMethods: readonly string[];
  }[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L121)

### DrizzleModelMap (type alias)

Optional table-keyed model declarations.

**Signature**

```ts
type DrizzleModelMap<Tables extends TableMap> = Partial<{
  readonly [Name in keyof Tables]: ModelDescriptor<Tables[Name], any>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L79)

### DrizzleOverrides (type alias)

Table-keyed override declarations.

**Signature**

```ts
type DrizzleOverrides<Tables extends TableMap> = {
  readonly [Name in keyof Tables]?: TableOverrides<Tables[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L71)

### DrizzleServiceDescriptor (type alias)

Frozen service descriptor retaining native client, schema and model inference.

**Signature**

```ts
type DrizzleServiceDescriptor<
  Id extends string,
  Client,
  Schema,
  Models extends DrizzleModelMap<TablesOf<Schema>>,
> = DescriptorBase<"service", Id> & {
  readonly capability: DrizzleCapability;
  readonly [SERVICE_TYPES]: {
    readonly client: Client;
    readonly schema: Schema;
    readonly models: Models;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L150)

### FindManyArgs

**Signature**

```ts
declare const FindManyArgs: FindManyArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L36)

### FindOneArgs

**Signature**

```ts
declare const FindOneArgs: FindOneArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L35)

### Insert

**Signature**

```ts
declare const Insert: {
  [
    K in keyof ({
      [
        Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
      ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    } & {
      [
        Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<
          Key,
          T["_"]["columns"][Key],
          false
        >
      ]?:
        | (T["_"]["columns"][Key]["_"]["notNull"] extends true
            ? T["_"]["columns"][Key]["_"]["data"]
            : T["_"]["columns"][Key]["_"]["data"] | null)
        | undefined;
    })
  ]: ({
    [
      Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
    ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  } & {
    [
      Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<Key, T["_"]["columns"][Key], false>
    ]?:
      | (T["_"]["columns"][Key]["_"]["notNull"] extends true
          ? T["_"]["columns"][Key]["_"]["data"]
          : T["_"]["columns"][Key]["_"]["data"] | null)
      | undefined;
  })[K];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L32)

### InsertArgs

**Signature**

```ts
declare const InsertArgs: InsertArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L37)

### ModelDescriptor

**Signature**

```ts
declare const ModelDescriptor: ModelDescriptor<T, Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L8)

### ModelDescriptorAny

**Signature**

```ts
declare const ModelDescriptorAny: ModelDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L9)

### ModelExtension

**Signature**

```ts
declare const ModelExtension: ModelExtension<T, Database>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L10)

### ModelExtensionContext

**Signature**

```ts
declare const ModelExtensionContext: ModelExtensionContext<T, Database>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L11)

### ModelExtensionMap

**Signature**

```ts
declare const ModelExtensionMap: Readonly<Record<string, ModelExtension<T, Database>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L12)

### NonEmptyExtensions

**Signature**

```ts
declare const NonEmptyExtensions: NonEmptyExtensions<Extensions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L13)

### OperationOverride (type alias)

Native override receiving a Promise base operation.

**Signature**

```ts
type OperationOverride<Args, Result> = (options: {
  readonly args: Args;
  readonly base: (args: Args) => Promise<Result>;
}) => MaybePromise<Result>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L51)

### Row

**Signature**

```ts
declare const Row: {
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L31)

### TableMap (type alias)

Supported tables keyed by authored schema names.

**Signature**

```ts
type TableMap = Readonly<Record<string, Table>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L17)

### TableOverrides (type alias)

Optional replacements for the six reserved table operations.

**Signature**

```ts
type TableOverrides<T extends Table> = {
  readonly [Name in keyof BaseOperations<T>]?: OperationOverride<
    Parameters<BaseOperations<T>[Name]>[0],
    Awaited<ReturnType<BaseOperations<T>[Name]>>
  >;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L60)

### TableZodSchemas (interface)

Unchanged public select, insert and update Zod contracts.

**Signature**

```ts
export interface TableZodSchemas<T extends Table> {
  readonly select: ZodType<Row<T>>;
  readonly insert: ZodType<Insert<T>>;
  readonly update: ZodType<Update<T>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L103)

### TablesOf (type alias)

Table-only projection of an authored Drizzle schema.

**Signature**

```ts
type TablesOf<Schema> = {
  readonly [Name in keyof Schema as Schema[Name] extends Table ? Name : never]: Extract<
    Schema[Name],
    Table
  >;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L23)

### Update

**Signature**

```ts
declare const Update: Partial<{
  [
    K in keyof ({
      [
        Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
      ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    } & {
      [
        Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<
          Key,
          T["_"]["columns"][Key],
          false
        >
      ]?:
        | (T["_"]["columns"][Key]["_"]["notNull"] extends true
            ? T["_"]["columns"][Key]["_"]["data"]
            : T["_"]["columns"][Key]["_"]["data"] | null)
        | undefined;
    })
  ]: ({
    [
      Key in keyof T["_"]["columns"] & string as RequiredKeyOnly<Key, T["_"]["columns"][Key]>
    ]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  } & {
    [
      Key in keyof T["_"]["columns"] & string as OptionalKeyOnly<Key, T["_"]["columns"][Key], false>
    ]?:
      | (T["_"]["columns"][Key]["_"]["notNull"] extends true
          ? T["_"]["columns"][Key]["_"]["data"]
          : T["_"]["columns"][Key]["_"]["data"] | null)
      | undefined;
  })[K];
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L33)

### UpdateArgs

**Signature**

```ts
declare const UpdateArgs: UpdateArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L38)

### UpsertArgs

**Signature**

```ts
declare const UpsertArgs: UpsertArgs<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L39)

### Where

**Signature**

```ts
declare const Where: Partial<{
  [
    K in keyof {
      [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
        ? T["_"]["columns"][Key]["_"]["data"]
        : T["_"]["columns"][Key]["_"]["data"] | null;
    }
  ]: {
    [Key in keyof T["_"]["columns"] & string]: T["_"]["columns"][Key]["_"]["notNull"] extends true
      ? T["_"]["columns"][Key]["_"]["data"]
      : T["_"]["columns"][Key]["_"]["data"] | null;
  }[K];
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/drizzle/src/types.ts#L34)

---

# Events API
Source: https://relkit.dev/docs/api/events

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineEvent](/docs/api/events#defineevent)
- [defineEventFunction](/docs/api/events#defineeventfunction)

For configuration and examples, read [events](/docs/modules/events), [domains](/docs/modules/service/domains), [organization](/docs/modules/service/organization).

For a complete workflow, follow [react to order events](/guides/events/react-to-order-events).

## Public imports

- `@relkit/events` — 44 exports
- `@relkit/events/effect` — 39 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                     | Kind  | Import from             | Example                                                                |
| --------------------------------------------------------------------------------------- | ----- | ----------------------- | ---------------------------------------------------------------------- |
| [assertEventDescriptor](/docs/api/events#asserteventdescriptor)                         | Value | `@relkit/events`        | [API example](/docs/api/events#asserteventdescriptor)                  |
| [assertEventDescriptorEffect](/docs/api/events#asserteventdescriptoreffect)             | Value | `@relkit/events/effect` | [API example](/docs/api/events#asserteventdescriptoreffect)            |
| [assertOptionalTextEffect](/docs/api/events#assertoptionaltexteffect-1)                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#assertoptionaltexteffect-1)             |
| [assertVersionEffect](/docs/api/events#assertversioneffect-1)                           | Value | `@relkit/events/effect` | [API example](/docs/api/events#assertversioneffect-1)                  |
| [bindFunctionEvents](/docs/api/events#bindfunctionevents)                               | Value | `@relkit/events`        | [API example](/docs/api/events#bindfunctionevents)                     |
| [bindFunctionEventsEffect](/docs/api/events#bindfunctioneventseffect-1)                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#bindfunctioneventseffect-1)             |
| [createEventClient](/docs/api/events#createeventclient)                                 | Value | `@relkit/events`        | [API example](/docs/api/events#createeventclient)                      |
| [createEventClientEffect](/docs/api/events#createeventclienteffect)                     | Value | `@relkit/events/effect` | [API example](/docs/api/events#createeventclienteffect)                |
| [defineEvent](/docs/api/events#defineevent)                                             | Value | `@relkit/events`        | [API example](/docs/api/events#defineevent)                            |
| [defineEventEffect](/docs/api/events#defineeventeffect)                                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#defineeventeffect)                      |
| [defineEventFunction](/docs/api/events#defineeventfunction)                             | Value | `@relkit/events`        | [API example](/docs/api/events#defineeventfunction)                    |
| [defineEventFunctionEffect](/docs/api/events#defineeventfunctioneffect)                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#defineeventfunctioneffect)              |
| [DefineEventFunctionOptions](/docs/api/events#defineeventfunctionoptions-interface)     | Type  | `@relkit/events`        | [API example](/docs/api/events#defineeventfunctionoptions-interface)   |
| [DefineEventOptions](/docs/api/events#defineeventoptions-interface)                     | Type  | `@relkit/events`        | [API example](/docs/api/events#defineeventoptions-interface)           |
| [EventAttributeValue](/docs/api/functions#eventattributevalue-type-alias)               | Type  | `@relkit/events`        | [API example](/docs/api/functions#eventattributevalue-type-alias)      |
| [EventBindingError](/docs/api/events#eventbindingerror-class)                           | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventbindingerror-class)                |
| [EventClient](/docs/api/events#eventclient-interface)                                   | Type  | `@relkit/events`        | [API example](/docs/api/events#eventclient-interface)                  |
| [EventClientOptions](/docs/api/events#eventclientoptions-interface)                     | Type  | `@relkit/events`        | [API example](/docs/api/events#eventclientoptions-interface)           |
| [EventDeclaredEdge](/docs/api/events#eventdeclarededge-interface)                       | Type  | `@relkit/events`        | [API example](/docs/api/events#eventdeclarededge-interface)            |
| [EventDefinitionError](/docs/api/events#eventdefinitionerror-class)                     | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventdefinitionerror-class)             |
| [EventDelivery](/docs/api/events#eventdelivery-type-alias)                              | Type  | `@relkit/events`        | [API example](/docs/api/events#eventdelivery-type-alias)               |
| [eventDeliveryEffect](/docs/api/events#eventdeliveryeffect-1)                           | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventdeliveryeffect-1)                  |
| [EventDependencyError](/docs/api/events#eventdependencyerror-class)                     | Value | `@relkit/events`        | [API example](/docs/api/events#eventdependencyerror-class)             |
| [EventDescriptor](/docs/api/events#eventdescriptor-interface)                           | Type  | `@relkit/events`        | [API example](/docs/api/events#eventdescriptor-interface)              |
| [EventDescriptorAny](/docs/api/events#eventdescriptorany-type-alias)                    | Type  | `@relkit/events`        | [API example](/docs/api/events#eventdescriptorany-type-alias)          |
| [EventDescriptorByName](/docs/api/events#eventdescriptorbyname-type-alias)              | Type  | `@relkit/events`        | [API example](/docs/api/events#eventdescriptorbyname-type-alias)       |
| [EventEnvelope](/docs/api/events#eventenvelope-type-alias)                              | Type  | `@relkit/events`        | [API example](/docs/api/events#eventenvelope-type-alias)               |
| [EventEnvelopeFor](/docs/api/events#eventenvelopefor-type-alias)                        | Type  | `@relkit/events`        | [API example](/docs/api/events#eventenvelopefor-type-alias)            |
| [EventFunctionContext](/docs/api/events#eventfunctioncontext-interface)                 | Type  | `@relkit/events`        | [API example](/docs/api/events#eventfunctioncontext-interface)         |
| [EventFunctionDescriptor](/docs/api/events#eventfunctiondescriptor-interface)           | Type  | `@relkit/events`        | [API example](/docs/api/events#eventfunctiondescriptor-interface)      |
| [EventFunctionDescriptorAny](/docs/api/events#eventfunctiondescriptorany-interface)     | Type  | `@relkit/events`        | [API example](/docs/api/events#eventfunctiondescriptorany-interface)   |
| [EventFunctionHandler](/docs/api/events#eventfunctionhandler-type-alias)                | Type  | `@relkit/events`        | [API example](/docs/api/events#eventfunctionhandler-type-alias)        |
| [EventFunctionTrigger](/docs/api/events#eventfunctiontrigger-interface)                 | Type  | `@relkit/events`        | [API example](/docs/api/events#eventfunctiontrigger-interface)         |
| [EventIdentity](/docs/api/events#eventidentity-class)                                   | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventidentity-class)                    |
| [EventIdentityLive](/docs/api/events#eventidentitylive)                                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventidentitylive)                      |
| [EventIdentityService](/docs/api/events#eventidentityservice-interface)                 | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventidentityservice-interface)         |
| [EventInputByName](/docs/api/events#eventinputbyname-type-alias)                        | Type  | `@relkit/events`        | [API example](/docs/api/events#eventinputbyname-type-alias)            |
| [EventInvocationBridge](/docs/api/events#eventinvocationbridge-interface)               | Type  | `@relkit/events`        | [API example](/docs/api/events#eventinvocationbridge-interface)        |
| [EventInvocationBridgeOptions](/docs/api/events#eventinvocationbridgeoptions-interface) | Type  | `@relkit/events`        | [API example](/docs/api/events#eventinvocationbridgeoptions-interface) |
| [EventName](/docs/api/events#eventname-type-alias)                                      | Type  | `@relkit/events`        | [API example](/docs/api/events#eventname-type-alias)                   |
| [EventObservedEdge](/docs/api/events#eventobservededge-interface)                       | Type  | `@relkit/events`        | [API example](/docs/api/events#eventobservededge-interface)            |
| [EventOperation](/docs/api/events#eventoperation-type-alias)                            | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventoperation-type-alias)              |
| [EventOperationCancelledError](/docs/api/events#eventoperationcancellederror-class)     | Value | `@relkit/events`        | [API example](/docs/api/events#eventoperationcancellederror-class)     |
| [EventOperationContext](/docs/api/events#eventoperationcontext-interface)               | Type  | `@relkit/events`        | [API example](/docs/api/events#eventoperationcontext-interface)        |
| [EventOperationTimeoutError](/docs/api/events#eventoperationtimeouterror-class)         | Value | `@relkit/events`        | [API example](/docs/api/events#eventoperationtimeouterror-class)       |
| [EventPayloadValidationError](/docs/api/events#eventpayloadvalidationerror-class)       | Value | `@relkit/events`        | [API example](/docs/api/events#eventpayloadvalidationerror-class)      |
| [EventPayloadValidationFailure](/docs/api/events#eventpayloadvalidationfailure-class)   | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventpayloadvalidationfailure-class)    |
| [eventProfileEffect](/docs/api/events#eventprofileeffect-1)                             | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventprofileeffect-1)                   |
| [EventProfileError](/docs/api/events#eventprofileerror-class)                           | Value | `@relkit/events`        | [API example](/docs/api/events#eventprofileerror-class)                |
| [EventProvider](/docs/api/events#eventprovider-interface)                               | Type  | `@relkit/events`        | [API example](/docs/api/events#eventprovider-interface)                |
| [EventProviderError](/docs/api/events#eventprovidererror-class)                         | Value | `@relkit/events`        | [API example](/docs/api/events#eventprovidererror-class)               |
| [EventProviderResult](/docs/api/events#eventproviderresult-type-alias)                  | Type  | `@relkit/events`        | [API example](/docs/api/events#eventproviderresult-type-alias)         |
| [EventPublisher](/docs/api/events#eventpublisher-class)                                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventpublisher-class)                   |
| [eventPublisherLayer](/docs/api/events#eventpublisherlayer)                             | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventpublisherlayer)                    |
| [EventPublisherService](/docs/api/events#eventpublisherservice-interface)               | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventpublisherservice-interface)        |
| [EventPublishFailure](/docs/api/events#eventpublishfailure-type-alias)                  | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventpublishfailure-type-alias)         |
| [EventPublishOptions](/docs/api/functions#eventpublishoptions-interface)                | Type  | `@relkit/events`        | [API example](/docs/api/functions#eventpublishoptions-interface)       |
| [EventPublishResult](/docs/api/functions#eventpublishresult-interface)                  | Type  | `@relkit/events`        | [API example](/docs/api/functions#eventpublishresult-interface)        |
| [EventPublishSetup](/docs/api/events#eventpublishsetup-interface)                       | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventpublishsetup-interface)            |
| [EventRegistry](/docs/api/events#eventregistry-type-alias)                              | Type  | `@relkit/events`        | [API example](/docs/api/events#eventregistry-type-alias)               |
| [eventRetryEffect](/docs/api/events#eventretryeffect-1)                                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventretryeffect-1)                     |
| [EventRetryPolicy](/docs/api/events#eventretrypolicy-type-alias)                        | Type  | `@relkit/events`        | [API example](/docs/api/events#eventretrypolicy-type-alias)            |
| [EventTelemetry](/docs/api/events#eventtelemetry-class)                                 | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventtelemetry-class)                   |
| [EventTelemetryLive](/docs/api/events#eventtelemetrylive-1)                             | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventtelemetrylive-1)                   |
| [EventTelemetryService](/docs/api/events#eventtelemetryservice-interface)               | Type  | `@relkit/events/effect` | [API example](/docs/api/events#eventtelemetryservice-interface)        |
| [EventVersionByName](/docs/api/events#eventversionbyname-type-alias)                    | Type  | `@relkit/events`        | [API example](/docs/api/events#eventversionbyname-type-alias)          |
| [EventWorkFailed](/docs/api/events#eventworkfailed-class)                               | Value | `@relkit/events/effect` | [API example](/docs/api/events#eventworkfailed-class)                  |
| [isEventDescriptor](/docs/api/events#iseventdescriptor)                                 | Value | `@relkit/events`        | [API example](/docs/api/events#iseventdescriptor)                      |
| [isEventDescriptorEffect](/docs/api/events#iseventdescriptoreffect)                     | Value | `@relkit/events/effect` | [API example](/docs/api/events#iseventdescriptoreffect)                |
| [isEventFunctionDescriptor](/docs/api/events#iseventfunctiondescriptor)                 | Value | `@relkit/events`        | [API example](/docs/api/events#iseventfunctiondescriptor)              |
| [isEventFunctionDescriptorEffect](/docs/api/events#iseventfunctiondescriptoreffect)     | Value | `@relkit/events/effect` | [API example](/docs/api/events#iseventfunctiondescriptoreffect)        |
| [normalizeAttributesEffect](/docs/api/events#normalizeattributeseffect-1)               | Value | `@relkit/events/effect` | [API example](/docs/api/events#normalizeattributeseffect-1)            |
| [normalizeOptionsEffect](/docs/api/events#normalizeoptionseffect-1)                     | Value | `@relkit/events/effect` | [API example](/docs/api/events#normalizeoptionseffect-1)               |
| [normalizeResultEffect](/docs/api/events#normalizeresulteffect)                         | Value | `@relkit/events/effect` | [API example](/docs/api/events#normalizeresulteffect)                  |
| [notifyEffect](/docs/api/events#notifyeffect)                                           | Value | `@relkit/events/effect` | [API example](/docs/api/events#notifyeffect)                           |
| [observeEvent](/docs/api/events#observeevent-1)                                         | Value | `@relkit/events/effect` | [API example](/docs/api/events#observeevent-1)                         |
| [parsePayloadEffect](/docs/api/events#parsepayloadeffect-1)                             | Value | `@relkit/events/effect` | [API example](/docs/api/events#parsepayloadeffect-1)                   |
| [publishEventEffect](/docs/api/events#publisheventeffect)                               | Value | `@relkit/events/effect` | [API example](/docs/api/events#publisheventeffect)                     |
| [rejectEventFunctionFieldsEffect](/docs/api/events#rejecteventfunctionfieldseffect-1)   | Value | `@relkit/events/effect` | [API example](/docs/api/events#rejecteventfunctionfieldseffect-1)      |
| [resolveProviderEffect](/docs/api/events#resolveprovidereffect)                         | Value | `@relkit/events/effect` | [API example](/docs/api/events#resolveprovidereffect)                  |
| [resolveValueEffect](/docs/api/events#resolvevalueeffect)                               | Value | `@relkit/events/effect` | [API example](/docs/api/events#resolvevalueeffect)                     |
| [runAbortableEffect](/docs/api/events#runabortableeffect)                               | Value | `@relkit/events/effect` | [API example](/docs/api/events#runabortableeffect)                     |
| [UnknownEventEnvelope](/docs/api/events#unknowneventenvelope-type-alias)                | Type  | `@relkit/events`        | [API example](/docs/api/events#unknowneventenvelope-type-alias)        |

## `client-errors.ts`

### EventClientValidationError (class)

Other expected client validation failure.

**Example**

```ts
new EventClientValidationError({ message: "Invalid event options" });
```

**Signature**

```ts
declare class EventClientValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L98)

### EventDependencyError (class)

Publication attempted without a declared event dependency.

**Example**

```ts
new EventDependencyError("orders.created");
```

**Signature**

```ts
declare class EventDependencyError {
  constructor(eventId: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L31)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L35)

### EventOperationCancelledError (class)

Publication cancelled through its AbortSignal.

**Example**

```ts
new EventOperationCancelledError();
```

**Signature**

```ts
declare class EventOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L70)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L74)

### EventOperationTimeoutError (class)

Publication exceeded its absolute deadline.

**Example**

```ts
new EventOperationTimeoutError();
```

**Signature**

```ts
declare class EventOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L84)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L88)

### EventPayloadValidationError (class)

Payload rejected by its Standard Schema validator.

**Example**

```ts
new EventPayloadValidationError([{ message: "Required" }]);
```

**Signature**

```ts
declare class EventPayloadValidationError { constructor(readonly issues: readonly StandardIssue[]) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L7)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_PAYLOAD_VALIDATION"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L8)

### EventPayloadValidationFailure (class)

Tagged payload failure used by Effect clients before Promise adaptation.

**Example**

```ts
new EventPayloadValidationFailure([{ message: "Required" }]);
```

**Signature**

```ts
declare class EventPayloadValidationFailure {
  constructor(issues: readonly StandardIssue[]);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L18)

### issues (property)

**Signature**

```ts
readonly issues: ReadonlyArray<StandardIssue>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L22)

### EventProfileError (class)

Requested provider profile is missing.

**Example**

```ts
new EventProfileError("default");
```

**Signature**

```ts
declare class EventProfileError {
  constructor(profile: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L44)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_PROFILE_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L48)

### EventProviderError (class)

Selected provider cannot publish events.

**Example**

```ts
new EventProviderError();
```

**Signature**

```ts
declare class EventProviderError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L57)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-errors.ts#L61)

## `client-operation.ts`

### EventWorkFailed (class)

Typed failure returned by the work callback.

**Example**

```ts
new EventWorkFailed({ cause: new Error("Provider failed") });
```

**Signature**

```ts
declare class EventWorkFailed
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-operation.ts#L14)

### runAbortable

Promise compatibility adapter for abortable event work.

**Throws**

The established cancellation, timeout, or provider error.

**Example**

```ts
await runAbortable(new AbortController().signal, undefined, async () => 1);
```

**Signature**

```ts
declare const runAbortable: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: () => Promise<A>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-operation.ts#L116)

### runAbortableEffect

Runs callback work with an owned abort listener and deadline timer.

**Example**

```ts
Effect.runPromise(runAbortableEffect(new AbortController().signal, undefined, async () => 1));
```

**Signature**

```ts
declare const runAbortableEffect: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (effectSignal: AbortSignal) => Promise<A>,
) => Effect.Effect<
  A,
  | EventClientValidationError
  | EventDependencyError
  | EventOperationCancelledError
  | EventOperationTimeoutError
  | EventPayloadValidationFailure
  | EventWorkFailed,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-operation.ts#L25)

## `client-provider.ts`

### notify

Invokes an edge hook without allowing telemetry failure to replace publication.

**Example**

```ts
notify(onObservedEdge, edge);
```

**Signature**

```ts
declare const notify: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L67)

### notifyEffect

Effect implementation of best-effort edge notification.

**Example**

```ts
Effect.runSync(notifyEffect(onObservedEdge, edge));
```

**Signature**

```ts
declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L78)

### resolveProvider

Synchronous provider resolution adapter.

**Throws**

EventProfileError, EventProviderError, or a resolver error.

**Example**

```ts
resolveProvider(provider, "default", undefined);
```

**Signature**

```ts
declare const resolveProvider: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => EventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L46)

### resolveProviderEffect

Resolves a provider for a named profile.

**Example**

```ts
Effect.runSync(resolveProviderEffect(provider, "default", undefined));
```

**Signature**

```ts
declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect.Effect<
  EventProvider,
  EventClientValidationError | EventProfileError | EventProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L18)

### resolveValue

Resolves a fixed or lazy correlation ID.

**Example**

```ts
resolveValue(() => "correlation-1");
```

**Signature**

```ts
declare const resolveValue: (value: EventClientOptions["correlationId"]) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L98)

### resolveValueEffect

Effect implementation of lazy correlation ID resolution.

**Example**

```ts
Effect.runSync(resolveValueEffect(() => "correlation-1"));
```

**Signature**

```ts
declare const resolveValueEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect.Effect<string | undefined, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-provider.ts#L113)

## `client-publish.ts`

### EventPublisher (class)

Substitutable provider boundary for Effect event publication.

**Example**

```ts
Effect.provide(publishEventEffect(setup, payload), eventPublisherLayer(provider));
```

**Signature**

```ts
declare class EventPublisher
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.ts#L32)

### eventPublisherLayer

Adapts a Promise provider into a typed Effect service layer.

**Example**

```ts
eventPublisherLayer(provider);
```

**Signature**

```ts
declare const eventPublisherLayer: (provider: EventProvider) => Layer.Layer<EventPublisher>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.ts#L41)

### publishEventEffect

Publishes one event through a supplied provider service.

**Example**

```ts
Effect.runPromise(
  publishEventEffect(setup, payload).pipe(Effect.provide(eventPublisherLayer(provider))),
);
```

**Signature**

```ts
declare const publishEventEffect: <
  Id extends string,
  Version extends number,
  PayloadSchema extends StandardSchemaV1,
>(
  setup: EventPublishSetup<Id, Version, PayloadSchema>,
  payload: InferInput<PayloadSchema>,
  request?: EventPublishOptions,
) => Effect.Effect<
  EventPublishResult<Id, Version, InferOutput<PayloadSchema>>,
  EventPublishFailure,
  EventPublisher
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.ts#L62)

## `client-publish.types.ts`

### EventProvider

**Signature**

```ts
declare const EventProvider: EventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L5)

### EventPublishFailure (type alias)

Typed failures of an Effect event publication.

**Example**

```ts
Effect.catchTag(publishEventEffect(setup, payload), "EventPayloadValidationFailure", handle);
```

**Signature**

```ts
type EventPublishFailure =
  | EventClientValidationError
  | EventDependencyError
  | EventOperationCancelledError
  | EventOperationTimeoutError
  | EventPayloadValidationFailure
  | EventWorkFailed;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L24)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L3)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L3)

### EventPublishSetup (interface)

Validated state captured by a generated event client.

**Example**

```ts
const setup: EventPublishSetup<"orders.created", 1, typeof schema> = validated;
```

**Signature**

```ts
export interface EventPublishSetup<
  Id extends string,
  Version extends number,
  PayloadSchema extends StandardSchemaV1,
> {
  readonly options: EventClientOptions<Id, Version, PayloadSchema>;
  readonly ownerId: string;
  readonly eventId: Id;
  readonly version: Version;
  readonly profile: string;
  readonly declared: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L53)

### EventPublisherService (interface)

Provider operation supplied to an Effect publication.

**Example**

```ts
const publisher: EventPublisherService = { publish: () => Effect.succeed(reply) };
```

**Signature**

```ts
export interface EventPublisherService {
  /** Publishes a validated payload.
   * @param payload - Decoded payload.
   * @param options - Validated request options.
   * @param context - Cancellation and trace context.
   * @returns Provider metadata or EventWorkFailed.
   * @example yield* publisher.publish(payload, {}, context)
   */
  readonly publish: (
    payload: unknown,
    options: EventPublishOptions,
    context: EventOperationContext,
  ) => Effect.Effect<EventProviderResult, EventWorkFailed>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L35)

### InferInput

**Signature**

```ts
declare const InferInput: InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L4)

### InferOutput

**Signature**

```ts
declare const InferOutput: InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L4)

### StandardSchemaV1

**Signature**

```ts
declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-publish.types.ts#L4)

## `client-record.ts`

### isRecord

Checks a value for a plain record shape.

**Example**

```ts
isRecord({ key: "value" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-record.ts#L9)

### isRecordEffect

Effect implementation of the client record predicate.

**Example**

```ts
Effect.runSync(isRecordEffect({ key: "value" }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-record.ts#L18)

## `client-result.ts`

### EventIdentity (class)

Substitutable time and identifier boundary for event envelopes.

**Example**

```ts
Effect.provide(
  normalizeResultEffect(reply, payload, {}, context, undefined, "orders.created", 1),
  EventIdentityLive,
);
```

**Signature**

```ts
declare class EventIdentity
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.ts#L17)

### EventIdentityLive

Default wall clock and random UUID source.

**Example**

```ts
Effect.provide(
  normalizeResultEffect(reply, payload, {}, context, undefined, "orders.created", 1),
  EventIdentityLive,
);
```

**Signature**

```ts
declare const EventIdentityLive: Layer.Layer<EventIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.ts#L28)

### normalizeResult

Synchronous compatibility adapter for provider result normalization.

**Throws**

TypeError when provider metadata cannot be normalized.

**Example**

```ts
normalizeResult(reply, input, {}, context, undefined, "orders.created", 1);
```

**Signature**

```ts
declare const normalizeResult: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.ts#L105)

### normalizeResultEffect

Builds the accepted event envelope from provider metadata.

**Example**

```ts
Effect.runSync(normalizeResultEffect(reply, input, {}, context, undefined, "orders.created", 1));
```

**Signature**

```ts
declare const normalizeResultEffect: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => Effect.Effect<EventPublishResult<Id, Version, Payload>, EventClientValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.ts#L41)

## `client-result.types.ts`

Substitutable clock and identifier source for event envelopes.

**Example**

```ts
const identity: EventIdentityService = { now: () => new Date(0), nextId: () => "event-1" };
```

### EventIdentityService (interface)

Substitutable clock and identifier source for event envelopes.

**Example**

```ts
const identity: EventIdentityService = { now: () => new Date(0), nextId: () => "event-1" };
```

**Signature**

```ts
export interface EventIdentityService {
  /** Reads the current wall-clock time.
   * @returns The current date.
   * @example identity.now()
   */
  readonly now: () => Date;
  /** Generates a unique event instance ID.
   * @returns An opaque instance ID.
   * @example identity.nextId()
   */
  readonly nextId: () => string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.types.ts#L4)

### EventOperationContext

**Signature**

```ts
declare const EventOperationContext: EventOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.types.ts#L17)

### EventProviderResult

**Signature**

```ts
declare const EventProviderResult: EventProviderResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.types.ts#L17)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.types.ts#L16)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-result.types.ts#L16)

## `client-utils.ts`

### EventClientValidationError

**Signature**

```ts
declare const EventClientValidationError: typeof EventClientValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L2)

### EventDependencyError

**Signature**

```ts
declare const EventDependencyError: typeof EventDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L3)

### EventOperationCancelledError

**Signature**

```ts
declare const EventOperationCancelledError: typeof EventOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L4)

### EventOperationTimeoutError

**Signature**

```ts
declare const EventOperationTimeoutError: typeof EventOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L5)

### EventPayloadValidationError

**Signature**

```ts
declare const EventPayloadValidationError: typeof EventPayloadValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L6)

### EventProfileError

**Signature**

```ts
declare const EventProfileError: typeof EventProfileError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L7)

### EventProviderError

**Signature**

```ts
declare const EventProviderError: typeof EventProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L8)

### assertOptionalText

**Signature**

```ts
declare const assertOptionalText: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L11)

### assertOptionalTextEffect

**Signature**

```ts
declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect<void, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L12)

### assertVersion

**Signature**

```ts
declare const assertVersion: (value: unknown) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L13)

### assertVersionEffect

**Signature**

```ts
declare const assertVersionEffect: (
  value: unknown,
) => Effect<number, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L14)

### normalizeAttributesEffect

**Signature**

```ts
declare const normalizeAttributesEffect: (
  value: unknown,
) => Effect<Readonly<Record<string, EventAttributeValue>>, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L15)

### normalizeOptions

**Signature**

```ts
declare const normalizeOptions: (value: unknown) => EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L16)

### normalizeOptionsEffect

**Signature**

```ts
declare const normalizeOptionsEffect: (
  value: unknown,
) => Effect<EventPublishOptions, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L17)

### normalizeResult

**Signature**

```ts
declare const normalizeResult: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L21)

### normalizeResultEffect

**Signature**

```ts
declare const normalizeResultEffect: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => Effect<EventPublishResult<Id, Version, Payload>, EventClientValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L21)

### notify

**Signature**

```ts
declare const notify: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L23)

### notifyEffect

**Signature**

```ts
declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L24)

### parsePayload

**Signature**

```ts
declare const parsePayload: (
  schema: StandardSchemaV1 | undefined,
  payload: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L18)

### parsePayloadEffect

**Signature**

```ts
declare const parsePayloadEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  payload: unknown,
) => Effect<unknown, EventClientValidationError | EventPayloadValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L19)

### resolveProvider

**Signature**

```ts
declare const resolveProvider: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => EventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L25)

### resolveProviderEffect

**Signature**

```ts
declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect<
  EventProvider,
  EventClientValidationError | EventProfileError | EventProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L26)

### resolveValue

**Signature**

```ts
declare const resolveValue: (value: EventClientOptions["correlationId"]) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L27)

### resolveValueEffect

**Signature**

```ts
declare const resolveValueEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect<string | undefined, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-utils.ts#L28)

## `client-validation.ts`

### assertOptionalText

Synchronous optional text assertion.

**Throws**

TypeError for empty or non-text input.

**Example**

```ts
assertOptionalText("key", "key");
```

**Signature**

```ts
declare const assertOptionalText: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L143)

### assertOptionalTextEffect

Requires optional text to be non-empty when present.

**Example**

```ts
Effect.runSync(assertOptionalTextEffect("key", "key"));
```

**Signature**

```ts
declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L128)

### assertVersion

Synchronous positive version assertion.

**Throws**

TypeError for an invalid version.

**Example**

```ts
assertVersion(1);
```

**Signature**

```ts
declare const assertVersion: (value: unknown) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L174)

### assertVersionEffect

Requires a positive safe event version.

**Example**

```ts
Effect.runSync(assertVersionEffect(1));
```

**Signature**

```ts
declare const assertVersionEffect: (
  value: unknown,
) => Effect.Effect<number, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L157)

### normalizeAttributesEffect

Normalizes and sorts bounded event attributes.

**Example**

```ts
Effect.runSync(normalizeAttributesEffect({ source: "checkout" }));
```

**Signature**

```ts
declare const normalizeAttributesEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<Record<string, EventAttributeValue>>,
  EventClientValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L99)

### normalizeOptions

Synchronous adapter for request option normalization.

**Throws**

TypeError for malformed options.

**Example**

```ts
normalizeOptions({ key: "order-1" });
```

**Signature**

```ts
declare const normalizeOptions: (value: unknown) => EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L77)

### normalizeOptionsEffect

Validates and freezes publisher request options.

**Example**

```ts
Effect.runSync(normalizeOptionsEffect({ key: "order-1" }));
```

**Signature**

```ts
declare const normalizeOptionsEffect: (
  value: unknown,
) => Effect.Effect<EventPublishOptions, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L64)

### parsePayload

Promise adapter for payload validation.

**Throws**

EventPayloadValidationError or EventClientValidationError.

**Example**

```ts
await parsePayload(schema, payload);
```

**Signature**

```ts
declare const parsePayload: (
  schema: StandardSchemaV1 | undefined,
  payload: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L46)

### parsePayloadEffect

Validates a publication payload with its Standard Schema contract.

**Example**

```ts
await Effect.runPromise(parsePayloadEffect(schema, payload));
```

**Signature**

```ts
declare const parsePayloadEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  payload: unknown,
) => Effect.Effect<unknown, EventClientValidationError | EventPayloadValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client-validation.ts#L18)

## `client.ts`

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L38)

### EventClient

**Signature**

```ts
declare const EventClient: EventClient<Input, Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L27)

### EventClientOptions

**Signature**

```ts
declare const EventClientOptions: EventClientOptions<Id, Version, PayloadSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L28)

### EventDeclaredEdge

**Signature**

```ts
declare const EventDeclaredEdge: EventDeclaredEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L29)

### EventDependencyError

**Signature**

```ts
declare const EventDependencyError: typeof EventDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L43)

### EventInvocationBridge

**Signature**

```ts
declare const EventInvocationBridge: EventInvocationBridge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L30)

### EventInvocationBridgeOptions

**Signature**

```ts
declare const EventInvocationBridgeOptions: EventInvocationBridgeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L31)

### EventObservedEdge

**Signature**

```ts
declare const EventObservedEdge: EventObservedEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L32)

### EventOperationCancelledError

**Signature**

```ts
declare const EventOperationCancelledError: typeof EventOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L44)

### EventOperationContext

**Signature**

```ts
declare const EventOperationContext: EventOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L33)

### EventOperationTimeoutError

**Signature**

```ts
declare const EventOperationTimeoutError: typeof EventOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L45)

### EventPayloadValidationError

**Signature**

```ts
declare const EventPayloadValidationError: typeof EventPayloadValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L46)

### EventProfileError

**Signature**

```ts
declare const EventProfileError: typeof EventProfileError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L47)

### EventProvider

**Signature**

```ts
declare const EventProvider: EventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L34)

### EventProviderError

**Signature**

```ts
declare const EventProviderError: typeof EventProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L48)

### EventProviderResult

**Signature**

```ts
declare const EventProviderResult: EventProviderResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L35)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L39)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L40)

### createEventClient

Creates a Promise publisher from a validated event contract.

**Throws**

TypeError for malformed client configuration, or a provider profile error.

**Example**

```ts
createEventClient({
  ownerId: "orders.create",
  eventId: "orders.created",
  version: 1,
  source: provider,
});
```

**Signature**

```ts
declare const createEventClient: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L57)

### createEventClientEffect

Creates an Effect-backed event publisher with typed configuration failures.

**Example**

```ts
Effect.runSync(
  createEventClientEffect({
    ownerId: "orders.create",
    eventId: "orders.created",
    version: 1,
    source: provider,
  }),
);
```

**Signature**

```ts
declare const createEventClientEffect: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => Effect.Effect<
  EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>,
  EventClientValidationError | EventProfileError | EventProviderError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.ts#L79)

## `client.types.ts`

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L5)

### EventClient (interface)

Promise compatibility interface exposed to application handlers.

**Example**

```ts
await client.publish({ orderId: "one" });
```

**Signature**

```ts
export interface EventClient<
  Input = unknown,
  Id extends string = string,
  Version extends number = number,
  Payload = Input,
> {
  /** Publishes a payload and returns the accepted envelope.
   * @param payload - Event payload to decode.
   * @param options - Optional key and attributes.
   * @returns A Promise of the accepted envelope or a rejected domain error.
   * @example await client.publish(payload, { key: "order-1" })
   */
  readonly publish: (
    payload: Input,
    options?: EventPublishOptions,
  ) => Promise<EventPublishResult<Id, Version, Payload>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L109)

### EventClientOptions (interface)

Dependencies and policy for a generated event publisher.
Provider selection occurs once when the client is created.

**Example**

```ts
const options: EventClientOptions = {
  ownerId: "orders.create",
  eventId: "orders.created",
  version: 1,
  source: provider,
};
```

**Signature**

```ts
export interface EventClientOptions<
  Id extends string = string,
  Version extends number = number,
  PayloadSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly ownerId: string;
  readonly eventId: Id;
  readonly version: Version;
  readonly source: unknown;
  readonly payloadSchema?: PayloadSchema;
  readonly profile?: string;
  readonly resolveProfile?: (profile: string) => unknown;
  readonly bridge?: EventInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly correlationId?: string | (() => string | undefined);
  readonly now?: () => Date;
  readonly declared?: boolean;
  readonly onDeclaredEdge?: (edge: EventDeclaredEdge) => void;
  readonly onObservedEdge?: (edge: EventObservedEdge) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L84)

### EventDeclaredEdge (interface)

Static graph edge for a declared publication dependency.

**Example**

```ts
const edge: EventDeclaredEdge = {
  kind: "publishes-event",
  from: "orders.create",
  to: "orders.created",
};
```

**Signature**

```ts
export interface EventDeclaredEdge {
  readonly kind: "publishes-event";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L130)

### EventInvocationBridge (interface)

Optional invocation bridge that owns a publication span.

**Example**

```ts
await bridge.run(() => provider.publish(payload, {}, context));
```

**Signature**

```ts
export interface EventInvocationBridge {
  /** Runs publication within the invocation context.
   * @param operation - Publication callback.
   * @param options - Producer span metadata.
   * @returns The operation result or rejection.
   * @example await bridge.run(() => Promise.resolve(1))
   */
  readonly run: <A>(
    operation: () => MaybePromise<A>,
    options?: EventInvocationBridgeOptions,
  ) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L67)

### EventInvocationBridgeOptions (interface)

Trace bridge metadata for a producer operation.

**Example**

```ts
const name = options.name;
```

**Signature**

```ts
export interface EventInvocationBridgeOptions {
  readonly name?: string;
  readonly attributes?: Readonly<Record<string, unknown>>;
  readonly signal?: AbortSignal;
  readonly kind?: "producer";
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L56)

### EventObservedEdge (interface)

Runtime graph edge for an attempted publication.

**Example**

```ts
const edge: EventObservedEdge = {
  relationship: "publishes-event",
  from: "orders.create",
  to: "orders.created",
};
```

**Signature**

```ts
export interface EventObservedEdge {
  readonly relationship: "publishes-event";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L139)

### EventOperationContext (interface)

Context passed to the selected event provider for one publication.
The signal remains valid until the publication settles.

**Example**

```ts
const id = context.eventId;
```

**Signature**

```ts
export interface EventOperationContext {
  readonly operation: "publish";
  readonly eventId: string;
  readonly version: number;
  readonly signal: AbortSignal;
  readonly profile: string;
  readonly deadlineMs?: number;
  readonly propagation?: TracePropagation;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L15)

### EventProvider (interface)

Provider interface selected from a profile for publication.

**Example**

```ts
const provider: EventProvider = {
  publish: async () => ({ accepted: true, instanceId: "event-1" }),
};
```

**Signature**

```ts
export interface EventProvider {
  /** Publishes one validated payload.
   * @param payload - Decoded event payload.
   * @param options - Validated publish options.
   * @param context - Trace and cancellation context.
   * @returns Provider acceptance and metadata, or a rejected Promise.
   * @example await provider.publish(payload, {}, context)
   */
  readonly publish: (
    payload: unknown,
    options: EventPublishOptions,
    context: EventOperationContext,
  ) => MaybePromise<EventProviderResult>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L38)

### EventProviderResult (type alias)

Provider acknowledgement and optional envelope metadata.

**Example**

```ts
const result: EventProviderResult = { accepted: true, instanceId: "event-1" };
```

**Signature**

```ts
type EventProviderResult<
  Id extends string = string,
  Version extends number = number,
  Payload = unknown,
> = Pick<EventPublishResult<Id, Version, Payload>, "instanceId" | "accepted"> &
  Partial<Omit<EventPublishResult<Id, Version, Payload>, "instanceId" | "accepted">>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L28)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L6)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L7)

### InferInput

**Signature**

```ts
declare const InferInput: InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L9)

### InferOutput

**Signature**

```ts
declare const InferOutput: InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L9)

### StandardSchemaV1

**Signature**

```ts
declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/client.types.ts#L9)

## `define-event-function.ts`

### defineEventFunction

Defines an independent event-only consumer with inferred input and void success.
Event IDs are supplied by the application's generated EventRegistry.

**Throws**

TypeError for malformed options.

**Example**

```ts
import { defineEvent, defineEventFunction } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const orderCreated = defineEvent({
  id: "orders.created",
  input: z.object({ orderId: z.string() }),
});

// The application normally generates this declaration with `relkit check`.
declare global {
  namespace Relkit {
    interface EventRegistry {
      "orders.created": typeof orderCreated;
    }
  }
}

const receipt = defineEventFunction({
  id: "receipt.send",
  event: "orders.created",
  handler: async () => {},
});
```

**Signature**

```ts
declare const defineEventFunction: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.ts#L59)

Since v0.1.0

### defineEventFunctionEffect

Defines an event-only function in Effect.

**Example**

```ts
Effect.runSync(
  defineEventFunctionEffect({ id: "notify", event: "orders.created", handler: () => {} }),
);
```

**Signature**

```ts
declare const defineEventFunctionEffect: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => Effect.Effect<
  EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>,
  EventDefinitionError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.ts#L84)

### isEventFunctionDescriptor

Checks an event-only function descriptor at a synchronous boundary.

**Example**

```ts
isEventFunctionDescriptor(candidate);
```

**Signature**

```ts
declare const isEventFunctionDescriptor: (value: unknown) => value is EventFunctionDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.ts#L145)

### isEventFunctionDescriptorEffect

Checks an unknown value for a valid event-only function descriptor.

**Example**

```ts
Effect.runSync(isEventFunctionDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isEventFunctionDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.ts#L154)

## `define-event-function.types.ts`

### ErrorDescriptorAny

**Signature**

```ts
declare const ErrorDescriptorAny: ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L8)

### ErrorListOf (type alias)

Error declarations inferred from a function definition.

**Example**

```ts
type Errors = ErrorListOf<typeof options>;
```

**Signature**

```ts
type ErrorListOf<Options> = Options extends {
  readonly errors: infer Errors extends readonly ErrorDescriptorAny[];
}
  ? Errors
  : readonly [];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L18)

### EventFunctionCallOptions (type alias)

Handler-aware options for an event function definition.

**Example**

```ts
type Options = EventFunctionCallOptions<"receipt.send", "orders.created", [], {}>;
```

**Signature**

```ts
type EventFunctionCallOptions<
  Id extends string,
  Event extends EventName,
  Publishes extends readonly EventName[],
  Dependencies extends FunctionDependencies,
> = Omit<
  DefineEventFunctionOptions<Id, Event, Publishes, Dependencies, readonly ErrorDescriptorAny[]>,
  "handler"
> & {
  readonly handler: (
    input: EventInputByName<Event>,
    context: EventFunctionContext<Event, Publishes, Dependencies>,
  ) => unknown;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L27)

### EventFunctionDescriptor

**Signature**

```ts
declare const EventFunctionDescriptor: EventFunctionDescriptor<
  Id,
  Event,
  Publishes,
  Dependencies,
  Errors
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L11)

### EventFunctionDescriptorAny

**Signature**

```ts
declare const EventFunctionDescriptorAny: EventFunctionDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L12)

### EventFunctionValidation (type alias)

Validates a handler's result against declared errors and void success.

**Example**

```ts
type Validation = EventFunctionValidation<typeof options>;
```

**Signature**

```ts
type EventFunctionValidation<Options extends { readonly handler: (...args: never[]) => unknown }> =
  FunctionHandlerValidation<Awaited<ReturnType<Options["handler"]>>, void, ErrorListOf<Options>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L45)

### EventName

**Signature**

```ts
declare const EventName: never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L9)

### FunctionDependencies

**Signature**

```ts
declare const FunctionDependencies: FunctionDependencies;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event-function.types.ts#L8)

## `define-event.ts`

### defineEvent

Defines a versioned event contract used by publishers and event functions.

**Throws**

TypeError when the contract is malformed.

**Example**

```ts
import { defineEvent } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const created = defineEvent({ id: "orders.created", input: z.object({ orderId: z.string() }) });
void created;
```

**Signature**

```ts
declare const defineEvent: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L46)

Since v0.1.0

### DefineEventOptions

**Signature**

```ts
declare const DefineEventOptions: DefineEventOptions<Id, Version, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L21)

### EventDescriptor

**Signature**

```ts
declare const EventDescriptor: EventDescriptor<Id, Version, Input, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L22)

### EventDescriptorAny

**Signature**

```ts
declare const EventDescriptorAny: EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L23)

### EventEnvelope

**Signature**

```ts
declare const EventEnvelope: EventEnvelope<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L24)

### EventEnvelopeFor

**Signature**

```ts
declare const EventEnvelopeFor: EventEnvelopeFor<E>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L25)

### UnknownEventEnvelope

**Signature**

```ts
declare const UnknownEventEnvelope: UnknownEventEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L26)

### assertEventDescriptor

Requires a valid event descriptor at a synchronous boundary.

**Throws**

TypeError when the candidate is invalid.

**Example**

```ts
assertEventDescriptor(value);
```

**Signature**

```ts
declare const assertEventDescriptor: (value: unknown) => asserts value is EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L164)

### assertEventDescriptorEffect

Requires a valid event descriptor in an Effect workflow.

**Example**

```ts
Effect.runSync(assertEventDescriptorEffect(candidate));
```

**Signature**

```ts
declare const assertEventDescriptorEffect: (
  value: unknown,
) => Effect.Effect<EventDescriptorAny, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L178)

### defineEventEffect

Defines an event contract in Effect with typed validation failure.

**Example**

```ts
Effect.runSync(defineEventEffect({ id: "orders.created", input: z.object({}) }));
```

**Signature**

```ts
declare const defineEventEffect: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => Effect.Effect<
  EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>,
  EventDefinitionError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L66)

### isEventDescriptor

Checks a candidate against the event descriptor contract.

**Example**

```ts
isEventDescriptor(value);
```

**Signature**

```ts
declare const isEventDescriptor: (value: unknown) => value is EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L122)

### isEventDescriptorEffect

Checks whether an unknown value is a valid event descriptor.

**Example**

```ts
Effect.runSync(isEventDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isEventDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.ts#L131)

## `define-event.types.ts`

### DefineEventOptions (interface)

Input accepted by the event descriptor factory.

**Example**

```ts
const options: DefineEventOptions<"orders.created", 1, typeof schema> = {
  id: "orders.created",
  input: schema,
};
```

**Signature**

```ts
export interface DefineEventOptions<
  Id extends string,
  Version extends number,
  InputSchema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly version?: Version;
  readonly input: InputSchema;
  readonly profile?: string;
  readonly sensitiveFields?: readonly string[];
  readonly handler?: never;
  readonly output?: never;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L55)

### EventDescriptor (interface)

Immutable, versioned event contract with no handler or output.

**Example**

```ts
const created: EventDescriptor<"orders.created", 1, { orderId: string }> = defineEvent(options);
```

**Signature**

```ts
export interface EventDescriptor<
  Id extends string,
  Version extends number,
  Input,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
>
  extends DescriptorBase<"event", Id>, EventRef<Id, InputSchema> {
  readonly version: Version;
  readonly input: InputSchema;
  readonly profile?: string;
  readonly sensitiveFields?: readonly string[];
  readonly handler?: never;
  readonly output?: never;
  readonly __input?: Input;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L31)

### EventDescriptorAny (type alias)

Event descriptor with erased contract parameters.

**Example**

```ts
const registry: EventDescriptorAny[] = [created];
```

**Signature**

```ts
type EventDescriptorAny = EventDescriptor<string, number, unknown, StandardSchemaV1>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L50)

### EventEnvelope (type alias)

Published event data without the provider acceptance flag.

**Example**

```ts
type Created = EventEnvelope<"orders.created", 1, { orderId: string }>;
```

**Signature**

```ts
type EventEnvelope<
  Id extends string = string,
  Version extends number = number,
  Payload = unknown,
> = Omit<EventPublishResult<Id, Version, Payload>, "accepted">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L9)

### EventEnvelopeFor (type alias)

Resolves the envelope for a specific event descriptor.

**Example**

```ts
type CreatedEnvelope = EventEnvelopeFor<typeof created>;
```

**Signature**

```ts
type EventEnvelopeFor<E> =
  E extends EventDescriptor<infer Id, infer Version, infer Input, StandardSchemaV1>
    ? EventEnvelope<Id, Version, Input>
    : UnknownEventEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L23)

### InferOutput

**Signature**

```ts
declare const InferOutput: InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L4)

### StandardSchemaV1

**Signature**

```ts
declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L4)

### UnknownEventEnvelope (type alias)

Event data when its contract is not known statically.

**Example**

```ts
const envelope: UnknownEventEnvelope = received;
```

**Signature**

```ts
type UnknownEventEnvelope = EventEnvelope<string, number, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/define-event.types.ts#L18)

## `effect.ts`

### EventBindingError

**Signature**

```ts
declare const EventBindingError: typeof EventBindingError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L37)

### EventDefinitionError

**Signature**

```ts
declare const EventDefinitionError: typeof EventDefinitionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L37)

### EventIdentity

**Signature**

```ts
declare const EventIdentity: typeof EventIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L26)

### EventIdentityLive

**Signature**

```ts
declare const EventIdentityLive: Layer<EventIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L26)

### EventIdentityService

**Signature**

```ts
declare const EventIdentityService: EventIdentityService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L27)

### EventOperation

**Signature**

```ts
declare const EventOperation: EventOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L30)

### EventPayloadValidationFailure

**Signature**

```ts
declare const EventPayloadValidationFailure: typeof EventPayloadValidationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L38)

### EventPublishFailure

**Signature**

```ts
declare const EventPublishFailure: EventPublishFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L14)

### EventPublishSetup

**Signature**

```ts
declare const EventPublishSetup: EventPublishSetup<Id, Version, PayloadSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L15)

### EventPublisher

**Signature**

```ts
declare const EventPublisher: typeof EventPublisher;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L12)

### EventPublisherService

**Signature**

```ts
declare const EventPublisherService: EventPublisherService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L16)

### EventTelemetry

**Signature**

```ts
declare const EventTelemetry: typeof EventTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L29)

### EventTelemetryLive

**Signature**

```ts
declare const EventTelemetryLive: Layer<EventTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L29)

### EventTelemetryService

**Signature**

```ts
declare const EventTelemetryService: EventTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L30)

### EventWorkFailed

**Signature**

```ts
declare const EventWorkFailed: typeof EventWorkFailed;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L18)

### assertEventDescriptorEffect

**Signature**

```ts
declare const assertEventDescriptorEffect: (
  value: unknown,
) => Effect<EventDescriptorAny, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L4)

### assertOptionalTextEffect

**Signature**

```ts
declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect<void, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L23)

### assertVersionEffect

**Signature**

```ts
declare const assertVersionEffect: (
  value: unknown,
) => Effect<number, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L24)

### bindFunctionEventsEffect

**Signature**

```ts
declare const bindFunctionEventsEffect: <T extends FunctionWithEvents>(
  descriptor: T,
  consumed: EventDescriptorAny | undefined,
  published: readonly EventDescriptorAny[],
) => Effect<T, EventBindingError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L10)

### createEventClientEffect

**Signature**

```ts
declare const createEventClientEffect: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => Effect<
  EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>,
  EventClientValidationError | EventProfileError | EventProviderError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L11)

### defineEventEffect

**Signature**

```ts
declare const defineEventEffect: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => Effect<
  EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>,
  EventDefinitionError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L2)

### defineEventFunctionEffect

**Signature**

```ts
declare const defineEventFunctionEffect: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => Effect<
  EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>,
  EventDefinitionError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L7)

### eventDeliveryEffect

**Signature**

```ts
declare const eventDeliveryEffect: (
  value: unknown,
) => Effect<EventDelivery, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L32)

### eventProfileEffect

**Signature**

```ts
declare const eventProfileEffect: (value: unknown) => Effect<string, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L33)

### eventPublisherLayer

**Signature**

```ts
declare const eventPublisherLayer: (provider: EventProvider) => Layer<EventPublisher>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L12)

### eventRetryEffect

**Signature**

```ts
declare const eventRetryEffect: (
  value: unknown,
) => Effect<RetryPolicy, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L34)

### isEventDescriptorEffect

**Signature**

```ts
declare const isEventDescriptorEffect: (value: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L3)

### isEventFunctionDescriptorEffect

**Signature**

```ts
declare const isEventFunctionDescriptorEffect: (value: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L8)

### normalizeAttributesEffect

**Signature**

```ts
declare const normalizeAttributesEffect: (
  value: unknown,
) => Effect<Readonly<Record<string, EventAttributeValue>>, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L21)

### normalizeOptionsEffect

**Signature**

```ts
declare const normalizeOptionsEffect: (
  value: unknown,
) => Effect<EventPublishOptions, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L20)

### normalizeResultEffect

**Signature**

```ts
declare const normalizeResultEffect: <Id extends string, Version extends number, Payload>(
  value: EventProviderResult | undefined,
  payload: Payload,
  options: EventPublishOptions,
  context: EventOperationContext,
  now: (() => Date) | undefined,
  eventId: Id,
  version: Version,
) => Effect<EventPublishResult<Id, Version, Payload>, EventClientValidationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L26)

### notifyEffect

**Signature**

```ts
declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L28)

### observeEvent

**Signature**

```ts
declare const observeEvent: <A, E, R>(
  operation: EventOperation,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L29)

### parsePayloadEffect

**Signature**

```ts
declare const parsePayloadEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  payload: unknown,
) => Effect<unknown, EventClientValidationError | EventPayloadValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L22)

### publishEventEffect

**Signature**

```ts
declare const publishEventEffect: <
  Id extends string,
  Version extends number,
  PayloadSchema extends StandardSchemaV1,
>(
  setup: EventPublishSetup<Id, Version, PayloadSchema>,
  payload: InferInput<PayloadSchema>,
  request?: EventPublishOptions,
) => Effect<
  EventPublishResult<Id, Version, InferOutput<PayloadSchema>>,
  EventPublishFailure,
  EventPublisher
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L12)

### rejectEventFunctionFieldsEffect

**Signature**

```ts
declare const rejectEventFunctionFieldsEffect: (
  options: Record<PropertyKey, unknown>,
) => Effect<void, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L35)

### resolveProviderEffect

**Signature**

```ts
declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect<
  EventProvider,
  EventClientValidationError | EventProfileError | EventProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L28)

### resolveValueEffect

**Signature**

```ts
declare const resolveValueEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect<string | undefined, EventClientValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L28)

### runAbortableEffect

**Signature**

```ts
declare const runAbortableEffect: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (effectSignal: AbortSignal) => Promise<A>,
) => Effect<
  A,
  | EventClientValidationError
  | EventDependencyError
  | EventOperationCancelledError
  | EventOperationTimeoutError
  | EventPayloadValidationFailure
  | EventWorkFailed,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/effect.ts#L18)

## `event-contract-shape.ts`

### hasOwn

Checks whether a descriptor owns a named property.

**Example**

```ts
hasOwn({ id: "orders.created" }, "id");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L51)

### hasOwnEffect

Effect implementation of direct property ownership detection.

**Example**

```ts
Effect.runSync(hasOwnEffect({ id: "orders.created" }, "id"));
```

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L61)

### isPositiveInteger

Checks for a positive safe version number.

**Example**

```ts
isPositiveInteger(1);
```

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L70)

### isPositiveIntegerEffect

Effect implementation of the positive safe integer predicate.

**Example**

```ts
Effect.runSync(isPositiveIntegerEffect(1));
```

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L79)

### isRecord

Checks whether a value is a non-array object.

**Example**

```ts
isRecord({ id: "orders.created" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L32)

### isRecordEffect

Effect implementation of the descriptor record predicate.

**Example**

```ts
Effect.runSync(isRecordEffect({ id: "orders.created" }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L41)

### isSchema

Checks the Standard Schema v1 runtime contract.

**Example**

```ts
isSchema(schema);
```

**Signature**

```ts
declare const isSchema: (value: unknown) => value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L11)

### isSchemaEffect

Effect implementation of the Standard Schema predicate.

**Example**

```ts
Effect.runSync(isSchemaEffect(schema));
```

**Signature**

```ts
declare const isSchemaEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L20)

### validateVersion

Requires a positive safe version number.

**Throws**

TypeError for an invalid version.

**Example**

```ts
validateVersion(1);
```

**Signature**

```ts
declare const validateVersion: (value: unknown) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L89)

### validateVersionEffect

Requires a positive safe version in the Effect error channel.

**Example**

```ts
Effect.runSync(validateVersionEffect(1));
```

**Signature**

```ts
declare const validateVersionEffect: (
  value: unknown,
) => Effect.Effect<number, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-contract-shape.ts#L103)

## `event-errors.ts`

### EventBindingError (class)

A rejected function-to-event binding with a stable typed tag.

**Example**

```ts
new EventBindingError({ message: "Missing event contract" });
```

**Signature**

```ts
declare class EventBindingError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-errors.ts#L14)

### EventDefinitionError (class)

A rejected event or event-function descriptor with a stable typed tag.

**Example**

```ts
new EventDefinitionError({ message: "Invalid event descriptor" });
```

**Signature**

```ts
declare class EventDefinitionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-errors.ts#L6)

## `event-function-target.ts`

### bindFunctionEvents

Binds validated event contracts into a generated function target.

**Throws**

TypeError if any declared contract is missing or invalid.

**Example**

```ts
bindFunctionEvents(publisher, undefined, [orderCreated]);
```

**Signature**

```ts
declare const bindFunctionEvents: <T extends FunctionWithEvents>(
  descriptor: T,
  consumed: EventDescriptorAny | undefined,
  published: readonly EventDescriptorAny[],
) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-target.ts#L22)

### bindFunctionEventsEffect

Binds event contracts with typed failures in an Effect workflow.

**Example**

```ts
Effect.runSync(bindFunctionEventsEffect(publisher, undefined, [orderCreated]));
```

**Signature**

```ts
declare const bindFunctionEventsEffect: <T extends FunctionWithEvents>(
  descriptor: T,
  consumed: EventDescriptorAny | undefined,
  published: readonly EventDescriptorAny[],
) => Effect.Effect<T, EventBindingError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-target.ts#L42)

## `event-function-target.types.ts`

Minimal function descriptor accepted by event contract binding.

**Example**

```ts
const target: FunctionWithEvents = { id: "orders.create", publishes: ["orders.created"] };
```

### EventDescriptorAny

**Signature**

```ts
declare const EventDescriptorAny: EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-target.types.ts#L11)

### FunctionWithEvents (interface)

Minimal function descriptor accepted by event contract binding.

**Example**

```ts
const target: FunctionWithEvents = { id: "orders.create", publishes: ["orders.created"] };
```

**Signature**

```ts
export interface FunctionWithEvents {
  readonly id: string;
  readonly invocationMode?: "callable" | "event-only";
  readonly event?: string;
  readonly publishes?: readonly string[];
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-target.types.ts#L4)

## `event-function-validation.ts`

### eventDelivery

Normalizes event delivery for synchronous authoring.

**Throws**

TypeError for an unsupported mode.

**Example**

```ts
eventDelivery("durable");
```

**Signature**

```ts
declare const eventDelivery: (value: unknown) => EventDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L22)

### eventDeliveryEffect

Resolves an event function delivery mode.

**Example**

```ts
Effect.runSync(eventDeliveryEffect("durable"));
```

**Signature**

```ts
declare const eventDeliveryEffect: (
  value: unknown,
) => Effect.Effect<EventDelivery, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L31)

### eventProfile

Normalizes a synchronous event provider profile.

**Throws**

TypeError for a malformed profile.

**Example**

```ts
eventProfile("default");
```

**Signature**

```ts
declare const eventProfile: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L52)

### eventProfileEffect

Resolves the configured event provider profile.

**Example**

```ts
Effect.runSync(eventProfileEffect("default"));
```

**Signature**

```ts
declare const eventProfileEffect: (
  value: unknown,
) => Effect.Effect<string, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L61)

### eventRetry

Normalizes synchronous event retry policy input.

**Throws**

TypeError for invalid retry values.

**Example**

```ts
eventRetry({ maxAttempts: 3 });
```

**Signature**

```ts
declare const eventRetry: (value: unknown) => RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L80)

### eventRetryEffect

Normalizes an event function retry policy.

**Example**

```ts
Effect.runSync(eventRetryEffect({ maxAttempts: 3 }));
```

**Signature**

```ts
declare const eventRetryEffect: (
  value: unknown,
) => Effect.Effect<RetryPolicy, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L89)

### rejectEventFunctionFields

Rejects descriptor fields reserved for other function kinds.

**Throws**

TypeError when a forbidden field is present.

**Example**

```ts
rejectEventFunctionFields({ event: "orders.created" });
```

**Signature**

```ts
declare const rejectEventFunctionFields: (options: Record<PropertyKey, unknown>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L121)

### rejectEventFunctionFieldsEffect

Rejects fields owned by other descriptor kinds.

**Example**

```ts
Effect.runSync(rejectEventFunctionFieldsEffect({ event: "orders.created" }));
```

**Signature**

```ts
declare const rejectEventFunctionFieldsEffect: (
  options: Record<PropertyKey, unknown>,
) => Effect.Effect<void, EventDefinitionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function-validation.ts#L130)

## `event-function.types.ts`

### DefineEventFunctionOptions (interface)

Definition options for a versioned event consumer.

**Example**

```ts
const options = { id: "receipt.send", event: "orders.created", handler: () => {} };
```

**Signature**

```ts
export interface DefineEventFunctionOptions<
  Id extends string,
  Event extends EventName,
  Publishes extends readonly EventName[] = readonly [],
  Dependencies extends FunctionDependencies = {},
  Errors extends readonly ErrorDescriptorAny[] = readonly [],
> extends DescriptorMetadata {
  readonly id: Id;
  readonly event: Event;
  readonly delivery?: EventDelivery;
  readonly profile?: string;
  readonly retry?: Partial<EventRetryPolicy>;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
  readonly publishes?: Publishes;
  readonly dependencies?: Dependencies;
  readonly errors?: Errors;
  readonly onBefore?: (
    input: EventInputByName<Event>,
    context: EventFunctionContext<Event, Publishes, Dependencies>,
  ) => MaybePromise<EventInputByName<Event>>;
  readonly onAfter?: (
    output: void,
    context: EventFunctionContext<Event, Publishes, Dependencies>,
  ) => MaybePromise<void>;
  readonly handler: EventFunctionHandler<Event, Publishes, Dependencies, Errors>;
  readonly input?: never;
  readonly output?: never;
  readonly tool?: never;
  readonly trigger?: never;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L76)

### EventDelivery (type alias)

Delivery semantics for an event-only function.

**Example**

```ts
const delivery: EventDelivery = "durable";
```

**Signature**

```ts
type EventDelivery = "ephemeral" | "durable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L20)

### EventFunctionContext (interface)

Handler context with event trigger and declared dependencies.

**Example**

```ts
const eventId = context.trigger.event.id;
```

**Signature**

```ts
export interface EventFunctionContext<
  Event extends EventName,
  Publishes extends readonly EventName[] = readonly [],
  Dependencies extends FunctionDependencies = {},
> extends FunctionContext<Dependencies, Publishes> {
  readonly trigger: EventFunctionTrigger<Event>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L52)

### EventFunctionDescriptor (interface)

Immutable descriptor emitted by defineEventFunction.

**Example**

```ts
const descriptor = defineEventFunction(options);
```

**Signature**

```ts
export interface EventFunctionDescriptor<
  Id extends string = string,
  Event extends EventName = EventName,
  Publishes extends readonly EventName[] = readonly [],
  Dependencies extends FunctionDependencies = {},
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
> extends DescriptorBase<"function", Id> {
  readonly invocationMode: "event-only";
  readonly event: Event;
  readonly delivery: EventDelivery;
  readonly profile: string;
  readonly retry: EventRetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
  readonly publishes?: Publishes;
  readonly dependencies?: Dependencies;
  readonly errors?: Errors;
  readonly handler: EventFunctionHandler<Event, Publishes, Dependencies, Errors>;
  readonly invoke?: never;
  readonly asTool?: never;
  readonly __input?: InferOutput<EventDescriptorByName<Event>["input"]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L111)

### EventFunctionDescriptorAny (interface)

Event-only descriptor with erased event and dependency types.

**Example**

```ts
const consumer: EventFunctionDescriptorAny = descriptor;
```

**Signature**

```ts
export interface EventFunctionDescriptorAny extends DescriptorBase<"function"> {
  readonly invocationMode: "event-only";
  readonly event: string;
  readonly delivery: EventDelivery;
  readonly profile: string;
  readonly retry: EventRetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
  readonly publishes?: readonly string[];
  readonly handler: (...args: never[]) => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L137)

### EventFunctionHandler (type alias)

Handler contract for event-only functions; successful handlers return void.

**Example**

```ts
const handler: EventFunctionHandler<"orders.created", [], {}, []> = () => {};
```

**Signature**

```ts
type EventFunctionHandler<
  Event extends EventName,
  Publishes extends readonly EventName[],
  Dependencies extends FunctionDependencies,
  Errors extends readonly ErrorDescriptorAny[],
> = (
  input: EventInputByName<Event>,
  context: EventFunctionContext<Event, Publishes, Dependencies>,
) => MaybePromise<FunctionHandlerResult<void, Errors>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L63)

### EventFunctionTrigger (interface)

Trigger metadata supplied for one event delivery.

**Example**

```ts
const attempt = context.trigger.delivery.attempt;
```

**Signature**

```ts
export interface EventFunctionTrigger<Event extends EventName = EventName> {
  readonly kind: "event";
  readonly event: {
    readonly id: Event;
    readonly version: EventVersionByName<Event>;
    readonly instanceId: string;
    readonly occurredAt: string;
    readonly publishedAt: string;
    readonly key?: string;
    readonly attributes: Readonly<Record<string, string | number | boolean>>;
  };
  readonly delivery: { readonly attempt: number; readonly replayed: boolean };
  readonly trace: {
    readonly traceId: string;
    readonly correlationId?: string;
    readonly causationInvocationId?: string;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L30)

### EventRetryPolicy (type alias)

Bounded retry policy shared with job handlers.

**Example**

```ts
const retry: EventRetryPolicy = {
  maxAttempts: 1,
  initialDelayMs: 0,
  maxDelayMs: 0,
  multiplier: 1,
  jitter: "none",
};
```

**Signature**

```ts
type EventRetryPolicy = RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-function.types.ts#L25)

## `event-observability.ts`

### EventTelemetry (class)

Substitutable telemetry for package operations.

**Example**

```ts
Effect.provide(observeEvent("event.define", Effect.void), EventTelemetryLive);
```

**Signature**

```ts
declare class EventTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.ts#L7)

### EventTelemetryLive

Default span and metric observer.

**Example**

```ts
Effect.provide(observeEvent("event.define", Effect.void), EventTelemetryLive);
```

**Signature**

```ts
declare const EventTelemetryLive: Layer.Layer<EventTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.ts#L14)

### observeEvent

Records a stable span, call count, failure count, and duration.

**Example**

```ts
observeEvent("event.define", Effect.succeed("created"));
```

**Signature**

```ts
declare const observeEvent: <A, E, R>(
  operation: EventOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.ts#L28)

### runEventSync

Runs a dependency-free compatibility effect and rethrows its typed failure.

**Throws**

The typed failure or an unexpected defect.

**Example**

```ts
runEventSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runEventSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.ts#L67)

## `event-observability.types.ts`

### EventOperation (type alias)

Fixed operation labels used by event authoring and publishing metrics.

**Example**

```ts
const operation: EventOperation = "client.publish";
```

**Signature**

```ts
type EventOperation =
  | "event.define"
  | "event.isDescriptor"
  | "event.assertDescriptor"
  | "function.define"
  | "function.isDescriptor"
  | "function.bindEvents"
  | "function.delivery"
  | "function.profile"
  | "function.retry"
  | "function.rejectFields"
  | "client.create"
  | "client.publish"
  | "client.parsePayload"
  | "client.normalizeOptions"
  | "client.normalizeAttributes"
  | "client.normalizeResult"
  | "client.resolveProvider"
  | "client.notify"
  | "client.resolveValue"
  | "client.assertOptionalText"
  | "client.assertVersion"
  | "client.runAbortable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.types.ts#L6)

### EventTelemetryService (interface)

Substitutable observer for event operations.
Implementations retain the original success and error channels.

**Example**

```ts
const telemetry: EventTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface EventTelemetryService {
  /** Observes one event operation.
   * @param operation - Fixed bounded operation label.
   * @param effect - Operation to observe.
   * @returns The same success and error channels.
   * @example telemetry.observe("event.define", Effect.void)
   */
  readonly observe: <A, E, R>(
    operation: EventOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-observability.types.ts#L34)

## `event-registry.ts`

### EventDescriptorByName (type alias)

Resolves a registered event descriptor from its name.

**Example**

```ts
type Created = EventDescriptorByName<"orders.created">;
```

**Signature**

```ts
type EventDescriptorByName<Name extends EventName> = EventRegistry[Name] extends EventDescriptorAny
  ? EventRegistry[Name]
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-registry.ts#L24)

### EventInputByName (type alias)

Decoded payload for a registered event name.

**Example**

```ts
type Payload = EventInputByName<"orders.created">;
```

**Signature**

```ts
type EventInputByName<Name extends EventName> = InferOutput<EventDescriptorByName<Name>["input"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-registry.ts#L30)

### EventName (type alias)

Event IDs known to the generated application registry.

**Example**

```ts
type Id = EventName;
```

**Signature**

```ts
type EventName = Extract<keyof EventRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-registry.ts#L19)

### EventRegistry (type alias)

Application registry augmented by generated event declarations.

**Example**

```ts
type Events = EventRegistry;
```

**Signature**

```ts
type EventRegistry = Relkit.EventRegistry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-registry.ts#L14)

### EventVersionByName (type alias)

Version of a registered event contract.

**Example**

```ts
type Version = EventVersionByName<"orders.created">;
```

**Signature**

```ts
type EventVersionByName<Name extends EventName> = EventDescriptorByName<Name>["version"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/event-registry.ts#L37)

## `index.ts`

### "./event-function.types.js" (namespace export)

Re-exports all named exports from the "./event-function.types.js" module.

**Signature**

```ts
export * from "./event-function.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L35)

### "./event-registry.js" (namespace export)

Re-exports all named exports from the "./event-registry.js" module.

**Signature**

```ts
export * from "./event-registry.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L33)

### DefineEventOptions

**Signature**

```ts
declare const DefineEventOptions: DefineEventOptions<Id, Version, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L3)

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L20)

### EventClient

**Signature**

```ts
declare const EventClient: EventClient<Input, Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L21)

### EventClientOptions

**Signature**

```ts
declare const EventClientOptions: EventClientOptions<Id, Version, PayloadSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L22)

### EventDeclaredEdge

**Signature**

```ts
declare const EventDeclaredEdge: EventDeclaredEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L23)

### EventDependencyError

**Signature**

```ts
declare const EventDependencyError: typeof EventDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L12)

### EventDescriptor

**Signature**

```ts
declare const EventDescriptor: EventDescriptor<Id, Version, Input, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L4)

### EventDescriptorAny

**Signature**

```ts
declare const EventDescriptorAny: EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L5)

### EventEnvelope

**Signature**

```ts
declare const EventEnvelope: EventEnvelope<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L6)

### EventEnvelopeFor

**Signature**

```ts
declare const EventEnvelopeFor: EventEnvelopeFor<E>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L7)

### EventInvocationBridge

**Signature**

```ts
declare const EventInvocationBridge: EventInvocationBridge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L24)

### EventInvocationBridgeOptions

**Signature**

```ts
declare const EventInvocationBridgeOptions: EventInvocationBridgeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L25)

### EventObservedEdge

**Signature**

```ts
declare const EventObservedEdge: EventObservedEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L26)

### EventOperationCancelledError

**Signature**

```ts
declare const EventOperationCancelledError: typeof EventOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L13)

### EventOperationContext

**Signature**

```ts
declare const EventOperationContext: EventOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L27)

### EventOperationTimeoutError

**Signature**

```ts
declare const EventOperationTimeoutError: typeof EventOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L14)

### EventPayloadValidationError

**Signature**

```ts
declare const EventPayloadValidationError: typeof EventPayloadValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L15)

### EventProfileError

**Signature**

```ts
declare const EventProfileError: typeof EventProfileError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L16)

### EventProvider

**Signature**

```ts
declare const EventProvider: EventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L28)

### EventProviderError

**Signature**

```ts
declare const EventProviderError: typeof EventProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L17)

### EventProviderResult

**Signature**

```ts
declare const EventProviderResult: EventProviderResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L29)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L30)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L31)

### UnknownEventEnvelope

**Signature**

```ts
declare const UnknownEventEnvelope: UnknownEventEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L8)

### assertEventDescriptor

**Signature**

```ts
declare const assertEventDescriptor: (value: unknown) => asserts value is EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L1)

### bindFunctionEvents

**Signature**

```ts
declare const bindFunctionEvents: <T extends FunctionWithEvents>(
  descriptor: T,
  consumed: EventDescriptorAny | undefined,
  published: readonly EventDescriptorAny[],
) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L36)

### createEventClient

**Signature**

```ts
declare const createEventClient: <
  const Id extends string,
  const Version extends number,
  const PayloadSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: EventClientOptions<Id, Version, PayloadSchema>,
) => EventClient<InferInput<PayloadSchema>, Id, Version, InferOutput<PayloadSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L11)

### defineEvent

**Signature**

```ts
declare const defineEvent: <
  const Id extends string,
  const Version extends number = 1,
  const InputSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options: DefineEventOptions<Id, Version, InputSchema>,
) => EventDescriptor<Id, Version, InferOutput<InputSchema>, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L1)

### defineEventFunction

**Signature**

```ts
declare const defineEventFunction: <
  const Id extends string,
  const Event extends EventName,
  const Publishes extends readonly EventName[] = readonly [],
  const Dependencies extends FunctionDependencies = {},
  const Options extends EventFunctionCallOptions<Id, Event, Publishes, Dependencies> =
    EventFunctionCallOptions<Id, Event, Publishes, Dependencies>,
>(
  options: EventFunctionCallOptions<Id, Event, Publishes, Dependencies> &
    Options &
    EventFunctionValidation<NoInfer<Options>>,
) => EventFunctionDescriptor<Id, Event, Publishes, Dependencies, ErrorListOf<Options>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L34)

### isEventDescriptor

**Signature**

```ts
declare const isEventDescriptor: (value: unknown) => value is EventDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L1)

### isEventFunctionDescriptor

**Signature**

```ts
declare const isEventFunctionDescriptor: (value: unknown) => value is EventFunctionDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/events/src/index.ts#L34)

---

# Functions API
Source: https://relkit.dev/docs/api/functions

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineFunction](/docs/api/functions#definefunction)
- [defineError](/docs/api/functions#defineerror)

For configuration and examples, read [Functions](/docs/learn/concepts/functions), [Declared errors](/docs/learn/concepts/errors), [migration](/docs/modules/service/migration).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images), [connect react](/guides/frontend/connect-react), [cache product prices](/guides/caching/cache-product-prices), [react to order events](/guides/events/react-to-order-events), [register users in a transaction](/guides/database/register-users-in-a-transaction).

## Frontend usage

[Call a public service operation](/docs/modules/service/routes#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/functions` — 119 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                  | Kind  | Import from         | Example                                                                      |
| ---------------------------------------------------------------------------------------------------- | ----- | ------------------- | ---------------------------------------------------------------------------- |
| [AgentClientFor](/docs/api/functions#agentclientfor-type-alias)                                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#agentclientfor-type-alias)                 |
| [AgentClients](/docs/api/functions#agentclients-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#agentclients-type-alias)                   |
| [AgentRef](/docs/api/functions#agentref-interface)                                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#agentref-interface)                        |
| [AgentRefAny](/docs/api/functions#agentrefany-type-alias)                                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#agentrefany-type-alias)                    |
| [AuthContext](/docs/api/functions#authcontext-interface)                                             | Type  | `@relkit/functions` | [API example](/docs/api/functions#authcontext-interface)                     |
| [BucketClient](/docs/api/buckets#bucketclient-interface)                                             | Type  | `@relkit/functions` | [API example](/docs/api/buckets#bucketclient-interface)                      |
| [BucketClientFor](/docs/api/functions#bucketclientfor-type-alias)                                    | Type  | `@relkit/functions` | [API example](/docs/api/functions#bucketclientfor-type-alias)                |
| [BucketClients](/docs/api/functions#bucketclients-type-alias)                                        | Type  | `@relkit/functions` | [API example](/docs/api/functions#bucketclients-type-alias)                  |
| [BucketObjectMetadata](/docs/api/buckets#bucketobjectmetadata-interface)                             | Type  | `@relkit/functions` | [API example](/docs/api/buckets#bucketobjectmetadata-interface)              |
| [BucketRef](/docs/api/functions#bucketref-type-alias)                                                | Type  | `@relkit/functions` | [API example](/docs/api/functions#bucketref-type-alias)                      |
| [BucketRefAny](/docs/api/functions#bucketrefany-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#bucketrefany-type-alias)                   |
| [CacheClient](/docs/api/cache#cacheclient-type-alias)                                                | Type  | `@relkit/functions` | [API example](/docs/api/cache#cacheclient-type-alias)                        |
| [CacheClientFor](/docs/api/functions#cacheclientfor-type-alias)                                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#cacheclientfor-type-alias)                 |
| [CacheClients](/docs/api/functions#cacheclients-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#cacheclients-type-alias)                   |
| [CacheOperationOptions](/docs/api/cache#cacheoperationoptions-interface)                             | Type  | `@relkit/functions` | [API example](/docs/api/cache#cacheoperationoptions-interface)               |
| [CacheRef](/docs/api/functions#cacheref-interface)                                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#cacheref-interface)                        |
| [CacheRefAny](/docs/api/functions#cacherefany-type-alias)                                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#cacherefany-type-alias)                    |
| [copyFunctionToolHooks](/docs/api/functions#copyfunctiontoolhooks)                                   | Value | `@relkit/functions` | [API example](/docs/api/functions#copyfunctiontoolhooks)                     |
| [copyFunctionToolHooksEffect](/docs/api/functions#copyfunctiontoolhookseffect)                       | Value | `@relkit/functions` | [API example](/docs/api/functions#copyfunctiontoolhookseffect)               |
| [createFunctionGraphNode](/docs/api/functions#createfunctiongraphnode)                               | Value | `@relkit/functions` | [API example](/docs/api/functions#createfunctiongraphnode)                   |
| [createFunctionGraphNodeEffect](/docs/api/functions#createfunctiongraphnodeeffect)                   | Value | `@relkit/functions` | [API example](/docs/api/functions#createfunctiongraphnodeeffect)             |
| [createFunctionToolInvoker](/docs/api/functions#createfunctiontoolinvoker)                           | Value | `@relkit/functions` | [API example](/docs/api/functions#createfunctiontoolinvoker)                 |
| [createFunctionToolInvokerEffect](/docs/api/functions#createfunctiontoolinvokereffect)               | Value | `@relkit/functions` | [API example](/docs/api/functions#createfunctiontoolinvokereffect)           |
| [DeclaredError](/docs/api/functions#declarederror-class)                                             | Value | `@relkit/functions` | [API example](/docs/api/functions#declarederror-class)                       |
| [DeclaredErrorOf](/docs/api/functions#declarederrorof-type-alias)                                    | Type  | `@relkit/functions` | [API example](/docs/api/functions#declarederrorof-type-alias)                |
| [DeclaredErrorsOf](/docs/api/functions#declarederrorsof-type-alias)                                  | Type  | `@relkit/functions` | [API example](/docs/api/functions#declarederrorsof-type-alias)               |
| [defineError](/docs/api/functions#defineerror)                                                       | Value | `@relkit/functions` | [API example](/docs/api/functions#defineerror)                               |
| [defineErrorEffect](/docs/api/functions#defineerroreffect)                                           | Value | `@relkit/functions` | [API example](/docs/api/functions#defineerroreffect)                         |
| [DefineErrorOptions](/docs/api/functions#defineerroroptions-interface)                               | Type  | `@relkit/functions` | [API example](/docs/api/functions#defineerroroptions-interface)              |
| [defineFunction](/docs/api/functions#definefunction)                                                 | Value | `@relkit/functions` | [API example](/docs/api/functions#definefunction)                            |
| [defineFunctionEffect](/docs/api/functions#definefunctioneffect)                                     | Value | `@relkit/functions` | [API example](/docs/api/functions#definefunctioneffect)                      |
| [DefineFunctionOptions](/docs/api/functions#definefunctionoptions-interface)                         | Type  | `@relkit/functions` | [API example](/docs/api/functions#definefunctionoptions-interface)           |
| [DescriptorRef](/docs/api/functions#descriptorref-interface)                                         | Type  | `@relkit/functions` | [API example](/docs/api/functions#descriptorref-interface)                   |
| [ErrorDescriptor](/docs/api/functions#errordescriptor-interface)                                     | Type  | `@relkit/functions` | [API example](/docs/api/functions#errordescriptor-interface)                 |
| [ErrorDescriptorAny](/docs/api/functions#errordescriptorany-type-alias)                              | Type  | `@relkit/functions` | [Module example](/docs/learn/concepts/functions)                             |
| [ErrorHttpMapping](/docs/api/functions#errorhttpmapping-interface)                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#errorhttpmapping-interface)                |
| [ErrorRef](/docs/api/functions#errorref-interface)                                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#errorref-interface)                        |
| [ErrorRetry](/docs/api/functions#errorretry-type-alias)                                              | Type  | `@relkit/functions` | [API example](/docs/api/functions#errorretry-type-alias)                     |
| [ErrorRetryInput](/docs/api/functions#errorretryinput-type-alias)                                    | Type  | `@relkit/functions` | [API example](/docs/api/functions#errorretryinput-type-alias)                |
| [EventAttributeValue](/docs/api/functions#eventattributevalue-type-alias)                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventattributevalue-type-alias)            |
| [EventClientFor](/docs/api/functions#eventclientfor-type-alias)                                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventclientfor-type-alias)                 |
| [EventClients](/docs/api/functions#eventclients-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventclients-type-alias)                   |
| [EventPublishOptions](/docs/api/functions#eventpublishoptions-interface)                             | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventpublishoptions-interface)             |
| [EventPublishResult](/docs/api/functions#eventpublishresult-interface)                               | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventpublishresult-interface)              |
| [EventRef](/docs/api/functions#eventref-interface)                                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventref-interface)                        |
| [EventRefAny](/docs/api/functions#eventrefany-type-alias)                                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#eventrefany-type-alias)                    |
| [fail](/docs/api/functions#fail)                                                                     | Value | `@relkit/functions` | [API example](/docs/api/functions#fail)                                      |
| [failEffect](/docs/api/functions#faileffect)                                                         | Value | `@relkit/functions` | [API example](/docs/api/functions#faileffect)                                |
| [FunctionAsGraphNode](/docs/api/functions#functionasgraphnode-type-alias)                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionasgraphnode-type-alias)            |
| [functionAttempt](/docs/api/functions#functionattempt)                                               | Value | `@relkit/functions` | [API example](/docs/api/functions#functionattempt)                           |
| [FunctionContext](/docs/api/functions#functioncontext-type-alias)                                    | Type  | `@relkit/functions` | [API example](/docs/api/functions#functioncontext-type-alias)                |
| [FunctionDependencies](/docs/api/functions#functiondependencies-interface)                           | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiondependencies-interface)            |
| [FunctionDescriptor](/docs/api/functions#functiondescriptor-interface)                               | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiondescriptor-interface)              |
| [FunctionEffectValue](/docs/api/functions#functioneffectvalue-interface)                             | Type  | `@relkit/functions` | [API example](/docs/api/functions#functioneffectvalue-interface)             |
| [FunctionFailure](/docs/api/functions#functionfailure-interface)                                     | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionfailure-interface)                 |
| [FunctionGraphNodeDescriptor](/docs/api/functions#functiongraphnodedescriptor-interface)             | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiongraphnodedescriptor-interface)     |
| [FunctionGraphNodeOptions](/docs/api/functions#functiongraphnodeoptions-interface)                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiongraphnodeoptions-interface)        |
| [FunctionHandlerResult](/docs/api/functions#functionhandlerresult-type-alias)                        | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionhandlerresult-type-alias)          |
| [FunctionHandlerValidation](/docs/api/functions#functionhandlervalidation-type-alias)                | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionhandlervalidation-type-alias)      |
| [FunctionOperation](/docs/api/functions#functionoperation-type-alias)                                | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionoperation-type-alias)              |
| [FunctionOperationError](/docs/api/functions#functionoperationerror-class)                           | Value | `@relkit/functions` | [API example](/docs/api/functions#functionoperationerror-class)              |
| [FunctionRef](/docs/api/functions#functionref-interface)                                             | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionref-interface)                     |
| [FunctionRefAny](/docs/api/functions#functionrefany-type-alias)                                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#functionrefany-type-alias)                 |
| [FunctionTelemetry](/docs/api/functions#functiontelemetry-class)                                     | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontelemetry-class)                   |
| [FunctionTelemetryLive](/docs/api/functions#functiontelemetrylive)                                   | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontelemetrylive)                     |
| [FunctionTelemetryService](/docs/api/functions#functiontelemetryservice-interface)                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontelemetryservice-interface)        |
| [FunctionToolApproval](/docs/api/functions#functiontoolapproval-type-alias)                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapproval-type-alias)           |
| [FunctionToolApprovalDecision](/docs/api/functions#functiontoolapprovaldecision-type-alias)          | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovaldecision-type-alias)   |
| [FunctionToolApprovalDeniedError](/docs/api/functions#functiontoolapprovaldeniederror-class)         | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovaldeniederror-class)     |
| [FunctionToolApprovalDeniedFailure](/docs/api/functions#functiontoolapprovaldeniedfailure-class)     | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovaldeniedfailure-class)   |
| [FunctionToolApprovalRequest](/docs/api/functions#functiontoolapprovalrequest-interface)             | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovalrequest-interface)     |
| [FunctionToolApprovalRequiredError](/docs/api/functions#functiontoolapprovalrequirederror-class)     | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovalrequirederror-class)   |
| [FunctionToolApprovalRequiredFailure](/docs/api/functions#functiontoolapprovalrequiredfailure-class) | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovalrequiredfailure-class) |
| [FunctionToolApprovalResolver](/docs/api/functions#functiontoolapprovalresolver-type-alias)          | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolapprovalresolver-type-alias)   |
| [FunctionToolArgumentFailure](/docs/api/functions#functiontoolargumentfailure-class)                 | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolargumentfailure-class)         |
| [FunctionToolArgumentValidationError](/docs/api/functions#functiontoolargumentvalidationerror-class) | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolargumentvalidationerror-class) |
| [FunctionToolCancelledFailure](/docs/api/functions#functiontoolcancelledfailure-class)               | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontoolcancelledfailure-class)        |
| [FunctionToolContext](/docs/api/functions#functiontoolcontext-type-alias)                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolcontext-type-alias)            |
| [FunctionToolDescriptor](/docs/api/functions#functiontooldescriptor-interface)                       | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontooldescriptor-interface)          |
| [FunctionToolHook](/docs/api/functions#functiontoolhook-type-alias)                                  | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolhook-type-alias)               |
| [FunctionToolInvokeOptions](/docs/api/functions#functiontoolinvokeoptions-interface)                 | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolinvokeoptions-interface)       |
| [FunctionToolMetadata](/docs/api/functions#functiontoolmetadata-interface)                           | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolmetadata-interface)            |
| [FunctionToolOperationCancelledError](/docs/api/functions#functiontooloperationcancellederror-class) | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontooloperationcancellederror-class) |
| [FunctionToolOptions](/docs/api/functions#functiontooloptions-interface)                             | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontooloptions-interface)             |
| [FunctionToolSideEffect](/docs/api/functions#functiontoolsideeffect-type-alias)                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontoolsideeffect-type-alias)         |
| [FunctionToolTarget](/docs/api/functions#functiontooltarget-type-alias)                              | Type  | `@relkit/functions` | [API example](/docs/api/functions#functiontooltarget-type-alias)             |
| [functionTry](/docs/api/functions#functiontry)                                                       | Value | `@relkit/functions` | [API example](/docs/api/functions#functiontry)                               |
| [InvocationMetadata](/docs/api/functions#invocationmetadata-type-alias)                              | Type  | `@relkit/functions` | [API example](/docs/api/functions#invocationmetadata-type-alias)             |
| [InvocationSource](/docs/api/functions#invocationsource-type-alias)                                  | Type  | `@relkit/functions` | [API example](/docs/api/functions#invocationsource-type-alias)               |
| [invokeFunctionGraphNodeEffect](/docs/api/functions#invokefunctiongraphnodeeffect)                   | Value | `@relkit/functions` | [API example](/docs/api/functions#invokefunctiongraphnodeeffect)             |
| [invokeFunctionToolEffect](/docs/api/functions#invokefunctiontooleffect)                             | Value | `@relkit/functions` | [API example](/docs/api/functions#invokefunctiontooleffect)                  |
| [isErrorDescriptor](/docs/api/functions#iserrordescriptor)                                           | Value | `@relkit/functions` | [API example](/docs/api/functions#iserrordescriptor)                         |
| [isErrorDescriptorEffect](/docs/api/functions#iserrordescriptoreffect)                               | Value | `@relkit/functions` | [API example](/docs/api/functions#iserrordescriptoreffect)                   |
| [isFunctionGraphNode](/docs/api/functions#isfunctiongraphnode)                                       | Value | `@relkit/functions` | [API example](/docs/api/functions#isfunctiongraphnode)                       |
| [isFunctionGraphNodeEffect](/docs/api/functions#isfunctiongraphnodeeffect)                           | Value | `@relkit/functions` | [API example](/docs/api/functions#isfunctiongraphnodeeffect)                 |
| [isStreamOutputSchema](/docs/api/functions#isstreamoutputschema)                                     | Value | `@relkit/functions` | [API example](/docs/api/functions#isstreamoutputschema)                      |
| [isStreamOutputSchemaEffect](/docs/api/functions#isstreamoutputschemaeffect)                         | Value | `@relkit/functions` | [API example](/docs/api/functions#isstreamoutputschemaeffect)                |
| [JobClientFor](/docs/api/functions#jobclientfor-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobclientfor-type-alias)                   |
| [JobClients](/docs/api/functions#jobclients-type-alias)                                              | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobclients-type-alias)                     |
| [JobEnqueueOptions](/docs/api/functions#jobenqueueoptions-interface)                                 | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobenqueueoptions-interface)               |
| [JobEnqueueResult](/docs/api/functions#jobenqueueresult-interface)                                   | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobenqueueresult-interface)                |
| [JobRef](/docs/api/app#jobref-interface)                                                             | Type  | `@relkit/functions` | [Module example](/docs/learn/concepts/functions)                             |
| [JobRefAny](/docs/api/app#jobrefany-type-alias)                                                      | Type  | `@relkit/functions` | [Module example](/docs/learn/concepts/functions)                             |
| [JobState](/docs/api/functions#jobstate-type-alias)                                                  | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobstate-type-alias)                       |
| [JobStatus](/docs/api/functions#jobstatus-interface)                                                 | Type  | `@relkit/functions` | [API example](/docs/api/functions#jobstatus-interface)                       |
| [NormalizedErrorRetry](/docs/api/functions#normalizederrorretry-interface)                           | Type  | `@relkit/functions` | [API example](/docs/api/functions#normalizederrorretry-interface)            |
| [observeFunction](/docs/api/functions#observefunction)                                               | Value | `@relkit/functions` | [API example](/docs/api/functions#observefunction)                           |
| [PublicClock](/docs/api/functions#publicclock-type-alias)                                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#publicclock-type-alias)                    |
| [PublicLogger](/docs/api/functions#publiclogger-type-alias)                                          | Type  | `@relkit/functions` | [API example](/docs/api/functions#publiclogger-type-alias)                   |
| [RELKIT_FUNCTION_GRAPH_NODE](/docs/api/functions#relkit_function_graph_node)                         | Value | `@relkit/functions` | [API example](/docs/api/functions#relkit_function_graph_node)                |
| [ResolvedApplicationEnv](/docs/api/functions#resolvedapplicationenv-type-alias)                      | Type  | `@relkit/functions` | [API example](/docs/api/functions#resolvedapplicationenv-type-alias)         |
| [runFunctionPromise](/docs/api/functions#runfunctionpromise)                                         | Value | `@relkit/functions` | [API example](/docs/api/functions#runfunctionpromise)                        |
| [runFunctionSync](/docs/api/functions#runfunctionsync)                                               | Value | `@relkit/functions` | [API example](/docs/api/functions#runfunctionsync)                           |
| [streamOf](/docs/api/functions#streamof)                                                             | Value | `@relkit/functions` | [API example](/docs/api/functions#streamof)                                  |
| [streamOfEffect](/docs/api/functions#streamofeffect)                                                 | Value | `@relkit/functions` | [API example](/docs/api/functions#streamofeffect)                            |
| [StreamOutputSchema](/docs/api/functions#streamoutputschema-interface)                               | Type  | `@relkit/functions` | [API example](/docs/api/functions#streamoutputschema-interface)              |
| [TaskClientFor](/docs/api/functions#taskclientfor-type-alias)                                        | Type  | `@relkit/functions` | [API example](/docs/api/functions#taskclientfor-type-alias)                  |
| [TaskClients](/docs/api/functions#taskclients-type-alias)                                            | Type  | `@relkit/functions` | [API example](/docs/api/functions#taskclients-type-alias)                    |
| [TaskTriggerOptions](/docs/api/functions#tasktriggeroptions-interface)                               | Type  | `@relkit/functions` | [API example](/docs/api/functions#tasktriggeroptions-interface)              |

## `client-maps.types.ts`

### AgentClientFor (type alias)

Typed callable client for an agent descriptor.

**Example**

```ts
const invoke: AgentClientFor<typeof agent> = async (input) => output;
```

**Signature**

```ts
type AgentClientFor<T> = (input: InputOf<T>) => Promise<OutputOf<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L58)

### AgentClients (type alias)

Named agent clients projected from dependencies.

**Example**

```ts
const agents: AgentClients<typeof dependencies.agents> = context.agents;
```

**Signature**

```ts
type AgentClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: AgentClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L151)

### BucketClientFor (type alias)

Bucket client exposed for a declared bucket.

**Example**

```ts
const client: BucketClientFor<typeof bucket> = buckets.uploads;
```

**Signature**

```ts
type BucketClientFor<T> = BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L112)

### BucketClients (type alias)

Named bucket clients projected from dependencies.

**Example**

```ts
const buckets: BucketClients<typeof dependencies.buckets> = context.buckets;
```

**Signature**

```ts
type BucketClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: BucketClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L139)

### CacheClientFor (type alias)

Key and value typed cache client.

**Example**

```ts
const client: CacheClientFor<typeof cache> = caches.sessions;
```

**Signature**

```ts
type CacheClientFor<T> = CacheClient<KeyOf<T>, ValueOf<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L116)

### CacheClients (type alias)

Named cache clients projected from dependencies.

**Example**

```ts
const cache: CacheClients<typeof dependencies.cache> = context.cache;
```

**Signature**

```ts
type CacheClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: CacheClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L145)

### EventClientFor (type alias)

Typed publish client for an event descriptor.

**Example**

```ts
const client: EventClientFor<typeof event> = events.created;
```

**Signature**

```ts
type EventClientFor<T> = {
  /** Publishes an event.
   * @param payload - Event payload.
   * @param options - Optional key and attributes.
   * @returns Accepted event envelope.
   * @example await events.created.publish(payload);
   */
  publish(
    payload: EventInputOf<T>,
    options?: EventPublishOptions,
  ): Promise<EventPublishResult<EventIdOf<T>, EventVersionOf<T>, EventOutputOf<T>>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L97)

### EventClients (type alias)

Named event clients projected from published events.

**Example**

```ts
const events: EventClients<typeof published> = context.events;
```

**Signature**

```ts
type EventClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: EventClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L133)

### JobClientFor (type alias)

Typed enqueue client for a job descriptor.

**Example**

```ts
const client: JobClientFor<typeof job> = jobs.myJob;
```

**Signature**

```ts
type JobClientFor<T> = {
  /** Enqueues a job invocation.
   * @param input - Job input.
   * @param options - Optional correlation metadata.
   * @returns Acceptance receipt.
   * @example await jobs.send.enqueue(input);
   */
  enqueue(input: InputOf<T>, options?: JobEnqueueOptions): Promise<JobEnqueueResult>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L62)

### JobClients (type alias)

Named job clients projected from dependencies.

**Example**

```ts
const jobs: JobClients<typeof dependencies.jobs> = context.jobs;
```

**Signature**

```ts
type JobClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: JobClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L121)

### TaskClientFor (type alias)

Typed trigger client for a task descriptor.

**Example**

```ts
const client: TaskClientFor<typeof task> = tasks.send;
```

**Signature**

```ts
type TaskClientFor<T> = {
  /** Triggers a task run.
   * @param input - Task input.
   * @param options - Optional scheduling and idempotency controls.
   * @returns Handle for the new run.
   * @example await tasks.send.trigger(input);
   */
  trigger(input: InputOf<T>, options?: TaskTriggerOptions): Promise<RunHandle>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L85)

### TaskClients (type alias)

Named task clients projected from dependencies.

**Example**

```ts
const tasks: TaskClients<typeof dependencies.tasks> = context.tasks;
```

**Signature**

```ts
type TaskClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: TaskClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L127)

### TaskTriggerOptions (interface)

Scheduling and idempotency options for a task.

**Example**

```ts
await tasks.send.trigger(input, { operationId: "send-1" });
```

**Signature**

```ts
export interface TaskTriggerOptions {
  readonly operationId?: string;
  readonly idempotencyKey?: string;
  readonly delay?: string;
  readonly at?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/client-maps.types.ts#L74)

## `clients.types.ts`

### "./client-maps.types.js" (namespace export)

Re-exports all named exports from the "./client-maps.types.js" module.

**Signature**

```ts
export * from "./client-maps.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L84)

### BucketClient

**Signature**

```ts
declare const BucketClient: BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L81)

### BucketObjectMetadata

**Signature**

```ts
declare const BucketObjectMetadata: BucketObjectMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L81)

### BucketPutOptions

**Signature**

```ts
declare const BucketPutOptions: BucketPutOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L81)

### CacheClient

**Signature**

```ts
declare const CacheClient: CacheClient<Key, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L82)

### CacheOperationOptions

**Signature**

```ts
declare const CacheOperationOptions: CacheOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L82)

### EventAttributeValue (type alias)

Scalar value accepted in event attributes.

**Example**

```ts
const value: EventAttributeValue = true;
```

**Signature**

```ts
type EventAttributeValue = string | number | boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L44)

### EventPublishOptions (interface)

Metadata supplied with an event publication.

**Example**

```ts
await events.publish(payload, { key: "order-1" });
```

**Signature**

```ts
export interface EventPublishOptions {
  readonly key?: string;
  readonly attributes?: Readonly<Record<string, EventAttributeValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L65)

### EventPublishResult (interface)

Accepted event envelope returned by publication.

**Example**

```ts
const published: EventPublishResult = await events.publish(payload);
```

**Signature**

```ts
export interface EventPublishResult<
  Id extends string = string,
  Version extends number = number,
  Payload = unknown,
> extends EventEnvelope<Id, Version, Payload> {
  readonly accepted: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L73)

### JobEnqueueOptions (interface)

Options for enqueuing a job.

**Example**

```ts
await jobs.enqueue(input, { correlationId: "trace-1" });
```

**Signature**

```ts
export interface JobEnqueueOptions {
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L23)

### JobEnqueueResult (interface)

Receipt returned when a job is accepted.

**Example**

```ts
const receipt: JobEnqueueResult = await jobs.enqueue(input);
```

**Signature**

```ts
export interface JobEnqueueResult {
  readonly instanceId: string;
  readonly accepted: true;
  readonly duplicate?: boolean;
  readonly idempotencyKey?: string;
  readonly idempotencyExpiresAt?: number;
  readonly status: Extract<JobState, "accepted">;
  readonly profile: string;
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L30)

### JobState (type alias)

Lifecycle state of a queued job.

**Example**

```ts
const state: JobState = "accepted";
```

**Signature**

```ts
type JobState = "accepted" | "available" | "leased" | "delayed" | "completed" | "dead-lettered";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L6)

### JobStatus (interface)

Snapshot of one queued job.

**Example**

```ts
const status: JobStatus = await jobs.status(id);
```

**Signature**

```ts
export interface JobStatus {
  readonly instanceId: string;
  readonly state: JobState;
  readonly profile: string;
  readonly attempt: number;
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/clients.types.ts#L12)

## `define-error-validation.ts`

### assertErrorSchema

Asserts a declared error data schema.

**Throws**

TypeError for a nonstandard schema.

**Example**

```ts
assertErrorSchema(z.string());
```

**Signature**

```ts
declare const assertErrorSchema: (value: unknown) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L100)

### assertErrorSchemaEffect

Validates a Standard Schema through Effect.

**Example**

```ts
Effect.runSync(assertErrorSchemaEffect(z.string()));
```

**Signature**

```ts
declare const assertErrorSchemaEffect: (
  value: unknown,
) => Effect.Effect<StandardSchemaV1<unknown, unknown>, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L77)

### isErrorDescriptor

Recognizes a declared error descriptor.

**Example**

```ts
if (isErrorDescriptor(value)) console.log(value.id);
```

**Signature**

```ts
declare const isErrorDescriptor: (value: unknown) => value is ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L41)

### isErrorDescriptorEffect

Checks a declared error descriptor through Effect.

**Example**

```ts
Effect.runSync(isErrorDescriptorEffect(value));
```

**Signature**

```ts
declare const isErrorDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L14)

### isRecord

Recognizes a nonarray record-like value.

**Example**

```ts
isRecord({ id: "one" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L124)

### isRecordEffect

Checks a record-like value through Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({}));
```

**Signature**

```ts
declare const isRecordEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L109)

### validateErrorHttp

Validates a declared error HTTP mapping.

**Throws**

TypeError for an invalid status.

**Example**

```ts
validateErrorHttp({ status: 404 });
```

**Signature**

```ts
declare const validateErrorHttp: (http: ErrorHttpMapping | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L68)

### validateErrorHttpEffect

Validates an HTTP status mapping through Effect.

**Example**

```ts
Effect.runSync(validateErrorHttpEffect({ status: 404 }));
```

**Signature**

```ts
declare const validateErrorHttpEffect: (
  http: ErrorHttpMapping | undefined,
) => Effect.Effect<void, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error-validation.ts#L50)

## `define-error.ts`

### defineError

Defines a typed application error.

**Throws**

TypeError for invalid schema, retry, HTTP status, or message.

**Example**

```ts
import { defineError } from "@relkit/functions";
import { z } from "@relkit/schema";
const NotFound = defineError({
  id: "orders.not-found",
  data: z.object({ id: z.string() }),
  message: "Missing",
});
const error = new NotFound({ id: "order-1" });
```

**Signature**

```ts
declare const defineError: <const Id extends string, const DataSchema extends StandardSchemaV1>(
  options: DefineErrorOptions<Id, DataSchema>,
) => ErrorDescriptor<Id, InferOutput<DataSchema>, DataSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L206)

Since v0.1.0

### defineErrorEffect

Defines a typed application error with safe data, transport metadata, and an optional retry hint.
The compiler derives omitted IDs. Omitted retry means never; `later` only hints to durable work.

**Example**

```ts
const NotFound = Effect.runSync(
  defineErrorEffect({
    id: "orders.not-found",
    data: z.object({ orderId: z.string() }),
    message: ({ orderId }) => `Order ${orderId} was not found`,
  }),
);
new NotFound({ orderId: "order-1" });
```

**Signature**

```ts
declare const defineErrorEffect: <
  const Id extends string,
  const DataSchema extends StandardSchemaV1,
>(
  options: DefineErrorOptions<Id, DataSchema>,
) => Effect.Effect<
  ErrorDescriptor<Id, InferOutput<DataSchema>, DataSchema>,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L90)

Since v0.1.0

### DeclaredError (class)

Validated application error instance.

**Example**

```ts
const error = new NotFound({ id: "one" });
```

**Signature**

```ts
declare class DeclaredError<Id, Data> {
  constructor(
    id: Id,
    ref: ErrorRef<Id>,
    data: Data,
    message: string,
    retry: ErrorRetry,
    afterMs: number | undefined,
    http: ErrorHttpMapping | undefined,
  );
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L45)

### id (property)

**Signature**

```ts
readonly id: Id
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L46)

### ref (property)

**Signature**

```ts
readonly ref: ErrorRef<Id>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L47)

### data (property)

**Signature**

```ts
readonly data: Data
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L48)

### retry (property)

**Signature**

```ts
readonly retry: ErrorRetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L49)

### afterMs (property)

**Signature**

```ts
readonly afterMs: number | undefined
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L50)

### http (property)

**Signature**

```ts
readonly http: ErrorHttpMapping | undefined
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L51)

### DefineErrorOptions

**Signature**

```ts
declare const DefineErrorOptions: DefineErrorOptions<Id, DataSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L35)

### ErrorDescriptor

**Signature**

```ts
declare const ErrorDescriptor: ErrorDescriptor<Id, Data, DataSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L36)

### ErrorDescriptorAny

**Signature**

```ts
declare const ErrorDescriptorAny: ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L37)

### ErrorHttpMapping

**Signature**

```ts
declare const ErrorHttpMapping: ErrorHttpMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L38)

### ErrorRef

**Signature**

```ts
declare const ErrorRef: ErrorRef<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L39)

### ErrorRetry

**Signature**

```ts
declare const ErrorRetry: ErrorRetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L33)

### ErrorRetryInput

**Signature**

```ts
declare const ErrorRetryInput: ErrorRetryInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L33)

### NormalizedErrorRetry

**Signature**

```ts
declare const NormalizedErrorRetry: NormalizedErrorRetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L33)

### isErrorDescriptor

**Signature**

```ts
declare const isErrorDescriptor: (value: unknown) => value is ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L31)

### isErrorDescriptorEffect

**Signature**

```ts
declare const isErrorDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.ts#L31)

## `define-error.types.ts`

### DefineErrorOptions (interface)

Options for constructing a declared error descriptor.

**Example**

```ts
defineError({ id: "orders.not-found", data: z.object({ id: z.string() }), message: "Missing" });
```

**Signature**

```ts
export interface DefineErrorOptions<
  Id extends string,
  DataSchema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly data: DataSchema;
  readonly message: string | ((data: InferOutput<DataSchema>) => string);
  readonly http?: ErrorHttpMapping;
  readonly retry?: ErrorRetryInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.types.ts#L47)

### ErrorDescriptor (interface)

Callable descriptor for creating a declared error.

**Example**

```ts
const error = new NotFound({ id: "one" });
```

**Signature**

```ts
export interface ErrorDescriptor<
  Id extends string,
  Data,
  DataSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorMetadata {
  readonly kind: "error";
  readonly id: Id;
  readonly ref: ErrorRef<Id>;
  readonly data: DataSchema;
  readonly message: string | ((data: Data) => string);
  readonly http?: ErrorHttpMapping;
  readonly retry: ErrorRetry;
  readonly afterMs?: number;
  readonly create: (input: InferInput<DataSchema>) => DeclaredError<Id, Data>;
  new (input: InferInput<DataSchema>): DeclaredError<Id, Data>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.types.ts#L24)

### ErrorDescriptorAny (type alias)

Any declared error descriptor for heterogeneous collections.

**Signature**

```ts
type ErrorDescriptorAny = ErrorDescriptor<string, any, StandardSchemaV1<any, any>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.types.ts#L42)

### ErrorHttpMapping (interface)

HTTP mapping for a declared error.

**Example**

```ts
const http: ErrorHttpMapping = { status: 404 };
```

**Signature**

```ts
export interface ErrorHttpMapping {
  readonly status: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.types.ts#L9)

### ErrorRef (interface)

Stable reference to an application error.

**Example**

```ts
const ref: ErrorRef = { kind: "error", id: "orders.not-found" };
```

**Signature**

```ts
export interface ErrorRef<Id extends string = string> {
  readonly kind: "error";
  readonly id: Id;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-error.types.ts#L16)

## `define-function-inference.types.ts`

## `define-function-validation.ts`

### assertHook

Checks an optional function lifecycle hook.

**Throws**

TypeError when the hook is not callable.

**Example**

```ts
assertHook(() => {}, "onBefore");
```

**Signature**

```ts
declare const assertHook: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L63)

### assertHookEffect

Checks an optional hook through Effect.

**Example**

```ts
Effect.runSync(assertHookEffect(() => {}, "onBefore"));
```

**Signature**

```ts
declare const assertHookEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L47)

### assertSchema

Asserts a Standard Schema validator.

**Throws**

TypeError for malformed schemas.

**Example**

```ts
assertSchema(z.string(), "input");
```

**Signature**

```ts
declare const assertSchema: (value: unknown, name: string) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L97)

### assertSchemaEffect

Checks a function schema through Effect.

**Example**

```ts
Effect.runSync(assertSchemaEffect(z.string(), "input"));
```

**Signature**

```ts
declare const assertSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<StandardSchemaV1<unknown, unknown>, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L73)

### copyDependencies

**Signature**

```ts
declare const copyDependencies: <D extends FunctionDependencies>(
  dependencies: D | undefined,
) => D | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L9)

### copyDependenciesEffect

**Signature**

```ts
declare const copyDependenciesEffect: <D extends FunctionDependencies>(
  dependencies: D | undefined,
) => Effect.Effect<D | undefined, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L10)

### copyPublishes

**Signature**

```ts
declare const copyPublishes: <Names extends readonly string[]>(
  publishes: Names | undefined,
) => Names | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L11)

### copyPublishesEffect

**Signature**

```ts
declare const copyPublishesEffect: <Names extends readonly string[]>(
  publishes: Names | undefined,
) => Effect.Effect<Names | undefined, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L12)

### functionTargetForReceiver

Resolves a method receiver to a callable function descriptor.

**Throws**

TypeError when receiver is event-only.

**Example**

```ts
functionTargetForReceiver(fn, fn);
```

**Signature**

```ts
declare const functionTargetForReceiver: (
  receiver: unknown,
  fallback: FunctionRefAny,
) => FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L136)

### functionTargetForReceiverEffect

Resolves a callable receiver through Effect.

**Example**

```ts
Effect.runSync(functionTargetForReceiverEffect(fn, fn));
```

**Signature**

```ts
declare const functionTargetForReceiverEffect: (
  receiver: unknown,
  fallback: FunctionRefAny,
) => Effect.Effect<FunctionRefAny, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L107)

### validateLimit

Checks a positive integer function limit.

**Throws**

TypeError for an invalid limit.

**Example**

```ts
validateLimit(5, "timeoutMs");
```

**Signature**

```ts
declare const validateLimit: (value: number | undefined, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L37)

### validateLimitEffect

Checks a function limit through Effect.

**Example**

```ts
Effect.runSync(validateLimitEffect(5, "timeoutMs"));
```

**Signature**

```ts
declare const validateLimitEffect: (
  value: number | undefined,
  name: string,
) => Effect.Effect<void, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function-validation.ts#L21)

## `define-function.ts`

### defineFunction

Defines the graph-visible executable unit shared by HTTP, background, tool, and agent calls.

The `id` is optional for source-scoped functions; the compiler derives it from the
source/export hierarchy. Durable resources keep explicit IDs. The handler receives
validated reusable input and an invocation-scoped context. Use `descriptor.invoke(input)`
for nested calls so the
common engine preserves validation, service policy, limits, and telemetry.

**Throws**

TypeError for invalid definition inputs.

**Example**

```ts
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const greet = defineFunction({
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
  handler: async ({ name }, context) => {
    context.log.info("greeting requested");
    return { message: `Hello, ${name}!` };
  },
});
const result = await greet.invoke({ name: "Ada" });
void result;
void greet;
```

**Signature**

```ts
declare const defineFunction: DefineFunction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L124)

Since v0.1.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="templates/default/v1/api/src/services/orders/functions/create-order.function.ts"
/** Validates order input, invokes the service-local pricing function, and returns the calculated order. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import priceOrder from "@app/services/orders/functions/price-order.function.js";

const orderInput = z.object({
  orderId: z.string().min(1),
  sku: z.string().min(1),
  quantity: z.number().int().positive(),
});

const orderOutput = z.object({
  orderId: z.string(),
  sku: z.string(),
  totalCents: z.number().int().nonnegative(),
});

const createOrder = defineFunction({
  input: orderInput,
  output: orderOutput,

  handler: async (input) => {
    const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
    const order = {
      orderId: input.orderId,
      sku: input.sku,
      totalCents,
    };

    return order;
  },
});

export default createOrder;
```

```ts title="templates/default/v1/api/src/routes/orders/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineServiceRoutes } from "@relkit/app/routes";
import orders from "@app/services/orders/service.js";

export const { POST } = defineServiceRoutes(orders, {
  POST: { member: "createOrder", successStatus: 201 },
});
```

**Frontend**

After [frontend setup and pulling this API example's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`:

```tsx title="src/CreateOrder.tsx — frontend"
"use client";

/** Calls the API example's Orders function through its public route, retaining the generated input and price result. */
import { useRelkitClient, useRouteMutation } from "@relkit/client/react";

/** Creates one order in the API example without importing the backend service.
 * @returns A guarded submission action and its typed price or failure. */
export function CreateOrder() {
  const { status } = useRelkitClient();
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() => create.mutate({ orderId: crypto.randomUUID(), sku: "book", quantity: 2 })}
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Total: {create.data.totalCents} cents</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

This calls the same `createOrder` function through `POST /orders`: `orderId`, `sku`, and `quantity`
come from its input schema, and `totalCents` comes from its output schema. The browser calls RPC;
it never imports the descriptor or calls `.invoke()`. Service membership needs a client-exposed
route to become a browser operation.

Reference: [`useRouteMutation`](/docs/api/client#useroutemutation).
Continue with [mutation state and recovery](/docs/modules/client/mutations).

### AgentClientFor

**Signature**

```ts
declare const AgentClientFor: AgentClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L14)

### AgentClients

**Signature**

```ts
declare const AgentClients: AgentClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L15)

### AgentRef

**Signature**

```ts
declare const AgentRef: AgentRef<Id, InputSchema, OutputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L16)

### AgentRefAny

**Signature**

```ts
declare const AgentRefAny: AgentRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L17)

### AuthContext

**Signature**

```ts
declare const AuthContext: AuthContext<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L18)

### BucketClient

**Signature**

```ts
declare const BucketClient: BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L19)

### BucketClientFor

**Signature**

```ts
declare const BucketClientFor: BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L20)

### BucketClients

**Signature**

```ts
declare const BucketClients: BucketClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L21)

### BucketObjectMetadata

**Signature**

```ts
declare const BucketObjectMetadata: BucketObjectMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L22)

### BucketRef

**Signature**

```ts
declare const BucketRef: BucketRef<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L23)

### BucketRefAny

**Signature**

```ts
declare const BucketRefAny: BucketRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L24)

### CacheClient

**Signature**

```ts
declare const CacheClient: CacheClient<Key, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L25)

### CacheClientFor

**Signature**

```ts
declare const CacheClientFor: CacheClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L26)

### CacheClients

**Signature**

```ts
declare const CacheClients: CacheClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L27)

### CacheOperationOptions

**Signature**

```ts
declare const CacheOperationOptions: CacheOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L28)

### CacheRef

**Signature**

```ts
declare const CacheRef: CacheRef<Id, KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L29)

### CacheRefAny

**Signature**

```ts
declare const CacheRefAny: CacheRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L30)

### DefineFunctionOptions

**Signature**

```ts
declare const DefineFunctionOptions: DefineFunctionOptions<
  Id,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L32)

### DescriptorRef

**Signature**

```ts
declare const DescriptorRef: DescriptorRef<Kind, Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L31)

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L35)

### EventClientFor

**Signature**

```ts
declare const EventClientFor: EventClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L33)

### EventClients

**Signature**

```ts
declare const EventClients: EventClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L34)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L36)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L37)

### EventRef

**Signature**

```ts
declare const EventRef: EventRef<Id, InputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L38)

### EventRefAny

**Signature**

```ts
declare const EventRefAny: EventRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L39)

### FunctionContext

**Signature**

```ts
declare const FunctionContext: FunctionContext<D, Publishes, Progress>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L40)

### FunctionDependencies

**Signature**

```ts
declare const FunctionDependencies: FunctionDependencies;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L41)

### FunctionDescriptor

**Signature**

```ts
declare const FunctionDescriptor: FunctionDescriptor<
  Id,
  Input,
  Output,
  Dependencies,
  Errors,
  InputSchema,
  OutputSchema,
  ToolMetadata,
  Publishes,
  ProgressSchema
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L42)

### FunctionRef

**Signature**

```ts
declare const FunctionRef: FunctionRef<Id, Input, Output, Errors, InputSchema, OutputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L43)

### FunctionRefAny

**Signature**

```ts
declare const FunctionRefAny: FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L44)

### InvocationMetadata

**Signature**

```ts
declare const InvocationMetadata: InvocationMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L45)

### InvocationSource

**Signature**

```ts
declare const InvocationSource: InvocationSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L46)

### JobClientFor

**Signature**

```ts
declare const JobClientFor: JobClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L48)

### JobClients

**Signature**

```ts
declare const JobClients: JobClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L49)

### JobEnqueueOptions

**Signature**

```ts
declare const JobEnqueueOptions: JobEnqueueOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L47)

### JobEnqueueResult

**Signature**

```ts
declare const JobEnqueueResult: JobEnqueueResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L50)

### JobRef

**Signature**

```ts
declare const JobRef: JobRef<Id, InputSchema, OutputSchema, Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L51)

### JobRefAny

**Signature**

```ts
declare const JobRefAny: JobRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L52)

### JobState

**Signature**

```ts
declare const JobState: JobState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L53)

### JobStatus

**Signature**

```ts
declare const JobStatus: JobStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L54)

### PublicClock

**Signature**

```ts
declare const PublicClock: PublicClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L58)

### PublicLogger

**Signature**

```ts
declare const PublicLogger: PublicLogger;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L59)

### ResolvedApplicationEnv

**Signature**

```ts
declare const ResolvedApplicationEnv: Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L60)

### TaskClientFor

**Signature**

```ts
declare const TaskClientFor: TaskClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L55)

### TaskClients

**Signature**

```ts
declare const TaskClients: TaskClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L56)

### TaskTriggerOptions

**Signature**

```ts
declare const TaskTriggerOptions: TaskTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L57)

### defineFunctionEffect

Defines a callable function through Effect.

**Example**

```ts
Effect.runSync(defineFunctionEffect({ input, output, handler }));
```

**Signature**

```ts
declare const defineFunctionEffect: DefineFunctionEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.ts#L90)

## `define-function.types.ts`

### DefineFunction (interface)

Overloaded public function constructor preserving schema inference.

**Example**

```ts
const greet = defineFunction({ input, output, handler });
```

**Signature**

```ts
export interface DefineFunction {
  /** Defines a function without declared dependencies.
   * @param options - Schemas, handler, and function metadata.
   * @returns A callable descriptor with inferred input and output types.
   * @example const greet = defineFunction({ input, output, handler });
   */
  <
    const Id extends string,
    const InputSchema extends StandardSchemaV1,
    const OutputSchema extends StandardSchemaV1,
    const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
    const Publishes extends readonly Extract<keyof Relkit.EventRegistry, string>[] = readonly [],
    const Options extends FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      {},
      Publishes,
      ProgressSchema
    > = FunctionCallOptions<Id, InputSchema, OutputSchema, {}, Publishes, ProgressSchema>,
  >(
    options: FunctionCallOptions<Id, InputSchema, OutputSchema, {}, Publishes, ProgressSchema> &
      Options &
      FunctionCallValidation<NoInfer<Options>, InferOutput<OutputSchema>> & {
        readonly dependencies?: never;
      },
  ): FunctionDescriptor<
    Id,
    InferOutput<InputSchema>,
    InferOutput<OutputSchema>,
    {},
    ErrorListOf<Options>,
    InputSchema,
    OutputSchema,
    ToolMetadataOf<Options>,
    Publishes,
    ProgressSchema
  >;

  /** Defines a function with declared dependencies.
   * @param options - Schemas, handler, dependency map, and function metadata.
   * @returns A callable descriptor whose context includes the declared dependencies.
   * @example const lookup = defineFunction({ input, output, dependencies, handler });
   */
  <
    const Id extends string,
    const InputSchema extends StandardSchemaV1,
    const OutputSchema extends StandardSchemaV1,
    const Dependencies extends FunctionDependencies,
    const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
    const Publishes extends readonly Extract<keyof Relkit.EventRegistry, string>[] = readonly [],
    const Options extends FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      Dependencies,
      Publishes,
      ProgressSchema
    > = FunctionCallOptions<Id, InputSchema, OutputSchema, Dependencies, Publishes, ProgressSchema>,
  >(
    options: FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      Dependencies,
      Publishes,
      ProgressSchema
    > &
      Options &
      FunctionCallValidation<NoInfer<Options>, InferOutput<OutputSchema>>,
  ): FunctionDescriptor<
    Id,
    InferOutput<InputSchema>,
    InferOutput<OutputSchema>,
    Dependencies,
    ErrorListOf<Options>,
    InputSchema,
    OutputSchema,
    ToolMetadataOf<Options>,
    Publishes,
    ProgressSchema
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.types.ts#L27)

### DefineFunctionEffect (interface)

Effect constructor with the same schema and handler inference as defineFunction.

**Signature**

```ts
export interface DefineFunctionEffect {
  <
    const Id extends string,
    const InputSchema extends StandardSchemaV1,
    const OutputSchema extends StandardSchemaV1,
    const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
    const Publishes extends readonly Extract<keyof Relkit.EventRegistry, string>[] = readonly [],
    const Options extends FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      {},
      Publishes,
      ProgressSchema
    > = FunctionCallOptions<Id, InputSchema, OutputSchema, {}, Publishes, ProgressSchema>,
  >(
    options: FunctionCallOptions<Id, InputSchema, OutputSchema, {}, Publishes, ProgressSchema> &
      Options &
      FunctionCallValidation<NoInfer<Options>, InferOutput<OutputSchema>> & {
        readonly dependencies?: never;
      },
  ): Effect.Effect<
    FunctionDescriptor<
      Id,
      InferOutput<InputSchema>,
      InferOutput<OutputSchema>,
      {},
      ErrorListOf<Options>,
      InputSchema,
      OutputSchema,
      ToolMetadataOf<Options>,
      Publishes,
      ProgressSchema
    >,
    FunctionOperationError
  >;

  <
    const Id extends string,
    const InputSchema extends StandardSchemaV1,
    const OutputSchema extends StandardSchemaV1,
    const Dependencies extends FunctionDependencies,
    const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
    const Publishes extends readonly Extract<keyof Relkit.EventRegistry, string>[] = readonly [],
    const Options extends FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      Dependencies,
      Publishes,
      ProgressSchema
    > = FunctionCallOptions<Id, InputSchema, OutputSchema, Dependencies, Publishes, ProgressSchema>,
  >(
    options: FunctionCallOptions<
      Id,
      InputSchema,
      OutputSchema,
      Dependencies,
      Publishes,
      ProgressSchema
    > &
      Options &
      FunctionCallValidation<NoInfer<Options>, InferOutput<OutputSchema>>,
  ): Effect.Effect<
    FunctionDescriptor<
      Id,
      InferOutput<InputSchema>,
      InferOutput<OutputSchema>,
      Dependencies,
      ErrorListOf<Options>,
      InputSchema,
      OutputSchema,
      ToolMetadataOf<Options>,
      Publishes,
      ProgressSchema
    >,
    FunctionOperationError
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.types.ts#L112)

### FunctionImplementationOptions (type alias)

Internal callable definition before the invocation mode is fixed.

**Example**

```ts
const options: FunctionImplementationOptions = { input, output, handler };
```

**Signature**

```ts
type FunctionImplementationOptions = Omit<
  FunctionDescriptorFactoryOptions,
  "id" | "invocationMode"
> & {
  readonly id?: string;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/define-function.types.ts#L6)

## `function-as-tool.types.ts`

### FunctionAsTool (type alias)

Overloads for deriving a tool from a callable function.

**Example**

```ts
const tool = fn.asTool({ description: "Lookup", sideEffect: "read", approval: "never" });
```

**Signature**

```ts
type FunctionAsTool<
  FunctionId extends string,
  Input,
  Output,
  Errors extends readonly ErrorDescriptorAny[],
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  ToolMetadata extends FunctionToolMetadata | undefined,
> = {
  /** Creates a tool with an explicit ID and metadata.
   * @param options - Tool identity and behavior metadata.
   * @returns Frozen tool descriptor.
   * @example fn.asTool({ id: "lookup", description: "Lookup", sideEffect: "read", approval: "never" });
   */
  <const ToolId extends string>(
    options: FunctionToolOptions<ToolId, Input, Output> & { readonly id: ToolId },
  ): FunctionToolView<ToolId, FunctionId, Input, Output, Errors, InputSchema, OutputSchema>;
  /** Creates a tool with a derived ID.
   * @param options - Tool behavior metadata.
   * @returns Frozen tool descriptor.
   * @example fn.asTool({ description: "Lookup", sideEffect: "read", approval: "never" });
   */
  (
    options: FunctionToolOptions<string, Input, Output>,
  ): FunctionToolView<
    `${FunctionId}.tool`,
    FunctionId,
    Input,
    Output,
    Errors,
    InputSchema,
    OutputSchema
  >;
} & ([ToolMetadata] extends [FunctionToolMetadata]
  ? {
      /** Uses metadata declared on the function.
       * @returns Frozen tool descriptor.
       * @example fn.asTool();
       */
      (): FunctionToolView<
        `${FunctionId}.tool`,
        FunctionId,
        Input,
        Output,
        Errors,
        InputSchema,
        OutputSchema
      >;
    }
  : {});
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-as-tool.types.ts#L35)

## `function-context.types.ts`

### ApplicationContextRegistry (type alias)

Application-owned additions to the handler context.

**Example**

```ts
type Registry = ApplicationContextRegistry;
```

**Signature**

```ts
type ApplicationContextRegistry = Relkit.ApplicationContextRegistry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L68)

### AuthContext (interface)

Session lookup available to a handler.

**Example**

```ts
const session = await context.auth.getSession();
```

**Signature**

```ts
export interface AuthContext<Session = unknown> {
  /** Looks up the current session.
   * @returns The session or null when unauthenticated.
   * @example const session = await context.auth.getSession();
   */
  readonly getSession: () => Promise<Session | null>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L80)

### FunctionContext (type alias)

Handler context with declared resources and optional progress.

**Example**

```ts
const run = async (_input: unknown, context: FunctionContext) => context.time.now();
```

**Signature**

```ts
type FunctionContext<
  D extends FunctionDependencies = {},
  Publishes extends readonly KnownEventName[] = readonly [],
  Progress = never,
> = FunctionContextBase<D, Publishes> &
  ([Progress] extends [never]
    ? {}
    : { readonly progress: import("@relkit/invocation").ProgressEmitter<Progress> });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L131)

### FunctionContextBase (interface)

Invocation context before optional progress is added.

**Example**

```ts
const env = context.env;
```

**Signature**

```ts
export interface FunctionContextBase<
  D extends FunctionDependencies = {},
  Publishes extends readonly KnownEventName[] = readonly [],
> {
  readonly invocation: InvocationMetadata;
  readonly signal: AbortSignal;
  readonly env: ResolvedApplicationEnv;
  readonly log: PublicLogger;
  readonly time: PublicClock;
  readonly trace: PublicTrace;
  readonly tasks: TaskClients<D["tasks"]>;
  readonly jobs: JobClients<D["jobs"]>;
  readonly events: EventClients<PublishedEventMap<Publishes>>;
  readonly buckets: BucketClients<D["buckets"]>;
  readonly cache: CacheClients<D["cache"]>;
  readonly agents: AgentClients<D["agents"]>;
  readonly database: RegisteredContext<"database", Readonly<Record<string, never>>>;
  readonly auth: RegisteredContext<"auth", AuthContext>;
  readonly constants: RegisteredContext<"constants", Readonly<Record<string, never>>>;
  readonly prompts: RegisteredContext<"prompts", Readonly<Record<string, never>>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L106)

### FunctionDependencies (interface)

Allowed resources a function may declare.

**Example**

```ts
const dependencies: FunctionDependencies = { buckets: { uploads } };
```

**Signature**

```ts
export interface FunctionDependencies {
  readonly tasks?: Readonly<Record<string, TaskRefAny>>;
  readonly jobs?: Readonly<Record<string, JobRefAny>>;
  readonly buckets?: Readonly<Record<string, BucketRefAny>>;
  readonly cache?: Readonly<Record<string, CacheRefAny>>;
  readonly agents?: Readonly<Record<string, AgentRefAny>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L21)

### FunctionDependencyOptions (type alias)

Rejects unsupported function dependency declarations.

**Example**

```ts
type Allowed = FunctionDependencyOptions<FunctionDependencies>;
```

**Signature**

```ts
type FunctionDependencyOptions<D extends FunctionDependencies> = "functions" extends keyof D
  ? never
  : D;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L91)

### InvocationMetadata (type alias)

Trace and identity metadata for one invocation.

**Example**

```ts
const metadata: InvocationMetadata = context.invocation;
```

**Signature**

```ts
type InvocationMetadata = SharedInvocationMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L36)

### InvocationSource (type alias)

Source category of a function invocation.

**Example**

```ts
const source: InvocationSource = "tool";
```

**Signature**

```ts
type InvocationSource = SharedInvocationSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L32)

### KnownEventName (type alias)

Registered event names accepted by publishes.

**Example**

```ts
type EventName = KnownEventName;
```

**Signature**

```ts
type KnownEventName = Extract<keyof Relkit.EventRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L98)

### PublicClock (type alias)

Clock exposed to application handlers.

**Example**

```ts
const clock: PublicClock = context.time;
```

**Signature**

```ts
type PublicClock = SharedPublicClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L51)

### PublicLogger (type alias)

Logger exposed to application handlers.

**Example**

```ts
const logger: PublicLogger = context.log;
```

**Signature**

```ts
type PublicLogger = SharedPublicLogger;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L47)

### PublicTrace (type alias)

Trace controls exposed to handlers.

**Example**

```ts
const trace: PublicTrace = context.trace;
```

**Signature**

```ts
type PublicTrace = SharedPublicTrace;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L55)

### ResolvedApplicationEnv (type alias)

Application environment supplied to handlers.

**Example**

```ts
const env: ResolvedApplicationEnv = context.env;
```

**Signature**

```ts
type ResolvedApplicationEnv = keyof Relkit.ApplicationEnv extends never
  ? Readonly<Record<string, unknown>>
  : Readonly<Relkit.ApplicationEnv>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-context.types.ts#L40)

## `function-dependency-copy.ts`

### copyDependencies

Copies and validates function dependencies.

**Throws**

TypeError for unsupported or malformed references.

**Example**

```ts
copyDependencies({ buckets: { uploads } });
```

**Signature**

```ts
declare const copyDependencies: <D extends FunctionDependencies>(
  dependencies: D | undefined,
) => D | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-dependency-copy.ts#L60)

### copyDependenciesEffect

Validates and freezes a dependency map through Effect.

**Example**

```ts
Effect.runSync(copyDependenciesEffect({ buckets: { uploads } }));
```

**Signature**

```ts
declare const copyDependenciesEffect: <D extends FunctionDependencies>(
  dependencies: D | undefined,
) => Effect.Effect<D | undefined, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-dependency-copy.ts#L12)

### copyPublishes

Copies and validates published event IDs.

**Throws**

TypeError for duplicate or empty IDs.

**Example**

```ts
copyPublishes(["orders.created"]);
```

**Signature**

```ts
declare const copyPublishes: <Names extends readonly string[]>(
  publishes: Names | undefined,
) => Names | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-dependency-copy.ts#L101)

### copyPublishesEffect

Validates a published event list through Effect.

**Example**

```ts
Effect.runSync(copyPublishesEffect(["orders.created"]));
```

**Signature**

```ts
declare const copyPublishesEffect: <Names extends readonly string[]>(
  publishes: Names | undefined,
) => Effect.Effect<Names | undefined, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-dependency-copy.ts#L71)

## `function-descriptor-factory.ts`

### FunctionDescriptorFactoryOptions

**Signature**

```ts
declare const FunctionDescriptorFactoryOptions: FunctionDescriptorFactoryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-factory.ts#L18)

### createFunctionDescriptor

Creates a frozen function descriptor for an authoring package.

**Throws**

TypeError for malformed schemas, hooks, limits, or dependencies.

**Example**

```ts
createFunctionDescriptor(options);
```

**Signature**

```ts
declare const createFunctionDescriptor: (options: FunctionDescriptorFactoryOptions) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-factory.ts#L78)

### createFunctionDescriptorEffect

Creates a function descriptor through Effect.

**Example**

```ts
Effect.runSync(createFunctionDescriptorEffect(options));
```

**Signature**

```ts
declare const createFunctionDescriptorEffect: (
  options: FunctionDescriptorFactoryOptions,
) => Effect.Effect<unknown, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-factory.ts#L25)

## `function-descriptor-factory.types.ts`

### FunctionDescriptorFactoryOptions (interface)

Inputs for a function descriptor shared by authoring packages.

**Example**

```ts
createFunctionDescriptor({ id: "orders.get", input, output, invocationMode: "callable", handler });
```

**Signature**

```ts
export interface FunctionDescriptorFactoryOptions extends DescriptorMetadata {
  readonly id: string;
  readonly input: StandardSchemaV1;
  readonly output: StandardSchemaV1;
  readonly progress?: StandardSchemaV1;
  readonly invocationMode: "callable" | "event-only";
  readonly handler: (...args: any[]) => unknown;
  readonly errors?: readonly ErrorDescriptorAny[];
  readonly dependencies?: FunctionDependencies;
  readonly publishes?: readonly string[];
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly tool?: FunctionToolMetadata;
  readonly onBefore?: (...args: any[]) => unknown;
  readonly onAfter?: (...args: any[]) => unknown;
  readonly descriptorFields?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-factory.types.ts#L10)

## `function-descriptor-methods.ts`

### addCallableMethods

Installs compatibility methods while the descriptor creation Effect owns mutation.

**Example**

```ts
addCallableMethods(descriptor, metadata);
```

**Signature**

```ts
declare const addCallableMethods: (
  descriptor: Record<string, any>,
  tool: FunctionToolMetadata | undefined,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-methods.ts#L128)

### asGraphNodeEffect

Derives a graph node view through Effect.

**Example**

```ts
Effect.runSync(asGraphNodeEffect(fn, fn));
```

**Signature**

```ts
declare const asGraphNodeEffect: (
  receiver: unknown,
  descriptor: FunctionRefAny,
  options?: { readonly id?: string } | undefined,
) => Effect.Effect<
  FunctionGraphNodeDescriptor<
    string,
    string,
    unknown,
    unknown,
    ReadonlyArray<ErrorDescriptorAny>,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    FunctionDependencies
  >,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-methods.ts#L106)

### asToolEffect

Derives a tool view through Effect.

**Example**

```ts
Effect.runSync(asToolEffect(fn, fn, fn.tool));
```

**Signature**

```ts
declare const asToolEffect: (
  receiver: unknown,
  descriptor: FunctionRefAny & { readonly id: string },
  tool: FunctionToolMetadata | undefined,
  options?: FunctionToolOptions<string, unknown, unknown> | undefined,
) => Effect.Effect<FunctionToolDescriptor<string, FunctionRefAny>, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-methods.ts#L66)

### invokeDescriptorEffect

Invokes a callable descriptor through the Effect dispatcher.

**Example**

```ts
Effect.runPromise(invokeDescriptorEffect(fn, fn, { id: "one" }));
```

**Signature**

```ts
declare const invokeDescriptorEffect: (
  receiver: unknown,
  descriptor: FunctionRefAny,
  input: unknown,
) => Effect.Effect<unknown, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor-methods.ts#L37)

## `function-descriptor.types.ts`

### DefineFunctionOptions (interface)

Schemas, handler, and metadata used to define a function.

**Example**

```ts
const options: DefineFunctionOptions<"orders.get", typeof input, typeof output> = {
  input,
  output,
  handler,
};
```

**Signature**

```ts
export interface DefineFunctionOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Dependencies extends FunctionDependencies = {},
  Errors extends readonly ErrorDescriptorAny[] = readonly [],
  Publishes extends readonly KnownEventName[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly errors?: Errors;
  readonly dependencies?: Dependencies;
  readonly publishes?: Publishes;
  readonly progress?: ProgressSchema;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly tool?: FunctionToolMetadata;
  readonly onBefore?: FunctionLifecycleHook<
    InferOutput<InputSchema>,
    Dependencies,
    Publishes,
    ProgressSchema
  >;
  readonly onAfter?: FunctionLifecycleHook<
    InferOutput<OutputSchema>,
    Dependencies,
    Publishes,
    ProgressSchema
  >;
  readonly handler: FunctionHandler<
    InferOutput<InputSchema>,
    InferOutput<OutputSchema>,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor.types.ts#L74)

### FunctionDescriptor (interface)

Frozen callable descriptor for a defined function.

**Example**

```ts
const descriptor: FunctionDescriptor<"orders.get", Input, Output, {}> = defineFunction(options);
```

**Signature**

```ts
export interface FunctionDescriptor<
  Id extends string,
  Input,
  Output,
  Dependencies extends FunctionDependencies,
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  ToolMetadata extends FunctionToolMetadata | undefined = undefined,
  Publishes extends readonly KnownEventName[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
>
  extends
    DescriptorBase<"function", Id>,
    FunctionRef<Id, Input, Output, Errors, InputSchema, OutputSchema> {
  readonly dependencies?: FunctionDependencyOptions<Dependencies>;
  readonly invocationMode: "callable";
  readonly publishes?: Publishes;
  readonly progress?: ProgressSchema;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly tool?: ToolMetadata;
  readonly onBefore?: FunctionLifecycleHook<Input, Dependencies, Publishes, ProgressSchema>;
  readonly onAfter?: FunctionLifecycleHook<Output, Dependencies, Publishes, ProgressSchema>;
  readonly handler: FunctionHandler<Input, Output, Dependencies, Errors, Publishes, ProgressSchema>;
  /** Invokes this function through the common runtime.
   * @param input - Value accepted by the input schema.
   * @returns Validated output, rejecting with an invocation error on failure.
   * @example await descriptor.invoke({ id: "one" });
   */
  readonly invoke: (input: InferInput<InputSchema>) => Promise<Output>;
  /** Creates a tool view when the output is not a stream.
   * @param options - Optional tool metadata overriding the declared metadata.
   * @returns A tool descriptor derived from this function.
   * @example descriptor.asTool({ description: "Lookup", sideEffect: "read", approval: "never" });
   */
  readonly asTool: OutputSchema extends StreamOutputSchema
    ? never
    : FunctionAsTool<Id, Input, Output, Errors, InputSchema, OutputSchema, ToolMetadata>;
  /** Creates a graph node view when the output is not a stream.
   * @param options - Optional graph node identity.
   * @returns A graph node descriptor derived from this function.
   * @example descriptor.asGraphNode({ id: "lookup" });
   */
  readonly asGraphNode: OutputSchema extends StreamOutputSchema
    ? never
    : FunctionAsGraphNode<Id, Input, Output, Errors, InputSchema, OutputSchema, Dependencies>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor.types.ts#L22)

### FunctionHandler (type alias)

Handler contract for a declared function.

**Example**

```ts
const handler: FunctionHandler<Input, Output, {}> = async (input) => input;
```

**Signature**

```ts
type FunctionHandler<
  Input,
  Output,
  Dependencies extends FunctionDependencies,
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
  Publishes extends readonly KnownEventName[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
> = (
  input: Input,
  context: FunctionContext<Dependencies, Publishes, ProgressValue<ProgressSchema>>,
) => MaybePromise<FunctionHandlerResult<Output, Errors>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor.types.ts#L121)

### FunctionLifecycleHook

**Signature**

```ts
declare const FunctionLifecycleHook: FunctionLifecycleHook<
  Value,
  Dependencies,
  Publishes,
  ProgressSchema
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-descriptor.types.ts#L17)

## `function-graph-node.ts`

### FunctionAsGraphNode

**Signature**

```ts
declare const FunctionAsGraphNode: FunctionAsGraphNode<
  FunctionId,
  Input,
  Output,
  Errors,
  InputSchema,
  OutputSchema,
  Dependencies
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L30)

### FunctionGraphNodeDescriptor

**Signature**

```ts
declare const FunctionGraphNodeDescriptor: FunctionGraphNodeDescriptor<
  Id,
  FunctionId,
  Input,
  Output,
  Errors,
  InputSchema,
  OutputSchema,
  Dependencies
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L31)

### FunctionGraphNodeOptions

**Signature**

```ts
declare const FunctionGraphNodeOptions: FunctionGraphNodeOptions<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L32)

### RELKIT_FUNCTION_GRAPH_NODE

Marker identifying a frozen function graph node.

**Example**

```ts
if (node[RELKIT_FUNCTION_GRAPH_NODE]) console.log(node.id);
```

**Signature**

```ts
declare const RELKIT_FUNCTION_GRAPH_NODE: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L38)

### createFunctionGraphNode

Creates a frozen graph node view of a function.

**Throws**

TypeError for invalid options or a non-callable function.

**Example**

```ts
createFunctionGraphNode(fn, fn, { id: "lookup" });
```

**Signature**

```ts
declare const createFunctionGraphNode: (
  receiver: unknown,
  fallback: FunctionRefAny,
  options?: FunctionGraphNodeOptions,
) => FunctionGraphNodeDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L130)

### createFunctionGraphNodeEffect

Creates a graph node view in the Effect error channel.

**Example**

```ts
Effect.runSync(createFunctionGraphNodeEffect(fn, fn));
```

**Signature**

```ts
declare const createFunctionGraphNodeEffect: (
  receiver: unknown,
  fallback: FunctionRefAny,
  options?: FunctionGraphNodeOptions<string> | undefined,
) => Effect.Effect<
  FunctionGraphNodeDescriptor<
    string,
    string,
    unknown,
    unknown,
    ReadonlyArray<ErrorDescriptorAny>,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    FunctionDependencies
  >,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L69)

### invokeFunctionGraphNodeEffect

Invokes the function retained by a graph node through Effect.

**Example**

```ts
Effect.runPromise(invokeFunctionGraphNodeEffect(fn, { orderId: "one" }));
```

**Signature**

```ts
declare const invokeFunctionGraphNodeEffect: (
  target: FunctionRefAny,
  input: unknown,
) => Effect.Effect<unknown, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L46)

### isFunctionGraphNode

Recognizes a function graph node.

**Example**

```ts
if (isFunctionGraphNode(value)) console.log(value.id);
```

**Signature**

```ts
declare const isFunctionGraphNode: (value: unknown) => value is FunctionGraphNodeDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L163)

### isFunctionGraphNodeEffect

Checks the shape of a graph node through Effect.

**Example**

```ts
Effect.runSync(isFunctionGraphNodeEffect(value));
```

**Signature**

```ts
declare const isFunctionGraphNodeEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.ts#L143)

## `function-graph-node.types.ts`

### FunctionAsGraphNode (type alias)

Overloads for creating a graph view with a derived or explicit ID.

**Example**

```ts
const node = fn.asGraphNode({ id: "lookup" });
```

**Signature**

```ts
type FunctionAsGraphNode<
  FunctionId extends string,
  Input,
  Output,
  Errors extends readonly ErrorDescriptorAny[],
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Dependencies extends FunctionDependencies,
> = {
  /** Creates a graph view with an explicit node ID.
   * @param options - Required stable node ID.
   * @returns Frozen graph node descriptor.
   * @example fn.asGraphNode({ id: "lookup" });
   */
  <const NodeId extends string>(
    options: FunctionGraphNodeOptions<NodeId> & { readonly id: NodeId },
  ): FunctionGraphNodeDescriptor<
    NodeId,
    FunctionId,
    Input,
    Output,
    Errors,
    InputSchema,
    OutputSchema,
    Dependencies
  >;
  /** Creates a graph view using the function ID.
   * @returns Frozen graph node descriptor.
   * @example fn.asGraphNode();
   */
  (): FunctionGraphNodeDescriptor<
    FunctionId,
    FunctionId,
    Input,
    Output,
    Errors,
    InputSchema,
    OutputSchema,
    Dependencies
  >;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.types.ts#L58)

### FunctionGraphNodeDescriptor (interface)

Frozen graph view of a callable function descriptor.

**Example**

```ts
const node: FunctionGraphNodeDescriptor = fn.asGraphNode();
```

**Signature**

```ts
export interface FunctionGraphNodeDescriptor<
  Id extends string = string,
  FunctionId extends string = string,
  Input = unknown,
  Output = unknown,
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  Dependencies extends FunctionDependencies = FunctionDependencies,
> extends DescriptorMetadata {
  readonly [RELKIT_FUNCTION_GRAPH_NODE]: true;
  readonly kind: "function-graph-node";
  readonly id: Id;
  readonly target: Ref<"function", FunctionId>;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly errors?: Errors;
  readonly dependencies?: Dependencies;
  /** Invokes the source function using services supplied when the Effect runs.
   * @param input - Value accepted by the source input schema.
   * @returns Validated output or a tagged dispatch failure.
   * @example yield* node.invokeEffect({ id: "one" });
   */
  readonly invokeEffect: (
    input: InferInput<InputSchema>,
  ) => Effect.Effect<Output, FunctionOperationError>;
  /** Invokes the source function through the common dispatcher.
   * @param input - Value accepted by the source input schema.
   * @returns Validated output or an invocation rejection.
   * @example await node.invoke({ id: "one" });
   */
  readonly invoke: (input: InferInput<InputSchema>) => Promise<Output>;
  readonly __input?: Input;
  readonly __output?: Output;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.types.ts#L19)

### FunctionGraphNodeOptions (interface)

Optional graph node identity override.

**Example**

```ts
const options: FunctionGraphNodeOptions = { id: "lookup" };
```

**Signature**

```ts
export interface FunctionGraphNodeOptions<Id extends string = string> {
  readonly id?: Id;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-graph-node.types.ts#L12)

## `function-input-error.ts`

Internal marker for an expected synchronous input failure.
It remains a TypeError for existing compatibility callers.

**Example**

```ts
throw new FunctionInputError("Invalid function input");
```

### FunctionInputError (class)

Internal marker for an expected synchronous input failure.
It remains a TypeError for existing compatibility callers.

**Example**

```ts
throw new FunctionInputError("Invalid function input");
```

**Signature**

```ts
declare class FunctionInputError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-input-error.ts#L5)

## `function-lifecycle.types.ts`

### FunctionLifecycleHook (type alias)

Hook called before or after a function invocation.

**Example**

```ts
const hook: FunctionLifecycleHook<Input, {}, []> = (value) => value;
```

**Signature**

```ts
type FunctionLifecycleHook<
  Value,
  Dependencies extends FunctionDependencies = {},
  Publishes extends readonly KnownEventName[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
> = (
  value: Value,
  context: FunctionContext<Dependencies, Publishes, ProgressValue<ProgressSchema>>,
) => MaybePromise<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-lifecycle.types.ts#L19)

### ProgressValue (type alias)

Validated progress value inferred from an optional schema.

**Example**

```ts
type Progress = ProgressValue<typeof progressSchema>;
```

**Signature**

```ts
type ProgressValue<Schema extends StandardSchemaV1 | undefined> = Schema extends StandardSchemaV1
  ? InferOutput<Schema>
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-lifecycle.types.ts#L10)

## `function-observability.ts`

### FunctionOperation

**Signature**

```ts
declare const FunctionOperation: FunctionOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L17)

### FunctionOperationError (class)

Tagged failure of a function authoring operation.

**Example**

```ts
const error = new FunctionOperationError({
  operation: "stream.create",
  cause: new TypeError("Invalid item"),
});
```

**Signature**

```ts
declare class FunctionOperationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L24)

### FunctionTelemetry (class)

Replaceable telemetry service for operation spans and metrics.

**Example**

```ts
Effect.provide(streamOfEffect(schema), FunctionTelemetryLive);
```

**Signature**

```ts
declare class FunctionTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L32)

### FunctionTelemetryLive

Default telemetry layer for function operations.

**Example**

```ts
Effect.runSync(Effect.provide(Effect.void, FunctionTelemetryLive));
```

**Signature**

```ts
declare const FunctionTelemetryLive: Layer.Layer<FunctionTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L46)

### FunctionTelemetryService

**Signature**

```ts
declare const FunctionTelemetryService: FunctionTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L18)

### functionAttempt

Evaluates a synchronous step within an already observed operation.

**Example**

```ts
yield * functionAttempt("error.define", () => validateInput(input));
```

**Signature**

```ts
declare const functionAttempt: <A>(
  operation: FunctionOperation,
  evaluate: () => A,
) => Effect.Effect<A, FunctionOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L149)

### functionTry

Maps an expected input error into the tagged channel and preserves defects.

**Example**

```ts
runFunctionSync(functionTry("stream.is-output", () => true));
```

**Signature**

```ts
declare const functionTry: <A>(
  operation: FunctionOperation,
  evaluate: () => A,
) => Effect.Effect<A, FunctionOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L136)

### observeFunction

Measures an operation using the provided telemetry service or the live observer.

**Example**

```ts
observeFunction("stream.is-output", Effect.succeed(true));
```

**Signature**

```ts
declare const observeFunction: <A, E, R>(
  operation: FunctionOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L54)

### runFunctionPromise

Executes an asynchronous compatibility adapter and restores its original error.

**Throws**

The original domain error or an unexpected defect.

**Example**

```ts
await runFunctionPromise(Effect.succeed(1));
```

**Signature**

```ts
declare const runFunctionPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L106)

### runFunctionSync

Executes a synchronous compatibility adapter and restores its original error.

**Throws**

The original validation error or an unexpected defect.

**Example**

```ts
runFunctionSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runFunctionSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.ts#L91)

## `function-observability.types.ts`

### FunctionOperation (type alias)

Fixed operation name used as a bounded telemetry label.

**Example**

```ts
const operation: FunctionOperation = "tool.invoke";
```

**Signature**

```ts
type FunctionOperation =
  | "error.define"
  | "error.create"
  | "error.is-descriptor"
  | "error.validate-http"
  | "error.assert-schema"
  | "error.is-record"
  | "function.define"
  | "function.invoke"
  | "function.invoke-target"
  | "function.as-tool"
  | "function.as-graph-node"
  | "function.create-descriptor"
  | "function.graph-node"
  | "function.graph-node-invoke"
  | "function.is-graph-node"
  | "function.fail"
  | "function.copy-dependencies"
  | "function.copy-publishes"
  | "function.validate-limit"
  | "function.assert-hook"
  | "function.assert-schema"
  | "function.target-for-receiver"
  | "stream.create"
  | "stream.validate"
  | "stream.is-output"
  | "tool.create"
  | "tool.copy-metadata"
  | "tool.invoke"
  | "tool.invoker-create"
  | "tool.is-target"
  | "tool.is-error-descriptor"
  | "tool.is-record"
  | "tool.has-own"
  | "tool.validate-side-effect"
  | "tool.validate-approval"
  | "tool.required-text"
  | "tool.positive-integer"
  | "tool.copy-hooks";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.types.ts#L6)

### FunctionTelemetryService (interface)

Substitutable observer for function authoring operations.

**Example**

```ts
const observer: FunctionTelemetryService = { observe: (_operation, effect) => effect };
```

**Signature**

```ts
export interface FunctionTelemetryService {
  /** Measures one operation while preserving the original Effect channels.
   * @param operation - Fixed operation name.
   * @param effect - Work to measure.
   * @returns Effect with the same success, error, and requirement channels.
   * @example observer.observe("tool.invoke", Effect.succeed(1));
   */
  readonly observe: <A, E, R>(
    operation: FunctionOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-observability.types.ts#L49)

## `function-ref.types.ts`

### AgentRef (interface)

Input and output schemas for an agent reference.

**Example**

```ts
const ref: AgentRef = agent;
```

**Signature**

```ts
export interface AgentRef<
  Id extends string = string,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorRef<"agent", Id> {
  readonly input: InputSchema;
  readonly output: OutputSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L62)

### AgentRefAny (type alias)

Broad agent reference for heterogeneous collections.

**Example**

```ts
const ref: AgentRefAny = agent;
```

**Signature**

```ts
type AgentRefAny = AgentRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L90)

### BucketRef (type alias)

Stable reference to a bucket.

**Example**

```ts
const ref: BucketRef = bucket;
```

**Signature**

```ts
type BucketRef<Id extends string = string> = DescriptorRef<"bucket", Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L45)

### BucketRefAny (type alias)

Broad bucket reference for heterogeneous collections.

**Example**

```ts
const ref: BucketRefAny = bucket;
```

**Signature**

```ts
type BucketRefAny = BucketRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L82)

### CacheRef (interface)

Key and value schemas for a cache reference.

**Example**

```ts
const ref: CacheRef = cache;
```

**Signature**

```ts
export interface CacheRef<
  Id extends string = string,
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorRef<"cache", Id> {
  readonly key: KeySchema;
  readonly value: ValueSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L50)

### CacheRefAny (type alias)

Broad cache reference for heterogeneous collections.

**Example**

```ts
const ref: CacheRefAny = cache;
```

**Signature**

```ts
type CacheRefAny = CacheRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L86)

### DescriptorRef (interface)

Stable reference carried by a descriptor.

**Example**

```ts
const ref: DescriptorRef<"function"> = { ref: { kind: "function", id: "orders.get" } };
```

**Signature**

```ts
export interface DescriptorRef<Kind extends DescriptorKind, Id extends string = string> {
  readonly ref: Ref<Kind, Id>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L8)

### EventRef (interface)

Schema and version view of a declared event.

**Example**

```ts
const ref: EventRef = event;
```

**Signature**

```ts
export interface EventRef<
  Id extends string = string,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorRef<"event", Id> {
  readonly version: number;
  readonly input: InputSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L34)

### EventRefAny (type alias)

Broad event reference for heterogeneous collections.

**Example**

```ts
const ref: EventRefAny = event;
```

**Signature**

```ts
type EventRefAny = EventRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L78)

### FunctionRef (interface)

Schema and identity view of a callable function.

**Example**

```ts
const ref: FunctionRef = descriptor;
```

**Signature**

```ts
export interface FunctionRef<
  Id extends string = string,
  Input = unknown,
  Output = unknown,
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends DescriptorRef<"function", Id> {
  readonly invocationMode?: "callable";
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly errors?: Errors;
  readonly __input?: Input;
  readonly __output?: Output;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L15)

### FunctionRefAny (type alias)

Broad function reference for heterogeneous collections.

**Example**

```ts
const ref: FunctionRefAny = descriptor;
```

**Signature**

```ts
type FunctionRefAny = FunctionRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-ref.types.ts#L74)

## `function-tool-approval.ts`

### resolveFunctionToolApprovalEffect

Resolves approval within the owning invocation's span and resource scope.

**Example**

```ts
yield * resolveFunctionToolApprovalEffect(request, { approval: () => true });
```

**Signature**

```ts
declare const resolveFunctionToolApprovalEffect: (
  approval: FunctionToolApprovalRequest,
  options: FunctionToolInvokeOptions,
) => Effect.Effect<
  undefined,
  | FunctionOperationError
  | FunctionToolCancelledFailure
  | FunctionToolApprovalRequiredFailure
  | FunctionToolApprovalDeniedFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-approval.ts#L20)

## `function-tool-errors.ts`

### FunctionToolApprovalDeniedError (class)

Compatibility error when a resolver denies execution.

**Example**

```ts
throw new FunctionToolApprovalDeniedError(request);
```

**Signature**

```ts
declare class FunctionToolApprovalDeniedError { constructor(readonly approval: FunctionToolApprovalRequest) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L45)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_APPROVAL_DENIED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L46)

### FunctionToolApprovalRequiredError (class)

Compatibility error when approval is required but unavailable.

**Example**

```ts
throw new FunctionToolApprovalRequiredError(request);
```

**Signature**

```ts
declare class FunctionToolApprovalRequiredError { constructor(readonly approval: FunctionToolApprovalRequest) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L33)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_APPROVAL_REQUIRED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L34)

### FunctionToolArgumentValidationError (class)

Compatibility error for malformed tool arguments.

**Example**

```ts
throw new FunctionToolArgumentValidationError([{ message: "Missing id" }]);
```

**Signature**

```ts
declare class FunctionToolArgumentValidationError {
  constructor(issues: readonly StandardIssue[]);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L7)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TOOL_ARGUMENT_VALIDATION"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L8)

### issues (property)

**Signature**

```ts
readonly issues: ReadonlyArray<StandardIssue>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L9)

### FunctionToolOperationCancelledError (class)

Compatibility cancellation error for a tool operation.

**Example**

```ts
throw new FunctionToolOperationCancelledError();
```

**Signature**

```ts
declare class FunctionToolOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L21)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-errors.ts#L22)

## `function-tool-failures.ts`

### FunctionToolApprovalDeniedFailure (class)

Tagged Effect failure when approval is denied.

**Example**

```ts
Effect.catchTag(
  invokeFunctionToolEffect(target, metadata, input),
  "FunctionToolApprovalDeniedFailure",
  () => Effect.void,
);
```

**Signature**

```ts
declare class FunctionToolApprovalDeniedFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-failures.ts#L40)

### FunctionToolApprovalRequiredFailure (class)

Tagged Effect failure when a tool needs an approval resolver.

**Example**

```ts
Effect.catchTag(
  invokeFunctionToolEffect(target, metadata, input),
  "FunctionToolApprovalRequiredFailure",
  () => Effect.void,
);
```

**Signature**

```ts
declare class FunctionToolApprovalRequiredFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-failures.ts#L25)

### FunctionToolArgumentFailure (class)

Tagged Effect failure for malformed tool arguments.

**Example**

```ts
Effect.catchTag(
  invokeFunctionToolEffect(target, metadata, input),
  "FunctionToolArgumentFailure",
  () => Effect.void,
);
```

**Signature**

```ts
declare class FunctionToolArgumentFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-failures.ts#L6)

### FunctionToolCancelledFailure (class)

Tagged Effect failure when tool execution is cancelled.

**Example**

```ts
Effect.catchTag(
  invokeFunctionToolEffect(target, metadata, input),
  "FunctionToolCancelledFailure",
  () => Effect.void,
);
```

**Signature**

```ts
declare class FunctionToolCancelledFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-failures.ts#L17)

## `function-tool-runtime.ts`

### FunctionToolApprovalDeniedError

**Signature**

```ts
declare const FunctionToolApprovalDeniedError: typeof FunctionToolApprovalDeniedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L38)

### FunctionToolApprovalDeniedFailure

**Signature**

```ts
declare const FunctionToolApprovalDeniedFailure: typeof FunctionToolApprovalDeniedFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L44)

### FunctionToolApprovalRequiredError

**Signature**

```ts
declare const FunctionToolApprovalRequiredError: typeof FunctionToolApprovalRequiredError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L39)

### FunctionToolApprovalRequiredFailure

**Signature**

```ts
declare const FunctionToolApprovalRequiredFailure: typeof FunctionToolApprovalRequiredFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L45)

### FunctionToolArgumentFailure

**Signature**

```ts
declare const FunctionToolArgumentFailure: typeof FunctionToolArgumentFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L46)

### FunctionToolArgumentValidationError

**Signature**

```ts
declare const FunctionToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L40)

### FunctionToolCancelledFailure

**Signature**

```ts
declare const FunctionToolCancelledFailure: typeof FunctionToolCancelledFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L47)

### FunctionToolOperationCancelledError

**Signature**

```ts
declare const FunctionToolOperationCancelledError: typeof FunctionToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L41)

### createFunctionToolInvoker

Creates a Promise compatibility invoker for a tool.

**Throws**

TypeError if construction metadata is invalid.

**Example**

```ts
const invoke = createFunctionToolInvoker(fn, metadata);
```

**Signature**

```ts
declare const createFunctionToolInvoker: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  identity?: object,
) => (
  input: InferInput<Target["input"]>,
  options?: FunctionToolInvokeOptions,
) => Promise<InferOutput<Target["output"]>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L151)

### createFunctionToolInvokerEffect

Creates an Effect invoker that resolves services when each call runs.

**Example**

```ts
Effect.runSync(createFunctionToolInvokerEffect(fn, metadata));
```

**Signature**

```ts
declare const createFunctionToolInvokerEffect: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  identity?: object | undefined,
) => Effect.Effect<
  (
    input: InferInput<Target["input"]>,
    options?: FunctionToolInvokeOptions,
  ) => Effect.Effect<
    InferOutput<Target["output"]>,
    | FunctionOperationError
    | FunctionToolArgumentFailure
    | FunctionToolCancelledFailure
    | FunctionToolApprovalRequiredFailure
    | FunctionToolApprovalDeniedFailure,
    SchemaValidator
  >,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L129)

### invokeFunctionToolEffect

Invokes a tool through schema validation, approval, and the Effect dispatcher.

**Example**

```ts
Effect.runPromise(
  Effect.provide(invokeFunctionToolEffect(fn, metadata, input), SchemaValidatorLive),
);
```

**Signature**

```ts
declare const invokeFunctionToolEffect: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  input: InferInput<Target["input"]>,
  options?: FunctionToolInvokeOptions | undefined,
  identity?: object | undefined,
) => Effect.Effect<
  InferOutput<Target["output"]>,
  | FunctionOperationError
  | FunctionToolArgumentFailure
  | FunctionToolCancelledFailure
  | FunctionToolApprovalRequiredFailure
  | FunctionToolApprovalDeniedFailure,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.ts#L59)

## `function-tool-runtime.types.ts`

### FunctionToolRuntimeMetadata (type alias)

Runtime policy and hooks attached to a tool invoker.

**Example**

```ts
const metadata: FunctionToolRuntimeMetadata = {
  id: "lookup",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
type FunctionToolRuntimeMetadata = Pick<
  FunctionToolMetadata,
  "sideEffect" | "approval" | "timeoutMs"
> & {
  readonly id: string;
  readonly onBefore?: FunctionToolHook;
  readonly onAfter?: FunctionToolHook;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.types.ts#L7)

### TargetSchema (type alias)

Input schema accepted by a callable function target.

**Example**

```ts
const schema: TargetSchema = target.input;
```

**Signature**

```ts
type TargetSchema = FunctionRefAny["input"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-runtime.types.ts#L19)

## `function-tool-shape.ts`

### hasOwn

Checks whether an object owns a property.

**Example**

```ts
hasOwn({ id: "one" }, "id");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L110)

### hasOwnEffect

Checks an own property through Effect.

**Example**

```ts
Effect.runSync(hasOwnEffect({}, "id"));
```

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L100)

### isErrorDescriptor

Recognizes an error descriptor accepted by tool metadata.

**Example**

```ts
isErrorDescriptor(value);
```

**Signature**

```ts
declare const isErrorDescriptor: (value: unknown) => value is ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L61)

### isErrorDescriptorEffect

Checks a declared error shape through Effect.

**Example**

```ts
Effect.runSync(isErrorDescriptorEffect(value));
```

**Signature**

```ts
declare const isErrorDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L42)

### isFunctionTarget

Recognizes a function usable as a tool target.

**Example**

```ts
if (isFunctionTarget(value)) console.log(value.ref.id);
```

**Signature**

```ts
declare const isFunctionTarget: (value: unknown) => value is FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L33)

### isFunctionTargetEffect

Checks a callable function target through Effect.

**Example**

```ts
Effect.runSync(isFunctionTargetEffect(fn));
```

**Signature**

```ts
declare const isFunctionTargetEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L12)

### isRecord

Recognizes a record-like tool value.

**Example**

```ts
isRecord({ id: "one" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L90)

### isRecordEffect

Checks a record-like value through Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({}));
```

**Signature**

```ts
declare const isRecordEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-shape.ts#L75)

## `function-tool-validation.ts`

### copyFunctionToolHooks

Copies optional tool hooks.

**Throws**

TypeError for malformed hooks.

**Example**

```ts
copyFunctionToolHooks({ onBefore: (x) => x });
```

**Signature**

```ts
declare const copyFunctionToolHooks: (
  value: unknown,
) => Pick<FunctionToolOptions, "onBefore" | "onAfter">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L148)

### copyFunctionToolHooksEffect

Copies validated tool hooks through Effect.

**Example**

```ts
Effect.runSync(copyFunctionToolHooksEffect({ onBefore: (x) => x }));
```

**Signature**

```ts
declare const copyFunctionToolHooksEffect: (
  value: unknown,
) => Effect.Effect<
  Pick<FunctionToolOptions<string, unknown, unknown>, "onBefore" | "onAfter">,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L120)

### hasOwn

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L10)

### isErrorDescriptor

**Signature**

```ts
declare const isErrorDescriptor: (value: unknown) => value is ErrorDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L10)

### isFunctionTarget

**Signature**

```ts
declare const isFunctionTarget: (value: unknown) => value is FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L10)

### isRecord

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L10)

### positiveInteger

Asserts a positive integer tool field.

**Throws**

TypeError for invalid input.

**Example**

```ts
positiveInteger(5, "timeoutMs");
```

**Signature**

```ts
declare const positiveInteger: (value: unknown, name: string) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L111)

### positiveIntegerEffect

Checks a positive integer through Effect.

**Example**

```ts
Effect.runSync(positiveIntegerEffect(5, "timeoutMs"));
```

**Signature**

```ts
declare const positiveIntegerEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<number, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L94)

### requiredText

Requires nonempty tool text.

**Throws**

TypeError for an empty value.

**Example**

```ts
requiredText(" Read order ", "description");
```

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L84)

### requiredTextEffect

Requires nonempty text through Effect.

**Example**

```ts
Effect.runSync(requiredTextEffect(" Hello ", "name"));
```

**Signature**

```ts
declare const requiredTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<string, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L68)

### validateApproval

Validates a tool approval policy.

**Throws**

TypeError for unknown values.

**Example**

```ts
validateApproval("always");
```

**Signature**

```ts
declare const validateApproval: (value: unknown) => FunctionToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L58)

### validateApprovalEffect

Validates an approval policy through Effect.

**Example**

```ts
Effect.runSync(validateApprovalEffect("always"));
```

**Signature**

```ts
declare const validateApprovalEffect: (
  value: unknown,
) => Effect.Effect<"never" | "on-write" | "always", FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L42)

### validateSideEffect

Validates a tool side effect policy.

**Throws**

TypeError for unknown values.

**Example**

```ts
validateSideEffect("read");
```

**Signature**

```ts
declare const validateSideEffect: (value: unknown) => FunctionToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L33)

### validateSideEffectEffect

Validates a side effect policy through Effect.

**Example**

```ts
Effect.runSync(validateSideEffectEffect("read"));
```

**Signature**

```ts
declare const validateSideEffectEffect: (
  value: unknown,
) => Effect.Effect<"none" | "read" | "write" | "external", FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool-validation.ts#L17)

## `function-tool.ts`

### "./function-tool.types.js" (namespace export)

Re-exports all named exports from the "./function-tool.types.js" module.

**Signature**

```ts
export * from "./function-tool.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L20)

### copyFunctionToolHooks

**Signature**

```ts
declare const copyFunctionToolHooks: (
  value: unknown,
) => Pick<FunctionToolOptions, "onBefore" | "onAfter">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L32)

### copyFunctionToolHooksEffect

**Signature**

```ts
declare const copyFunctionToolHooksEffect: (
  value: unknown,
) => Effect.Effect<
  Pick<FunctionToolOptions<string, unknown, unknown>, "onBefore" | "onAfter">,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L32)

### copyFunctionToolMetadata

Copies and validates tool metadata.

**Throws**

TypeError for invalid fields.

**Example**

```ts
copyFunctionToolMetadata({ description: "Get order", sideEffect: "read", approval: "never" });
```

**Signature**

```ts
declare const copyFunctionToolMetadata: (value: unknown) => FunctionToolMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L161)

### copyFunctionToolMetadataEffect

Copies and validates tool metadata through Effect.

**Example**

```ts
Effect.runSync(copyFunctionToolMetadataEffect(raw));
```

**Signature**

```ts
declare const copyFunctionToolMetadataEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolMetadata, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L121)

### createFunctionTool

Creates a frozen tool descriptor.

**Throws**

TypeError for malformed target or metadata.

**Example**

```ts
const tool = createFunctionTool({
  target: fn,
  description: "Get order",
  sideEffect: "read",
  approval: "never",
});
```

**Signature**

```ts
declare const createFunctionTool: <const Id extends string, const Target extends FunctionRefAny>(
  options: FunctionToolCreateOptions<Id, Target>,
) => FunctionToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L110)

### createFunctionToolEffect

Creates a tool descriptor through Effect.

**Example**

```ts
Effect.runSync(
  createFunctionToolEffect({
    target: fn,
    description: "Get order",
    sideEffect: "read",
    approval: "never",
  }),
);
```

**Signature**

```ts
declare const createFunctionToolEffect: <
  const Id extends string,
  const Target extends FunctionRefAny,
>(
  options: FunctionToolCreateOptions<Id, Target>,
) => Effect.Effect<FunctionToolDescriptor<Id, Target>, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.ts#L38)

## `function-tool.types.ts`

### FunctionToolApproval (type alias)

Approval policy applied before tool dispatch.

**Example**

```ts
const policy: FunctionToolApproval = "on-write";
```

**Signature**

```ts
type FunctionToolApproval = "never" | "on-write" | "always";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L22)

### FunctionToolApprovalDecision (type alias)

Decision returned by an approval resolver.

**Example**

```ts
const decision: FunctionToolApprovalDecision = "approved";
```

**Signature**

```ts
type FunctionToolApprovalDecision = "approved" | "denied" | boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L73)

### FunctionToolApprovalRequest (interface)

Request shown to an approval resolver.

**Example**

```ts
const request: FunctionToolApprovalRequest = {
  toolId: "orders.lookup",
  sideEffect: "read",
  policy: "always",
};
```

**Signature**

```ts
export interface FunctionToolApprovalRequest {
  readonly toolId: string;
  readonly sideEffect: FunctionToolSideEffect;
  readonly policy: FunctionToolApproval;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L65)

### FunctionToolApprovalResolver (type alias)

Callback that decides whether a tool may execute.

**Example**

```ts
const approve: FunctionToolApprovalResolver = async () => "approved";
```

**Signature**

```ts
type FunctionToolApprovalResolver = (
  approval: FunctionToolApprovalRequest,
  signal?: AbortSignal,
) => MaybePromise<FunctionToolApprovalDecision>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L80)

### FunctionToolContext (type alias)

Restricted invocation context passed to tool hooks.

**Example**

```ts
const time = context.time;
```

**Signature**

```ts
type FunctionToolContext = Pick<FunctionContext, "invocation" | "signal" | "env" | "log" | "time">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L36)

### FunctionToolCreateOptions (type alias)

Target and metadata required to construct a tool.

**Example**

```ts
const options: FunctionToolCreateOptions<"lookup", typeof fn> = {
  id: "lookup",
  target: fn,
  description: "Lookup",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
type FunctionToolCreateOptions<
  Id extends string,
  Target extends FunctionRefAny,
> = FunctionToolOptions<Id, InferInput<Target["input"]>, InferOutput<Target["output"]>> & {
  readonly id?: Id;
  readonly target: Target;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L150)

### FunctionToolDescriptor (interface)

Frozen tool descriptor with a Promise invoke adapter.

**Example**

```ts
const tool: FunctionToolDescriptor<"lookup", typeof fn> = createFunctionTool(options);
```

**Signature**

```ts
export interface FunctionToolDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
> extends DescriptorBase<"tool", Id> {
  readonly ref: { readonly kind: "tool"; readonly id: Id };
  readonly target: FunctionToolTarget<Target>;
  readonly description: string;
  readonly sideEffect: FunctionToolSideEffect;
  readonly approval: FunctionToolApproval;
  readonly timeoutMs?: number;
  readonly mcp: boolean;
  readonly onBefore?: FunctionToolHook<InferInput<Target["input"]>>;
  readonly onAfter?: FunctionToolHook<InferOutput<Target["output"]>>;
  /** Invokes the target using services supplied when the Effect runs.
   * @param input - Tool argument value.
   * @param options - Optional cancellation and approval controls.
   * @returns Validated output or a tagged tool failure.
   * @example yield* tool.invokeEffect({ id: "one" });
   */
  readonly invokeEffect: (
    input: InferInput<Target["input"]>,
    options?: FunctionToolInvokeOptions,
  ) => Effect.Effect<
    InferOutput<Target["output"]>,
    | FunctionOperationError
    | FunctionToolArgumentFailure
    | FunctionToolCancelledFailure
    | FunctionToolApprovalRequiredFailure
    | FunctionToolApprovalDeniedFailure,
    SchemaValidator
  >;
  /** Invokes the target through the common tool and function runtime.
   * @param input - Tool argument value.
   * @param options - Optional cancellation and approval controls.
   * @returns Validated output, rejecting with a tool error on failure.
   * @example await tool.invoke({ id: "one" });
   */
  readonly invoke: (
    input: InferInput<Target["input"]>,
    options?: FunctionToolInvokeOptions,
  ) => Promise<InferOutput<Target["output"]>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L105)

### FunctionToolHook (type alias)

Optional input or output transform for a tool.

**Example**

```ts
const hook: FunctionToolHook<string> = (value) => value.trim();
```

**Signature**

```ts
type FunctionToolHook<Value = unknown> = (
  value: Value,
  context: FunctionToolContext,
) => MaybePromise<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L46)

### FunctionToolInvokeOptions (interface)

Per-call signal and approval resolver.

**Example**

```ts
await tool.invoke(input, { signal: controller.signal });
```

**Signature**

```ts
export interface FunctionToolInvokeOptions {
  readonly signal?: AbortSignal;
  readonly approval?: FunctionToolApprovalResolver;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L87)

### FunctionToolMetadata (interface)

Display and policy metadata for a tool.

**Example**

```ts
const metadata: FunctionToolMetadata = {
  description: "Lookup",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
export interface FunctionToolMetadata extends DescriptorMetadata {
  readonly description: string;
  readonly sideEffect: FunctionToolSideEffect;
  readonly approval: FunctionToolApproval;
  readonly timeoutMs?: number;
  readonly mcp?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L26)

### FunctionToolOptions (interface)

Options used when creating a tool view.

**Example**

```ts
const options: FunctionToolOptions = {
  description: "Lookup",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
export interface FunctionToolOptions<
  Id extends string = string,
  Input = unknown,
  Output = unknown,
> extends FunctionToolMetadata {
  readonly id?: Id;
  readonly onBefore?: FunctionToolHook<Input>;
  readonly onAfter?: FunctionToolHook<Output>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L53)

### FunctionToolSideEffect (type alias)

Bounded side effect category for a tool.

**Example**

```ts
const effect: FunctionToolSideEffect = "read";
```

**Signature**

```ts
type FunctionToolSideEffect = "none" | "read" | "write" | "external";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L18)

### FunctionToolTarget (type alias)

Function contract copied into a tool view.

**Example**

```ts
const target: FunctionToolTarget<typeof fn> = tool.target;
```

**Signature**

```ts
type FunctionToolTarget<Target extends FunctionRefAny> = FunctionRef<
  Target["ref"]["id"],
  Target extends { readonly __input?: infer Input } ? Input : unknown,
  Target extends { readonly __output?: infer Output } ? Output : unknown,
  TargetErrors<Target>,
  Target["input"],
  Target["output"]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/function-tool.types.ts#L94)

## `handler-result.ts`

### "./handler-result.types.js" (namespace export)

Re-exports all named exports from the "./handler-result.types.js" module.

**Signature**

```ts
export * from "./handler-result.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.ts#L6)

### fail

Returns a typed application failure from a plain function handler.

**Throws**

The descriptor's validation error.

**Example**

```ts
return fail(NotFound, { id: "one" });
```

**Signature**

```ts
declare const fail: <const Descriptor extends ErrorDescriptorAny>(
  descriptor: Descriptor,
  data: Parameters<Descriptor["create"]>[0],
) => FunctionFailure<DeclaredErrorOf<Descriptor>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.ts#L35)

### failEffect

Creates a typed application failure in the Effect error channel.

**Example**

```ts
Effect.runSync(failEffect(NotFound, { id: "one" }));
```

**Signature**

```ts
declare const failEffect: <const Descriptor extends ErrorDescriptorAny>(
  descriptor: Descriptor,
  data: Parameters<Descriptor["create"]>[0],
) => Effect.Effect<
  FunctionFailure<ReturnType<Descriptor["create"]>>,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.ts#L14)

## `handler-result.types.ts`

### DeclaredErrorOf (type alias)

Instance type produced by one error descriptor.

**Example**

```ts
type NotFoundError = DeclaredErrorOf<typeof NotFound>;
```

**Signature**

```ts
type DeclaredErrorOf<Descriptor extends ErrorDescriptorAny> = ReturnType<Descriptor["create"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L27)

### DeclaredErrorsOf (type alias)

Union of instances from an error descriptor list.

**Example**

```ts
type Allowed = DeclaredErrorsOf<typeof errors>;
```

**Signature**

```ts
type DeclaredErrorsOf<Descriptors extends readonly ErrorDescriptorAny[]> =
  Descriptors[number] extends infer Descriptor
    ? Descriptor extends ErrorDescriptorAny
      ? DeclaredErrorOf<Descriptor>
      : never
    : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L34)

### FunctionEffectValue (interface)

Structural Effect type accepted from a handler.

**Example**

```ts
const result: FunctionEffectValue = Effect.succeed(output);
```

**Signature**

```ts
export interface FunctionEffectValue<Output = unknown, Error = unknown, Requirements = unknown> {
  readonly "~effect/Effect": {
    readonly _A: (_: never) => Output;
    readonly _E: (_: never) => Error;
    readonly _R: (_: never) => Requirements;
  };
  readonly pipe: (...args: never[]) => unknown;
  readonly [Symbol.iterator]: () => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L14)

### FunctionFailure (interface)

Tagged failure returned by a plain function handler.

**Example**

```ts
const failure: FunctionFailure = fail(NotFound, data);
```

**Signature**

```ts
export interface FunctionFailure<Error extends globalThis.Error = globalThis.Error> {
  readonly _tag: "FunctionFailure";
  readonly error: Error;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L6)

### FunctionHandlerResult (type alias)

Values and declared failures a handler may return.

**Example**

```ts
const result: FunctionHandlerResult<string> = "done";
```

**Signature**

```ts
type FunctionHandlerResult<
  Output,
  Errors extends readonly ErrorDescriptorAny[] = readonly ErrorDescriptorAny[],
> =
  | Output
  | DeclaredErrorsOf<Errors>
  | FunctionFailure<DeclaredErrorsOf<Errors>>
  | FunctionEffectValue<Output, DeclaredErrorsOf<Errors>, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L44)

### FunctionHandlerValidation (type alias)

Compile-time check of handler output and declared errors.

**Example**

```ts
type Valid = FunctionHandlerValidation<ReturnType<typeof handler>, Output, Errors>;
```

**Signature**

```ts
type FunctionHandlerValidation<Result, Output, Errors extends readonly ErrorDescriptorAny[]> = [
  InvalidHandlerResult<Awaited<Result>, Output, DeclaredErrorsOf<Errors>>,
] extends [never]
  ? [MissingDeclaredErrors<Result, Errors>] extends [never]
    ? {}
    : {
        readonly __relkit_handler_error__: "Return every error declared in the function's errors list";
      }
  : {
      readonly __relkit_handler_error__: "Return values and errors must match the function contract";
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/handler-result.types.ts#L116)

## `index.ts`

### "./define-error.js" (namespace export)

Re-exports all named exports from the "./define-error.js" module.

**Signature**

```ts
export * from "./define-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L1)

### "./define-function.js" (namespace export)

Re-exports all named exports from the "./define-function.js" module.

**Signature**

```ts
export * from "./define-function.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L2)

### "./function-graph-node.js" (namespace export)

Re-exports all named exports from the "./function-graph-node.js" module.

**Signature**

```ts
export * from "./function-graph-node.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L4)

### "./function-observability.js" (namespace export)

Re-exports all named exports from the "./function-observability.js" module.

**Signature**

```ts
export * from "./function-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L6)

### "./handler-result.js" (namespace export)

Re-exports all named exports from the "./handler-result.js" module.

**Signature**

```ts
export * from "./handler-result.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L3)

### "./stream.js" (namespace export)

Re-exports all named exports from the "./stream.js" module.

**Signature**

```ts
export * from "./stream.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L5)

### FunctionToolApproval

**Signature**

```ts
declare const FunctionToolApproval: FunctionToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L8)

### FunctionToolApprovalDecision

**Signature**

```ts
declare const FunctionToolApprovalDecision: FunctionToolApprovalDecision;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L9)

### FunctionToolApprovalDeniedError

**Signature**

```ts
declare const FunctionToolApprovalDeniedError: typeof FunctionToolApprovalDeniedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L26)

### FunctionToolApprovalDeniedFailure

**Signature**

```ts
declare const FunctionToolApprovalDeniedFailure: typeof FunctionToolApprovalDeniedFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L30)

### FunctionToolApprovalRequest

**Signature**

```ts
declare const FunctionToolApprovalRequest: FunctionToolApprovalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L10)

### FunctionToolApprovalRequiredError

**Signature**

```ts
declare const FunctionToolApprovalRequiredError: typeof FunctionToolApprovalRequiredError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L27)

### FunctionToolApprovalRequiredFailure

**Signature**

```ts
declare const FunctionToolApprovalRequiredFailure: typeof FunctionToolApprovalRequiredFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L31)

### FunctionToolApprovalResolver

**Signature**

```ts
declare const FunctionToolApprovalResolver: FunctionToolApprovalResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L11)

### FunctionToolArgumentFailure

**Signature**

```ts
declare const FunctionToolArgumentFailure: typeof FunctionToolArgumentFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L32)

### FunctionToolArgumentValidationError

**Signature**

```ts
declare const FunctionToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L28)

### FunctionToolCancelledFailure

**Signature**

```ts
declare const FunctionToolCancelledFailure: typeof FunctionToolCancelledFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L33)

### FunctionToolContext

**Signature**

```ts
declare const FunctionToolContext: FunctionToolContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L14)

### FunctionToolDescriptor

**Signature**

```ts
declare const FunctionToolDescriptor: FunctionToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L12)

### FunctionToolHook

**Signature**

```ts
declare const FunctionToolHook: FunctionToolHook<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L15)

### FunctionToolInvokeOptions

**Signature**

```ts
declare const FunctionToolInvokeOptions: FunctionToolInvokeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L13)

### FunctionToolMetadata

**Signature**

```ts
declare const FunctionToolMetadata: FunctionToolMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L16)

### FunctionToolOperationCancelledError

**Signature**

```ts
declare const FunctionToolOperationCancelledError: typeof FunctionToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L29)

### FunctionToolOptions

**Signature**

```ts
declare const FunctionToolOptions: FunctionToolOptions<Id, Input, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L17)

### FunctionToolSideEffect

**Signature**

```ts
declare const FunctionToolSideEffect: FunctionToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L18)

### FunctionToolTarget

**Signature**

```ts
declare const FunctionToolTarget: FunctionToolTarget<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L19)

### copyFunctionToolHooks

**Signature**

```ts
declare const copyFunctionToolHooks: (
  value: unknown,
) => Pick<FunctionToolOptions, "onBefore" | "onAfter">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L21)

### copyFunctionToolHooksEffect

**Signature**

```ts
declare const copyFunctionToolHooksEffect: (
  value: unknown,
) => Effect<
  Pick<FunctionToolOptions<string, unknown, unknown>, "onBefore" | "onAfter">,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L21)

### createFunctionToolInvoker

**Signature**

```ts
declare const createFunctionToolInvoker: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  identity?: object,
) => (
  input: InferInput<Target["input"]>,
  options?: FunctionToolInvokeOptions,
) => Promise<InferOutput<Target["output"]>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L23)

### createFunctionToolInvokerEffect

**Signature**

```ts
declare const createFunctionToolInvokerEffect: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  identity?: object | undefined,
) => Effect<
  (
    input: InferInput<Target["input"]>,
    options?: FunctionToolInvokeOptions,
  ) => Effect<
    InferOutput<Target["output"]>,
    | FunctionOperationError
    | FunctionToolArgumentFailure
    | FunctionToolCancelledFailure
    | FunctionToolApprovalRequiredFailure
    | FunctionToolApprovalDeniedFailure,
    SchemaValidator
  >,
  FunctionOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L24)

### invokeFunctionToolEffect

**Signature**

```ts
declare const invokeFunctionToolEffect: <Target extends FunctionRefAny>(
  target: Target,
  metadata: FunctionToolRuntimeMetadata,
  input: InferInput<Target["input"]>,
  options?: FunctionToolInvokeOptions | undefined,
  identity?: object | undefined,
) => Effect<
  InferOutput<Target["output"]>,
  | FunctionOperationError
  | FunctionToolArgumentFailure
  | FunctionToolCancelledFailure
  | FunctionToolApprovalRequiredFailure
  | FunctionToolApprovalDeniedFailure,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/index.ts#L25)

## `internal.ts`

### "./function-descriptor-factory.js" (namespace export)

Re-exports all named exports from the "./function-descriptor-factory.js" module.

**Signature**

```ts
export * from "./function-descriptor-factory.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/internal.ts#L1)

## `stream.ts`

### StreamOutputSchema

**Signature**

```ts
declare const StreamOutputSchema: StreamOutputSchema<ItemSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.ts#L12)

### isStreamOutputSchema

Recognizes a stream output schema.

**Example**

```ts
if (isStreamOutputSchema(value)) console.log(value.item);
```

**Signature**

```ts
declare const isStreamOutputSchema: (value: unknown) => value is StreamOutputSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.ts#L91)

### isStreamOutputSchemaEffect

Checks whether a value is a stream output schema through Effect.

**Example**

```ts
Effect.runSync(isStreamOutputSchemaEffect(value));
```

**Signature**

```ts
declare const isStreamOutputSchemaEffect: (
  value: unknown,
) => Effect.Effect<boolean, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.ts#L78)

### streamOf

Declares a validated asynchronous stream result.

**Throws**

TypeError when the item is not a Standard Schema validator.

**Example**

```ts
const output = streamOf(z.string());
```

**Signature**

```ts
declare const streamOf: <const ItemSchema extends StandardSchemaV1>(
  item: ItemSchema,
) => StreamOutputSchema<ItemSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.ts#L67)

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/orders/functions/stream-order-report.function.ts"
/** Supplies the report route with ten validated stream items, stopping when its invocation signal aborts. */
import { defineFunction, streamOf } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const streamOrderReport = defineFunction({
  input: z.object({ reportId: z.string().min(1) }),
  output: streamOf(z.object({ completed: z.number().int(), total: z.number().int() })),
  handler: async function* (_input, context) {
    for (let completed = 1; completed <= 10; completed += 1) {
      // if (completed > 1) {
      //   await Bun.sleep(1_000);
      // }
      if (context.signal.aborted) return;
      yield { completed, total: completed };
    }
  },
});

export default streamOrderReport;
```

```ts title="examples/commerce/src/routes/reports/[reportId]/route.ts"
/** Maps a report path identifier to the order stream and exposes its validated items as server-sent events. */
import { defineRoute, http } from "@relkit/app/routes";
import orders from "../../../services/orders/service.js";

export const GET = defineRoute({
  target: orders.streamOrderReport,
  request: http.input({ reportId: http.path("reportId") }),
  client: { operation: "query" },
  stream: { format: "sse" },
});
```

**Frontend**

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider. The `GET /reports/:reportId` route exposes the streaming function:

```tsx title="src/Report.tsx"
"use client";

/** Consumes the commerce report route as a cancellable typed stream inside the client provider. */
import { useRelkitClient, useStream } from "@relkit/client/react";

/** Starts one report explicitly and displays its validated progress items.
 * @returns Start/cancel controls and visible progress or stream failure. */
export function Report() {
  const { status } = useRelkitClient();
  const report = useStream("GET /reports/:reportId");

  return (
    <section>
      <button
        disabled={status !== "ready"}
        onClick={() => void report.start({ reportId: "daily" })}
      >
        Run report
      </button>
      <button onClick={() => report.cancel()}>Cancel report</button>
      <p role="status">Completed: {report.items.map((item) => item.completed).join(", ")}</p>
      {report.error && <p role="alert">{String(report.error)}</p>}
    </section>
  );
}
```

`streamOf` supplies the item type, so `report.items` exposes each item's `completed` field.
`start({ reportId })` begins the request; `cancel()` releases it. Use the domain input even when
REST places a field in the URL. Streaming operations are excluded from finite `useRoute` queries.

Reference: [`useStream`](/docs/api/client#usestream).
Continue with [stream lifecycle and failures](/docs/modules/client/streams).

### streamOfEffect

Creates a stream output schema in the Effect error channel.

**Example**

```ts
Effect.runSync(streamOfEffect(z.string()));
```

**Signature**

```ts
declare const streamOfEffect: <const ItemSchema extends StandardSchemaV1>(
  item: ItemSchema,
) => Effect.Effect<StreamOutputSchema<ItemSchema>, FunctionOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.ts#L19)

## `stream.types.ts`

### StreamOutputSchema (interface)

Standard Schema contract for an asynchronous sequence of validated items.

**Example**

```ts
const output: StreamOutputSchema = streamOf(z.string());
```

**Signature**

```ts
export interface StreamOutputSchema<
  ItemSchema extends StandardSchemaV1 = StandardSchemaV1,
> extends StandardSchemaV1<
  AsyncIterable<InferInput<ItemSchema>>,
  AsyncIterable<InferOutput<ItemSchema>>
> {
  readonly kind: "stream";
  readonly item: ItemSchema;
  readonly relkit: {
    readonly jsonSchema: () => { readonly kind: "stream"; readonly item: object };
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/stream.types.ts#L6)

## `types.ts`

### "./function-context.types.js" (namespace export)

Re-exports all named exports from the "./function-context.types.js" module.

**Signature**

```ts
export * from "./function-context.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L29)

### "./function-descriptor.types.js" (namespace export)

Re-exports all named exports from the "./function-descriptor.types.js" module.

**Signature**

```ts
export * from "./function-descriptor.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L30)

### "./function-ref.types.js" (namespace export)

Re-exports all named exports from the "./function-ref.types.js" module.

**Signature**

```ts
export * from "./function-ref.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L28)

### AgentClientFor

**Signature**

```ts
declare const AgentClientFor: AgentClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L3)

### AgentClients

**Signature**

```ts
declare const AgentClients: AgentClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L4)

### BucketClient

**Signature**

```ts
declare const BucketClient: BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L5)

### BucketClientFor

**Signature**

```ts
declare const BucketClientFor: BucketClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L6)

### BucketClients

**Signature**

```ts
declare const BucketClients: BucketClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L7)

### BucketObjectMetadata

**Signature**

```ts
declare const BucketObjectMetadata: BucketObjectMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L8)

### CacheClient

**Signature**

```ts
declare const CacheClient: CacheClient<Key, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L9)

### CacheClientFor

**Signature**

```ts
declare const CacheClientFor: CacheClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L10)

### CacheClients

**Signature**

```ts
declare const CacheClients: CacheClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L11)

### CacheOperationOptions

**Signature**

```ts
declare const CacheOperationOptions: CacheOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L12)

### EventAttributeValue

**Signature**

```ts
declare const EventAttributeValue: EventAttributeValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L15)

### EventClientFor

**Signature**

```ts
declare const EventClientFor: EventClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L13)

### EventClients

**Signature**

```ts
declare const EventClients: EventClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L14)

### EventPublishOptions

**Signature**

```ts
declare const EventPublishOptions: EventPublishOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L16)

### EventPublishResult

**Signature**

```ts
declare const EventPublishResult: EventPublishResult<Id, Version, Payload>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L17)

### JobClientFor

**Signature**

```ts
declare const JobClientFor: JobClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L19)

### JobClients

**Signature**

```ts
declare const JobClients: JobClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L20)

### JobEnqueueOptions

**Signature**

```ts
declare const JobEnqueueOptions: JobEnqueueOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L18)

### JobEnqueueResult

**Signature**

```ts
declare const JobEnqueueResult: JobEnqueueResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L21)

### JobRef

**Signature**

```ts
declare const JobRef: JobRef<Id, InputSchema, OutputSchema, Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L1)

### JobRefAny

**Signature**

```ts
declare const JobRefAny: JobRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L1)

### JobState

**Signature**

```ts
declare const JobState: JobState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L22)

### JobStatus

**Signature**

```ts
declare const JobStatus: JobStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L23)

### TaskClientFor

**Signature**

```ts
declare const TaskClientFor: TaskClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L24)

### TaskClients

**Signature**

```ts
declare const TaskClients: TaskClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L25)

### TaskRef

**Signature**

```ts
declare const TaskRef: TaskRef<Id, InputSchema, OutputSchema, Errors>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L1)

### TaskRefAny

**Signature**

```ts
declare const TaskRefAny: TaskRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L1)

### TaskTriggerOptions

**Signature**

```ts
declare const TaskTriggerOptions: TaskTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/functions/src/types.ts#L26)

## `error-retry.types.ts`

Retry policy for a declared application error.

**Example**

```ts
const retry: ErrorRetry = "later";
```

### ErrorRetry (type alias)

Retry policy for a declared application error.

**Example**

```ts
const retry: ErrorRetry = "later";
```

**Signature**

```ts
type ErrorRetry = "never" | "later";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/error-retry.types.ts#L4)

### ErrorRetryInput (type alias)

Accepted retry policy input.
Normalization validates the optional delay and freezes the result.

**Example**

```ts
const retry: ErrorRetryInput = { kind: "later", afterMs: 500 };
```

**Signature**

```ts
type ErrorRetryInput = ErrorRetry | ErrorRetryLater;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/error-retry.types.ts#L19)

### ErrorRetryLater (interface)

Delayed retry policy with an optional minimum delay.
afterMs must be a finite non-negative integer when supplied.

**Example**

```ts
const retry: ErrorRetryLater = { kind: "later", afterMs: 500 };
```

**Signature**

```ts
export interface ErrorRetryLater {
  readonly kind: "later";
  readonly afterMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/error-retry.types.ts#L10)

### NormalizedErrorRetry (interface)

Canonical immutable retry policy.
Normalization removes a delay when retry is never.

**Example**

```ts
const policy = normalizeErrorRetry("later", 500);
```

**Signature**

```ts
export interface NormalizedErrorRetry {
  readonly retry: ErrorRetry;
  readonly afterMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/error-retry.types.ts#L25)

## `identity-bind.ts`

### bindDescriptorIdentity

Synchronous canonical identity binding adapter.

**Throws**

DescriptorIdentityError or TypeError for invalid identity.

**Example**

```ts
bindDescriptorIdentity(descriptor, "tasks.run");
```

**Signature**

```ts
declare const bindDescriptorIdentity: <T extends object>(descriptor: T, id: string) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L47)

### bindDescriptorIdentityEffect

Binds a canonical descriptor identity without mutating the descriptor.

**Example**

```ts
Effect.runSync(bindDescriptorIdentityEffect(descriptor, "tasks.run"));
```

**Signature**

```ts
declare const bindDescriptorIdentityEffect: <T extends object>(
  descriptor: T,
  id: string,
) => Effect.Effect<T, import("./identity-state.js").DescriptorIdentityFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L18)

### bindDescriptorServiceMembers

Synchronous service member binding adapter.

**Throws**

DescriptorIdentityError when a member belongs to another service.

**Example**

```ts
bindDescriptorServiceMembers([member], service);
```

**Signature**

```ts
declare const bindDescriptorServiceMembers: <T extends object>(
  descriptors: readonly T[],
  service: object & DescriptorIdentitySource,
) => readonly T[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L99)

### bindDescriptorServiceMembersEffect

Associates descriptor members with one service without changing them.

**Example**

```ts
Effect.runSync(bindDescriptorServiceMembersEffect([member], service));
```

**Signature**

```ts
declare const bindDescriptorServiceMembersEffect: <T extends object>(
  descriptors: readonly T[],
  service: object & DescriptorIdentitySource,
) => Effect.Effect<ReadonlyArray<T>, DescriptorIdentityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L75)

### isDescriptorIdentityBound

Synchronous bound check adapter.

**Example**

```ts
isDescriptorIdentityBound(descriptor);
```

**Signature**

```ts
declare const isDescriptorIdentityBound: (descriptor: object) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L65)

### isDescriptorIdentityBoundEffect

Checks if a descriptor has an explicit canonical binding.

**Example**

```ts
Effect.runSync(isDescriptorIdentityBoundEffect(descriptor));
```

**Signature**

```ts
declare const isDescriptorIdentityBoundEffect: (
  descriptor: object,
) => Effect.Effect<boolean, DescriptorIdentityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/invocation/src/identity-bind.ts#L56)

---

# Standalone Inspector API
Source: https://relkit.dev/docs/api/inspector

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [inspector](/docs/modules/operations/inspector).

## Public imports

- `@relkit/inspector` — 13 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                          | Kind  | Import from         | Example                                                                                                              |
| ---------------------------------------------------------------------------- | ----- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [INSPECTOR_HELP](/docs/api/inspector#inspector_help-1)                       | Value | `@relkit/inspector` | [Module example](/docs/modules/operations/inspector)                                                                 |
| [InspectorDiscovery](/docs/api/inspector#inspectordiscovery-class)           | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/discovery-bun.test.ts#L36)     |
| [InspectorDiscoveryLive](/docs/api/inspector#inspectordiscoverylive)         | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/discovery-bun.test.ts#L18)     |
| [InspectorHistory](/docs/api/inspector#inspectorhistory-class)               | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/history-bun.test.ts#L33)       |
| [inspectorHistoryLayer](/docs/api/inspector#inspectorhistorylayer)           | Value | `@relkit/inspector` | [Module example](/docs/modules/operations/inspector)                                                                 |
| [InspectorHistoryNative](/docs/api/inspector#inspectorhistorynative-class)   | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/history-domain.test.ts#L16)    |
| [InspectorHistoryNativeLive](/docs/api/inspector#inspectorhistorynativelive) | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/history-bun.test.ts#L57)       |
| [InspectorOptions](/docs/api/inspector#inspectoroptions-interface)           | Type  | `@relkit/inspector` | [Module example](/docs/modules/operations/inspector)                                                                 |
| [InspectorRemote](/docs/api/inspector#inspectorremote-class)                 | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/backend.test.ts#L187)          |
| [InspectorRemoteLive](/docs/api/inspector#inspectorremotelive-1)             | Value | `@relkit/inspector` | [Module example](/docs/modules/operations/inspector)                                                                 |
| [InspectorTool](/docs/api/inspector#inspectortool-class)                     | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/tool-backend-logs.test.ts#L47) |
| [InspectorToolLive](/docs/api/inspector#inspectortoollive-1)                 | Value | `@relkit/inspector` | [Module example](/docs/modules/operations/inspector)                                                                 |
| [parseInspectorOptions](/docs/api/inspector#parseinspectoroptions-1)         | Value | `@relkit/inspector` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/container-policy.test.ts#L6)   |

## `backend-forward.ts`

Live operations are forwarded once; bridge rejections retain their HTTP status in the UI protocol.

### forwardBackend

Preserves native cookies, authorization, operation IDs and streaming bodies.

**Signature**

```ts
declare const forwardBackend: (
  remote: InspectorRemoteOperations,
  connection: InspectionConnectionFile,
  request: Request,
  target?: string | undefined,
) => Effect.Effect<Response, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/backend-forward.ts#L8)

## `backend-history.ts`

History queries stay in the standalone writer; no application config is executed.

### backendError

Credential-free failures retain the UI's established error protocol.

**Signature**

```ts
declare const backendError: (error: string, status: number) => Response;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/backend-history.ts#L56)

### historyResponse

Decodes only supported query/detail paths and returns their existing public protocol.

**Signature**

```ts
declare const historyResponse: (
  current: InspectorToolState,
  request: Request,
  match: RegExpExecArray,
) => Effect.Effect<Response, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/backend-history.ts#L12)

## `bin.ts`

Native standalone entry; signals interrupt and join the tool's complete resource Scope.

## `collection.schemas.ts`

Validates network records again; in-process redaction brands are never trusted across JSON.

### InspectionCollectionBatch

A finite batch has monotonic session sequence identities and optional producer attribution.

**Signature**

```ts
declare const InspectionCollectionBatch: Schema.fromJsonString<
  Schema.Struct<{
    readonly records: Schema.$Array<
      Schema.Struct<{
        readonly sequence: Schema.Number;
        readonly record: Schema.declare<ObservabilityRecord, ObservabilityRecord>;
        readonly identity: Schema.optionalKey<
          Schema.Struct<{
            readonly key: Schema.String;
            readonly origin: Schema.Literals<readonly ["application", "relkit", "inspector"]>;
          }>
        >;
      }>
    >;
    readonly gap: Schema.Boolean;
    readonly droppedRecords: Schema.Number;
    readonly incomplete: Schema.Boolean;
    readonly droppedBytes: Schema.optionalKey<Schema.Number>;
    readonly producerFailed: Schema.optionalKey<Schema.Number>;
    readonly producerDropped: Schema.optionalKey<Schema.Number>;
  }>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/collection.schemas.ts#L16)

## `collector-changes.ts`

Coalesces UI invalidations without retaining another copy of committed records.

### collectionChange

Uses existing event names so current graph/history/job views refresh after commits.

**Signature**

```ts
declare const collectionChange: (record: ObservabilityRecord) => ObservabilityStreamEventType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/collector-changes.ts#L5)

## `collector-loss.ts`

Cumulative loss has an independent durable identity, outside the saturated application's buffer.

### persistCollectionGap

Records skipped sequences, such as records retired before this Inspector read them, as loss.

**Signature**

```ts
declare const persistCollectionGap: (
  history: InspectorHistoryOperations,
  sessionId: string,
  after: number,
  next: number,
  evicted?: number | undefined,
) => Effect.Effect<void, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/collector-loss.ts#L52)

### persistCollectionLoss

One tiny transaction follows record persistence; a lost ACK reuses the same receipt key.

**Signature**

```ts
declare const persistCollectionLoss: (
  history: InspectorHistoryOperations,
  batch: {
    readonly records: ReadonlyArray<{
      readonly record: ObservabilityRecord;
      readonly sequence: number;
      readonly identity?: {
        readonly key: string;
        readonly origin: "application" | "relkit" | "inspector";
      };
    }>;
    readonly gap: boolean;
    readonly droppedRecords: number;
    readonly incomplete: boolean;
    readonly droppedBytes?: number;
    readonly producerFailed?: number;
    readonly producerDropped?: number;
  },
  sessionId: string,
  previous?: string | undefined,
) => Effect.Effect<string | undefined, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/collector-loss.ts#L8)

## `collector.ts`

Commits a finite replay batch before ACK; lost ACKs replay stable keys without duplicate writes.

### collectInspectionBatch

One bounded pull needs no independent pending queue or in-memory history copy.

**Signature**

```ts
declare const collectInspectionBatch: (
  remote: InspectorRemoteOperations,
  history: InspectorHistoryOperations,
  connection: InspectionConnectionFile,
  after: number,
  target?: string | undefined,
  previousLossKey?: string | undefined,
  previousDropped?: number | undefined,
) => Effect.Effect<
  {
    through: number;
    gap: boolean;
    droppedRecords: number;
    incomplete: boolean;
    records: number;
    lossKey: string | undefined;
    producerFailed: number;
    producerDropped: number;
    changes: Array<
      | "request.started"
      | "request.completed"
      | "log.emitted"
      | "span.started"
      | "span.updated"
      | "span.completed"
      | "job.changed"
      | "event.published"
      | "event.delivery.changed"
      | "generation.changed"
      | "diagnostic.changed"
    >;
  },
  InspectionConnectionError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/collector.ts#L23)

## `container-bin.ts`

Linux image entry requires explicit persistent mounts before acquiring the tool.

## `container-exit.ts`

A joined requested shutdown is healthy; mixed failures retain normal failure exit codes.

### inspectorContainerTeardown

**Signature**

```ts
declare const inspectorContainerTeardown: Runtime.Teardown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/container-exit.ts#L4)

## `container-native.ts`

Reads Linux mount authority only at the image's explicit native entry.

### requireInspectorContainer

**Signature**

```ts
declare const requireInspectorContainer: (
  options: InspectorOptions,
) => Effect.Effect<undefined, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/container-native.ts#L9)

## `container-policy.ts`

Restricts image execution to a private directory mount and persistent history.

### validateInspectorContainer

**Signature**

```ts
declare const validateInspectorContainer: (
  options: InspectorOptions,
  uid: number,
  mountInfo: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/container-policy.ts#L5)

## `discovery.service.ts`

Authenticates session discovery without executing project code or deleting stale metadata.

### InspectorDiscovery (class)

Captures metadata and transport authority before creating any per-tool session state.

**Signature**

```ts
declare class InspectorDiscovery
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/discovery.service.ts#L19)

### InspectorDiscoveryLive

Native discovery performs no config import, writes, installation or PID liveness probes.

**Signature**

```ts
declare const InspectorDiscoveryLive: Layer.Layer<InspectorDiscovery, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/discovery.service.ts#L33)

## `discovery.types.ts`

Discovery results keep credentials private and never select by PID or file age.

### InspectorDiscoveryOperations (interface)

Read-only discovery leaves stale and foreign descriptors untouched.

**Signature**

```ts
export interface InspectorDiscoveryOperations {
  readonly select: (
    options: InspectorOptions,
  ) => Effect.Effect<InspectorSelection, InspectionConnectionError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/discovery.types.ts#L22)

### InspectorSelection (type alias)

Only an authenticated matching handshake grants live forwarding authority.

**Signature**

```ts
type InspectorSelection =
  | { readonly state: "disconnected"; readonly rejected: number }
  | { readonly state: "ambiguous"; readonly sessions: readonly string[]; readonly rejected: number }
  | {
      readonly state: "connected";
      readonly connection: InspectionConnectionFile;
      readonly handshake: InspectionHandshake;
      readonly rejected: number;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/discovery.types.ts#L11)

## `history-binding.ts`

Binds a history directory to one project without replacing existing data or deleting locks.

### bindInspectorHistory

Publishes an immutable project marker atomically, retaining legacy history in place.

**Signature**

```ts
declare const bindInspectorHistory: (
  root: string,
  projectId: string,
) => Effect.Effect<undefined, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-binding.ts#L16)

## `history-native.service.ts`

Acquires the optional isolated writer and validates its opening receipt before exposing it.

### InspectorHistoryNative (class)

Tests substitute the complete native boundary without inheriting live process authority.

**Signature**

```ts
declare class InspectorHistoryNative
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-native.service.ts#L11)

### InspectorHistoryNativeLive

Native worker module is owned exclusively by the standalone tool.

**Signature**

```ts
declare const InspectorHistoryNativeLive: Layer.Layer<InspectorHistoryNative, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-native.service.ts#L19)

### historyNativeFailure

Retains precise native failure evidence without exposing native payloads to browser responses.

**Signature**

```ts
declare const historyNativeFailure: <Cause extends Error>(
  cause: Cause,
) => InspectionConnectionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-native.service.ts#L52)

## `history-native.types.ts`

Native history acquisition is replaceable and retains caller lifetime authority.

### InspectorHistoryNativeOperations (interface)

Owns project binding, worker open and joined physical shutdown as one acquisition.

**Signature**

```ts
export interface InspectorHistoryNativeOperations {
  readonly acquire: (
    root: string,
    projectId: string,
  ) => Effect.Effect<LocalWorkerEffects, InspectionConnectionError, Scope.Scope>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-native.types.ts#L7)

## `history-reply.ts`

Validates native IPC payloads through the shared model/query owner before exposing browser data.

### validateHistoryReply

A transport-level JSON decode alone cannot certify a worker query response.

**Signature**

```ts
declare const validateHistoryReply: (
  command: LocalWorkerCommand,
  value: Schema.Json | undefined,
) => Effect.Effect<void, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history-reply.ts#L17)

## `history.service.ts`

Owns the existing isolated DuckDB worker and preserves its transactional receipt semantics.

### InspectorHistory (class)

Persistent history opens only inside the standalone tool's Scope.

**Signature**

```ts
declare class InspectorHistory
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history.service.ts#L10)

### inspectorHistoryLayer

Supplies exactly one native writer owner for the selected project.

**Signature**

```ts
declare const inspectorHistoryLayer: (
  root: string,
  projectId: string,
) => Layer.Layer<InspectorHistory, InspectionConnectionError, InspectorHistoryNative>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history.service.ts#L49)

## `history.types.ts`

Standalone history owns the native worker; the application receives only durable ACKs.

### InspectorHistoryOperations (interface)

Serialized operations use the existing project store/schema and stable receipt keys.

**Signature**

```ts
export interface InspectorHistoryOperations {
  readonly call: (
    command: LocalWorkerCommand,
  ) => Effect.Effect<Schema.Json | undefined, InspectionConnectionError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/history.types.ts#L7)

## `index.ts`

Standalone tool entry; project inspection never evaluates application configuration.

### INSPECTOR_HELP

**Signature**

```ts
declare const INSPECTOR_HELP: "Usage: relkit-inspector [options]\n  --project-root <directory>     Discover running sessions without evaluating the project\n  --connection-file <file>       Explicitly select one private session descriptor\n  --credential-file <file>       Private descriptor supplying matching session credentials\n  --target <http-origin>         Override network routing while verifying original identity\n  --history-directory <path>     Persistent project-bound history (default .relkit/observability)\n  --hostname <host>              UI bind host (default 127.0.0.1)\n  --port <number>                UI port (default 3210)\n  --help                        Show this help\n";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L2)

### InspectorDiscovery

**Signature**

```ts
declare const InspectorDiscovery: typeof InspectorDiscovery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L4)

### InspectorDiscoveryLive

**Signature**

```ts
declare const InspectorDiscoveryLive: Layer<InspectorDiscovery, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L4)

### InspectorHistory

**Signature**

```ts
declare const InspectorHistory: typeof InspectorHistory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L7)

### InspectorHistoryNative

**Signature**

```ts
declare const InspectorHistoryNative: typeof InspectorHistoryNative;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L8)

### InspectorHistoryNativeLive

**Signature**

```ts
declare const InspectorHistoryNativeLive: Layer<InspectorHistoryNative, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L8)

### InspectorOptions

**Signature**

```ts
declare const InspectorOptions: InspectorOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L3)

### InspectorRemote

**Signature**

```ts
declare const InspectorRemote: typeof InspectorRemote;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L5)

### InspectorRemoteLive

**Signature**

```ts
declare const InspectorRemoteLive: Layer<InspectorRemote, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L5)

### InspectorTool

**Signature**

```ts
declare const InspectorTool: typeof InspectorTool;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L6)

### InspectorToolLive

**Signature**

```ts
declare const InspectorToolLive: Layer<InspectorTool, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L6)

### inspectorHistoryLayer

**Signature**

```ts
declare const inspectorHistoryLayer: (
  root: string,
  projectId: string,
) => Layer<InspectorHistory, InspectionConnectionError, InspectorHistoryNative>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L7)

### parseInspectorOptions

**Signature**

```ts
declare const parseInspectorOptions: (args: readonly string[]) => InspectorOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/index.ts#L2)

## `live-events.ts`

UI invalidations borrow the existing bounded stream, while full records stay in history.

### acquireLiveEvents

The tool Scope closes every subscriber before releasing its listener.

**Signature**

```ts
declare const acquireLiveEvents: Effect.Effect<ObservabilityStream, never, Scope>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/live-events.ts#L8)

### publishCollection

One small invalidation per signal follows the committed batch; no history copy is retained.

**Signature**

```ts
declare const publishCollection: (
  stream: ObservabilityStream,
  changes: readonly ObservabilityStreamEventType[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/live-events.ts#L45)

### publishSelection

Session/generation changes invalidate metadata without exposing session credentials.

**Signature**

```ts
declare const publishSelection: (
  stream: ObservabilityStream,
  previous: InspectorSelection,
  next: InspectorSelection,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/live-events.ts#L21)

## `options.ts`

Parses trusted tool launch flags without importing an application's config or dependencies.

### INSPECTOR_HELP

Public standalone launch help; tokens are accepted only through private files.

**Signature**

```ts
declare const INSPECTOR_HELP: "Usage: relkit-inspector [options]\n  --project-root <directory>     Discover running sessions without evaluating the project\n  --connection-file <file>       Explicitly select one private session descriptor\n  --credential-file <file>       Private descriptor supplying matching session credentials\n  --target <http-origin>         Override network routing while verifying original identity\n  --history-directory <path>     Persistent project-bound history (default .relkit/observability)\n  --hostname <host>              UI bind host (default 127.0.0.1)\n  --port <number>                UI port (default 3210)\n  --help                        Show this help\n";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/options.ts#L8)

### parseInspectorOptions

Validates all launch authority before opening a listener, history or a child.

**Signature**

```ts
declare const parseInspectorOptions: (args: readonly string[]) => InspectorOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/options.ts#L20)

## `options.types.ts`

Trusted launch inputs; none are accepted from a browser request.

### InspectorOptions (interface)

Trusted launch inputs; none are accepted from a browser request.

**Signature**

```ts
export interface InspectorOptions {
  readonly projectRoot?: string;
  readonly connectionFile?: string;
  readonly credentialFile?: string;
  readonly target?: string;
  readonly historyDirectory?: string;
  readonly hostname: string;
  readonly port: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/options.types.ts#L2)

## `remote.service.ts`

Authenticates bounded server-to-server requests without exposing app credentials to UI.

### InspectorRemote (class)

Remote transport can be replaced by a deterministic Layer in collection tests.

**Signature**

```ts
declare class InspectorRemote
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/remote.service.ts#L8)

### InspectorRemoteLive

Live request capability; acquisition opens no network connections.

**Signature**

```ts
declare const InspectorRemoteLive: Layer.Layer<InspectorRemote, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/remote.service.ts#L18)

## `remote.types.ts`

Server-only remote authority with no application module evaluation.

### InspectorRemoteOperations (interface)

Single-shot requests preserve native operation IDs; callers never retry mutations.

**Signature**

```ts
export interface InspectorRemoteOperations {
  readonly request: (
    connection: InspectionConnectionFile,
    path: string,
    options?: RequestInit,
    target?: string,
  ) => Effect.Effect<Response, InspectionConnectionError>;
  readonly json: (response: Response) => Effect.Effect<string, InspectionConnectionError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/remote.types.ts#L9)

## `tool-backend.ts`

Protects UI server requests and serves history locally while forwarding live operations once.

### inspectorBackend

The packaged Next server alone receives credentials for this local hop.

**Signature**

```ts
declare const inspectorBackend: (
  state: InspectorToolStateRef,
  remote: InspectorRemoteOperations,
  token: string,
  options: InspectorOptions,
  stream: ObservabilityStream,
) => (request: Request) => Effect.Effect<Response, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-backend.ts#L18)

## `tool-history.ts`

Keeps history acquisition attached to the tool and hides retiring writers before native cleanup.

### acquireHistory

Opens legacy project history in a parent-owned child Scope and rejects cross-project reuse.

**Signature**

```ts
declare const acquireHistory: (
  state: InspectorToolStateRef,
  files: InspectionFilesOperations,
  options: InspectorOptions,
) => Effect.Effect<undefined, InspectionConnectionError, Scope.Scope | InspectorHistoryNative>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-history.ts#L11)

### historyFailureHint

Names the remedy for a locked history database. DuckDB reports the holder's
PID; only that number is echoed, never the file path or the rest of the message.

**Signature**

```ts
declare const historyFailureHint: (error: InspectionConnectionError) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-history.ts#L69)

### recoverInspection

Recovery detaches unavailable history and its connection fence before awaiting a slow close.

**Signature**

```ts
declare const recoverInspection: (
  state: InspectorToolStateRef,
  error: InspectionConnectionError,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-history.ts#L46)

## `tool-loop.ts`

Serializes bounded discovery, recovery and collection independently from application requests.

### inspectionLoop

Only one poll/batch can be pending; support failure uses a finite recovery interval.

**Signature**

```ts
declare const inspectionLoop: (
  state: InspectorToolStateRef,
  discovery: InspectorDiscoveryOperations,
  remote: InspectorRemoteOperations,
  files: InspectionFilesOperations,
  options: InspectorOptions,
  stream: ObservabilityStream,
) => Effect.Effect<never, InspectionConnectionError, Scope | InspectorHistoryNative>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-loop.ts#L19)

## `tool-main.ts`

Shares the native signal owner between package and restricted container entries.

### runInspectorMain

**Signature**

```ts
declare const runInspectorMain: (container: boolean) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-main.ts#L18)

## `tool-state.types.ts`

Tool-owned projection; browser responses must select safe fields instead of serializing it.

### InspectorHistoryOwner (interface)

One native writer and its child Scope survive app generation/session changes.

**Signature**

```ts
export interface InspectorHistoryOwner {
  readonly projectId: string;
  readonly scope: Scope.Closeable;
  readonly operations: InspectorHistoryOperations;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-state.types.ts#L7)

### InspectorToolState (interface)

Collection state contains only one finite batch at a time; no pending write queue.

**Signature**

```ts
export interface InspectorToolState {
  readonly selection: InspectorSelection;
  readonly history: InspectorHistoryOwner | undefined;
  readonly sessionId: string | undefined;
  readonly through: number;
  readonly error: string | undefined;
  readonly incomplete: boolean;
  readonly droppedRecords: number;
  readonly lossKey?: string | undefined;
  readonly producerFailed?: number | undefined;
  readonly producerDropped?: number | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-state.types.ts#L14)

### InspectorToolStateRef (type alias)

Shared projection is owned by the acquired tool, never module global.

**Signature**

```ts
type InspectorToolStateRef = Ref.Ref<InspectorToolState>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool-state.types.ts#L28)

## `tool.service.ts`

Composes standalone UI, collector, private discovery and a single project history writer.

### InspectorTool (class)

Native authority is captured once; every run owns an independent tool Scope.

**Signature**

```ts
declare class InspectorTool
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool.service.ts#L22)

### InspectorToolLive

Live command composition; no app compiler, evaluator or native feature SDK is included.

**Signature**

```ts
declare const InspectorToolLive: Layer.Layer<InspectorTool, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/tool.service.ts#L43)

## `ui-native.service.ts`

Owns the packaged Node UI child without inheriting application environment values.

### InspectorUiNative (class)

Native UI acquisition is separate from all application/session ownership.

**Signature**

```ts
declare class InspectorUiNative
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/ui-native.service.ts#L12)

### InspectorUiNativeLive

Live child adapter, acquired only by an explicit standalone launch.

**Signature**

```ts
declare const InspectorUiNativeLive: Layer.Layer<InspectorUiNative, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/ui-native.service.ts#L28)

### acquireInspectorUi

Runs the exact packaged UI and joins its process on tool exit.

**Signature**

```ts
declare const acquireInspectorUi: (
  entry: string,
  options: InspectorOptions,
  backend: string,
  token: string,
) => Effect.Effect<
  Effect.Effect<never, InspectionConnectionError, never>,
  InspectionConnectionError,
  Scope
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/ui-native.service.ts#L31)

## `ui-readiness.ts`

Requires complete UI response bytes and joins cancellation before advertising listening.

### probeInspectorUi

Fetch cancellation reaches both headers and body; an oversized UI reply is never ready.

**Signature**

```ts
declare const probeInspectorUi: (
  fetcher: typeof fetch,
  endpoint: string,
) => Effect.Effect<boolean, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/ui-readiness.ts#L16)

### waitInspectorUiReady

The caller supplies native authority; expected connection failures retry within one minute.

**Signature**

```ts
declare const waitInspectorUiReady: (
  probe: Effect.Effect<boolean, InspectionConnectionError>,
) => Effect.Effect<boolean, InspectionConnectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/inspector/src/ui-readiness.ts#L6)

---

# AWS API
Source: https://relkit.dev/docs/api/integrations/aws

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [aws](/docs/api/integrations/aws#aws)

For configuration and examples, read [deployment](/docs/modules/deployment), [aws](/docs/modules/deployment/aws).

## Public imports

- `@relkit/aws` — 5 exports
- `@relkit/aws/host` — 2 exports
- `@relkit/aws/infrastructure` — 2 exports
- `@relkit/aws/access` — 2 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                         | Kind  | Import from                  | Example                                                                                                    |
| --------------------------------------------------------------------------- | ----- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [aws](/docs/api/integrations/aws#aws)                                       | Value | `@relkit/aws`                | [API example](/docs/api/integrations/aws#aws)                                                              |
| [awsAccess](/docs/api/integrations/aws#awsaccess)                           | Value | `@relkit/aws/access`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/grouped-pulumi.probe.ts#L40) |
| [AwsAdapter](/docs/api/integrations/aws#awsadapter-type-alias)              | Type  | `@relkit/aws`                | [Module example](/docs/modules/deployment)                                                                 |
| [awsHost](/docs/api/integrations/aws#awshost)                               | Value | `@relkit/aws/host`           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L45) |
| [awsInfrastructure](/docs/api/integrations/aws#awsinfrastructure)           | Value | `@relkit/aws/infrastructure` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/grouped-pulumi.probe.ts#L40) |
| [AwsOptions](/docs/api/integrations/aws#awsoptions-type-alias)              | Type  | `@relkit/aws`                | [Module example](/docs/modules/deployment)                                                                 |
| [AwsRedisOptions](/docs/api/integrations/aws#awsredisoptions-interface)     | Type  | `@relkit/aws`                | [Module example](/docs/modules/deployment)                                                                 |
| [AwsS3Options](/docs/api/integrations/aws#awss3options-interface)           | Type  | `@relkit/aws`                | [Module example](/docs/modules/deployment)                                                                 |
| [deploymentIntegration](/docs/api/integrations/aws#deploymentintegration-1) | Value | `@relkit/aws/host`           | [Module example](/docs/modules/deployment)                                                                 |
| [deploymentIntegration](/docs/api/integrations/aws#deploymentintegration-2) | Value | `@relkit/aws/infrastructure` | [Module example](/docs/modules/deployment)                                                                 |
| [deploymentIntegration](/docs/api/integrations/aws#deploymentintegration)   | Value | `@relkit/aws/access`         | [Module example](/docs/modules/deployment)                                                                 |

## `index.ts`

### awsAccess

**Signature**

```ts
declare const awsAccess: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "access";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
    readonly operation: AccessOperationPlan;
    readonly host: DeploymentHostMaterialization;
    readonly infrastructure: DeploymentInfrastructureMaterialization;
  }) => DeploymentAccessMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/access/index.ts#L7)

### deploymentIntegration

**Signature**

```ts
declare const deploymentIntegration: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "access";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
    readonly operation: AccessOperationPlan;
    readonly host: DeploymentHostMaterialization;
    readonly infrastructure: DeploymentInfrastructureMaterialization;
  }) => DeploymentAccessMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/access/index.ts#L15)

## `materialize.ts`

### materializeAwsAccess

**Signature**

```ts
declare const materializeAwsAccess: (input: {
  readonly plan: DeploymentPlan;
  readonly stackName: string;
  readonly operation: AccessOperationPlan;
  readonly host: DeploymentHostMaterialization;
  readonly infrastructure: DeploymentInfrastructureMaterialization;
}) => DeploymentAccessMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/access/materialize.ts#L8)

## `aws.ts`

### aws

Provisions a supported S3 or Redis adapter on AWS and grants only its workload access.

**Example**

```ts
import { aws } from "@relkit/aws";
import { s3 } from "@relkit/s3";
const receipts = aws(s3(), { versioning: true });
```

**Signature**

```ts
declare const aws: <const Adapter extends AwsAdapter>(
  adapter: Adapter,
  options?: AwsOptions<Adapter>,
) => InfrastructureProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/aws.ts#L43)

Since v0.2.0

### AwsAdapter (type alias)

**Signature**

```ts
type AwsAdapter = S3Adapter | RedisAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/aws.ts#L12)

### AwsOptions (type alias)

**Signature**

```ts
type AwsOptions<Adapter extends AwsAdapter> = Adapter extends S3Adapter
  ? AwsS3Options
  : AwsRedisOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/aws.ts#L25)

### AwsRedisOptions (interface)

**Signature**

```ts
export interface AwsRedisOptions {
  readonly engine?: "valkey" | "redis";
  readonly nodeType?: string;
  readonly replicas?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/aws.ts#L19)

### AwsS3Options (interface)

**Signature**

```ts
export interface AwsS3Options {
  readonly versioning?: boolean;
  readonly forceDestroy?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/aws.ts#L14)

## `environment.ts`

### containerEnvironment

**Signature**

```ts
declare const containerEnvironment: (
  plan: DeploymentPlan,
) => readonly Readonly<{ name: string; value: DeploymentInput }>[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/environment.ts#L9)

## `index.ts`

### awsHost

**Signature**

```ts
declare const awsHost: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "host";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
  }) => DeploymentHostMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/index.ts#L7)

### deploymentIntegration

**Signature**

```ts
declare const deploymentIntegration: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "host";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
  }) => DeploymentHostMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/index.ts#L15)

## `materialize.ts`

### materializeAwsHost

**Signature**

```ts
declare const materializeAwsHost: (input: {
  readonly plan: DeploymentPlan;
  readonly stackName: string;
}) => DeploymentHostMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/materialize.ts#L6)

## `network.ts`

### network

**Signature**

```ts
declare const network: (
  context: HostContext,
) => Pick<DeploymentHostMaterialization, "resources" | "network">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/network.ts#L4)

## `service-support.ts`

### container

**Signature**

```ts
declare const container: (context: HostContext) => Readonly<Record<string, DeploymentInput>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/service-support.ts#L30)

### role

**Signature**

```ts
declare const role: (context: HostContext, id: string) => DeploymentResourceOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/service-support.ts#L20)

## `service.ts`

### service

**Signature**

```ts
declare const service: (
  context: HostContext,
  network: DeploymentHostMaterialization["network"],
) => Pick<DeploymentHostMaterialization, "resources" | "workload" | "outputs">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/service.ts#L12)

## `shared.ts`

### HostContext (interface)

**Signature**

```ts
export interface HostContext {
  readonly plan: DeploymentPlan;
  readonly stackName: string;
  readonly prefix: string;
  readonly tags: Readonly<Record<string, string>>;
  readonly region: DeploymentInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L9)

### hostContext

**Signature**

```ts
declare const hostContext: (plan: DeploymentPlan, stackName: string) => HostContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L17)

### hostId

**Signature**

```ts
declare const hostId: (id: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L52)

### name

**Signature**

```ts
declare const name: (value: string, max?: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L60)

### output

**Signature**

```ts
declare const output: (id: string, property: string) => DeploymentInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L56)

### resource

**Signature**

```ts
declare const resource: (
  context: HostContext,
  id: string,
  type: string,
  inputs: Readonly<Record<string, DeploymentInput>>,
  outputs?: readonly string[],
  dependsOn?: readonly string[],
) => DeploymentResourceOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/host/shared.ts#L33)

## `index.ts`

### "./aws.js" (namespace export)

Re-exports all named exports from the "./aws.js" module.

**Signature**

```ts
export * from "./aws.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/index.ts#L1)

## `index.ts`

### awsInfrastructure

**Signature**

```ts
declare const awsInfrastructure: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "infrastructure";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
    readonly operation: InfrastructureOperationPlan;
    readonly host: DeploymentHostMaterialization;
  }) => DeploymentInfrastructureMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/index.ts#L7)

### deploymentIntegration

**Signature**

```ts
declare const deploymentIntegration: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "aws";
  role: "infrastructure";
  materialize: (input: {
    readonly plan: DeploymentPlan;
    readonly stackName: string;
    readonly operation: InfrastructureOperationPlan;
    readonly host: DeploymentHostMaterialization;
  }) => DeploymentInfrastructureMaterialization;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/index.ts#L15)

## `materialize.ts`

### materializeAwsInfrastructure

**Signature**

```ts
declare const materializeAwsInfrastructure: (input: {
  readonly plan: DeploymentPlan;
  readonly stackName: string;
  readonly operation: InfrastructureOperationPlan;
  readonly host: DeploymentHostMaterialization;
}) => DeploymentInfrastructureMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/materialize.ts#L5)

## `redis.ts`

### materializeRedis

**Signature**

```ts
declare const materializeRedis: (
  plan: DeploymentPlan,
  stackName: string,
  operation: InfrastructureOperationPlan,
  host: DeploymentHostMaterialization,
) => DeploymentInfrastructureMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/redis.ts#L10)

## `s3.ts`

### materializeS3

**Signature**

```ts
declare const materializeS3: (
  plan: DeploymentPlan,
  stackName: string,
  operation: InfrastructureOperationPlan,
) => DeploymentInfrastructureMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/s3.ts#L9)

## `shared.ts`

### InfrastructureContext (interface)

**Signature**

```ts
export interface InfrastructureContext {
  readonly stackName: string;
  readonly operation: InfrastructureOperationPlan;
  readonly prefix: string;
  readonly tags: Readonly<Record<string, string>>;
  readonly region: DeploymentInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L9)

### assertAdapter

**Signature**

```ts
declare const assertAdapter: (
  operation: InfrastructureOperationPlan,
  capability: string,
  adapterId: string,
  features: readonly string[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L79)

### context

**Signature**

```ts
declare const context: (
  appId: string,
  graphHash: string,
  stackName: string,
  operation: InfrastructureOperationPlan,
) => InfrastructureContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L17)

### id

**Signature**

```ts
declare const id: (context: InfrastructureContext, suffix: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L57)

### name

**Signature**

```ts
declare const name: (value: string, max?: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L61)

### output

**Signature**

```ts
declare const output: (
  context: InfrastructureContext,
  suffix: string,
  property: string,
) => DeploymentInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L49)

### resource

**Signature**

```ts
declare const resource: (
  context: InfrastructureContext,
  suffix: string,
  type: string,
  inputs: Readonly<Record<string, DeploymentInput>>,
  outputs?: readonly string[],
) => DeploymentResourceOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L32)

### settings

**Signature**

```ts
declare const settings: (value: unknown) => Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/aws/src/infrastructure/shared.ts#L73)

---

# Integration catalog API
Source: https://relkit.dev/docs/api/integrations/catalog

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [integrations](/docs/modules/integrations).

## Public imports

- `@relkit/integrations` — 0 exports

This package contains integration metadata. Its JavaScript entrypoint exports no runtime APIs; install each selected integration separately.

## `index.ts`

---

# Cloudflare API
Source: https://relkit.dev/docs/api/integrations/cloudflare

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [integrations](/docs/modules/integrations), [providers](/docs/modules/deployment/providers).

## Public imports

- `@relkit/cloudflare` — 6 exports
- `@relkit/cloudflare/runtime` — 6 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                    | Kind  | Import from                  | Example                                                                                                  |
| ------------------------------------------------------------------------------------------------------ | ----- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| [CloudflareKvAdapter](/docs/api/integrations/cloudflare#cloudflarekvadapter-type-alias)                | Type  | `@relkit/cloudflare`         | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareKvCacheOptions](/docs/api/integrations/cloudflare#cloudflarekvcacheoptions-interface)       | Type  | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareKvCacheProvider](/docs/api/integrations/cloudflare#cloudflarekvcacheprovider-interface)     | Type  | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareKvOptions](/docs/api/integrations/cloudflare#cloudflarekvoptions-interface)                 | Type  | `@relkit/cloudflare`         | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareR2Adapter](/docs/api/integrations/cloudflare#cloudflarer2adapter-type-alias)                | Type  | `@relkit/cloudflare`         | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareR2BucketOptions](/docs/api/integrations/cloudflare#cloudflarer2bucketoptions-interface)     | Type  | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |
| [CloudflareR2Options](/docs/api/integrations/cloudflare#cloudflarer2options-interface)                 | Type  | `@relkit/cloudflare`         | [Module example](/docs/modules/integrations)                                                             |
| [createCloudflareKvCacheProvider](/docs/api/integrations/cloudflare#createcloudflarekvcacheprovider)   | Value | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |
| [createCloudflareR2BucketProvider](/docs/api/integrations/cloudflare#createcloudflarer2bucketprovider) | Value | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |
| [kv](/docs/api/integrations/cloudflare#kv)                                                             | Value | `@relkit/cloudflare`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/cloudflare.ts#L18) |
| [r2](/docs/api/integrations/cloudflare#r2)                                                             | Value | `@relkit/cloudflare`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/cloudflare.ts#L8)  |
| [runtimeIntegration](/docs/api/integrations/cloudflare#runtimeintegration)                             | Value | `@relkit/cloudflare/runtime` | [Module example](/docs/modules/integrations)                                                             |

## `cloudflare.ts`

### kv

Defines a connected Cloudflare Workers KV cache.

**Signature**

```ts
declare const kv: (options: CloudflareKvOptions) => CloudflareKvAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L71)

Since v0.2.0

### r2

Defines a connected Cloudflare R2 bucket through its S3-compatible API.

**Signature**

```ts
declare const r2: (options: CloudflareR2Options) => CloudflareR2Adapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L96)

Since v0.2.0

### CloudflareKvAdapter (type alias)

**Signature**

```ts
type CloudflareKvAdapter = ProviderAdapter<
  typeof cache,
  "cloudflare-kv",
  ProviderConnectionValues,
  ProviderBehavior<Readonly<{ minimumTtlMs: 60_000 }>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L52)

### CloudflareKvOptions (interface)

**Signature**

```ts
export interface CloudflareKvOptions {
  readonly accountId: TextValue;
  readonly namespaceId: TextValue;
  readonly apiToken: SecretReference;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L36)

### CloudflareR2Adapter (type alias)

**Signature**

```ts
type CloudflareR2Adapter = ProviderAdapter<
  typeof bucket,
  "cloudflare-r2",
  ProviderConnectionValues,
  ProviderBehavior<Readonly<{ signedUrlTtlSeconds: number }>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L59)

### CloudflareR2Options (interface)

**Signature**

```ts
export interface CloudflareR2Options {
  readonly accountId: TextValue;
  readonly bucketName: TextValue;
  readonly credentials: Readonly<{
    accessKeyId: SecretReference;
    secretAccessKey: SecretReference;
  }>;
  readonly signedUrlTtlSeconds?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/cloudflare.ts#L42)

## `index.ts`

### "./cloudflare.js" (namespace export)

Re-exports all named exports from the "./cloudflare.js" module.

**Signature**

```ts
export * from "./cloudflare.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/index.ts#L1)

## `index.ts`

### "./kv.js" (namespace export)

Re-exports all named exports from the "./kv.js" module.

**Signature**

```ts
export * from "./kv.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/index.ts#L5)

### "./r2.js" (namespace export)

Re-exports all named exports from the "./r2.js" module.

**Signature**

```ts
export * from "./r2.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/index.ts#L6)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "cloudflare";
  registrations: ReadonlyArray<
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ connection, behavior }: RuntimeProviderContext) => { value: BucketProvider };
      }
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection }: RuntimeProviderContext) => {
          value: CloudflareKvCacheProvider;
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/index.ts#L8)

## `kv.ts`

### CloudflareKvCacheOptions (interface)

**Signature**

```ts
export interface CloudflareKvCacheOptions {
  readonly accountId: string;
  readonly namespaceId: string;
  readonly apiToken: string;
  readonly cacheId: string;
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/kv.ts#L4)

### CloudflareKvCacheProvider (interface)

**Signature**

```ts
export interface CloudflareKvCacheProvider extends CacheProvider {
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/kv.ts#L12)

### createCloudflareKvCacheProvider

**Signature**

```ts
declare const createCloudflareKvCacheProvider: (
  options: CloudflareKvCacheOptions,
) => CloudflareKvCacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/kv.ts#L17)

## `r2-signing.ts`

### R2Credentials (interface)

**Signature**

```ts
export interface R2Credentials {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2-signing.ts#L1)

### R2RequestInit (type alias)

**Signature**

```ts
type R2RequestInit = Omit<RequestInit, "body"> & {
  readonly body?: string | Uint8Array | null;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2-signing.ts#L6)

### assertR2Response

**Signature**

```ts
declare const assertR2Response: (response: Response, operation: string) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2-signing.ts#L57)

### presignR2Url

**Signature**

```ts
declare const presignR2Url: (
  url: string,
  method: "GET" | "PUT",
  credentials: R2Credentials,
  expiresSeconds: number,
) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2-signing.ts#L27)

### signedR2Request

**Signature**

```ts
declare const signedR2Request: (
  url: string,
  credentials: R2Credentials,
  init?: R2RequestInit,
  fetcher?: typeof globalThis.fetch,
) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2-signing.ts#L10)

## `r2.ts`

### CloudflareR2BucketOptions (interface)

**Signature**

```ts
export interface CloudflareR2BucketOptions extends R2Credentials {
  readonly accountId: string;
  readonly bucketName: string;
  readonly signedUrlTtlSeconds?: number;
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2.ts#L10)

### createCloudflareR2BucketProvider

**Signature**

```ts
declare const createCloudflareR2BucketProvider: (
  options: CloudflareR2BucketOptions,
) => BucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/cloudflare/src/runtime/r2.ts#L17)

---

# Docker API
Source: https://relkit.dev/docs/api/integrations/docker

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [docker](/docs/api/integrations/docker#docker)

For configuration and examples, read [bindings](/docs/modules/jobs/bindings), [docker](/docs/modules/jobs/docker), [integrations](/docs/modules/integrations).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images), [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/docker` — 1 exports
- `@relkit/docker/runtime` — 16 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                     | Kind  | Import from              | Example                                                                                                             |
| --------------------------------------------------------------------------------------- | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| [createDockerClient](/docs/api/integrations/docker#createdockerclient)                  | Value | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L36)  |
| [createDockerMaterializer](/docs/api/integrations/docker#createdockermaterializer)      | Value | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L37)  |
| [docker](/docs/api/integrations/docker#docker)                                          | Value | `@relkit/docker`         | [API example](/docs/api/integrations/docker#docker)                                                                 |
| [DockerClient](/docs/api/integrations/docker#dockerclient-interface)                    | Type  | `@relkit/docker/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L170) |
| [DockerClientOptions](/docs/api/integrations/docker#dockerclientoptions-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandOptions](/docs/api/integrations/docker#dockercommandoptions-interface)    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandRequest](/docs/api/integrations/docker#dockercommandrequest-interface)    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandResult](/docs/api/integrations/docker#dockercommandresult-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerCommandRunner](/docs/api/integrations/docker#dockercommandrunner-type-alias)     | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerContainer](/docs/api/integrations/docker#dockercontainer-interface)              | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineError](/docs/api/integrations/docker#dockerengineerror-class)              | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineErrorCode](/docs/api/integrations/docker#dockerengineerrorcode-type-alias) | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerEngineInfo](/docs/api/integrations/docker#dockerengineinfo-interface)            | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerHealthOptions](/docs/api/integrations/docker#dockerhealthoptions-interface)      | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [dockerMaterializer](/docs/api/integrations/docker#dockermaterializer)                  | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [DockerVolume](/docs/api/integrations/docker#dockervolume-interface)                    | Type  | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |
| [randomLoopbackPort](/docs/api/integrations/docker#randomloopbackport-1)                | Value | `@relkit/docker/runtime` | [Module example](/docs/modules/jobs/bindings)                                                                       |

## `index.ts`

### docker

Selects an adapter's declared local recipe without contacting Docker.

**Example**

```ts
import { docker } from "@relkit/docker";
import { redis } from "@relkit/redis";

const cache = docker(redis());
```

**Signature**

```ts
declare const docker: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/index.ts#L20)

Since v0.2.0

## `docker-client.ts`

### createDockerClient

**Signature**

```ts
declare const createDockerClient: (options?: DockerClientOptions) => DockerClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-client.ts#L25)

### randomLoopbackPort

**Signature**

```ts
declare const randomLoopbackPort: (containerPort: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-client.ts#L177)

## `docker-composite-support.ts`

### argument

**Signature**

```ts
declare const argument: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L82)

### bindMountArguments

**Signature**

```ts
declare const bindMountArguments: (
  mounts: readonly LocalServiceBindMount[] | undefined,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L65)

### compositeLabels

**Signature**

```ts
declare const compositeLabels: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L24)

### compositeSignal

**Signature**

```ts
declare const compositeSignal: (request: LocalServiceStartRequest) => {
  readonly signal?: AbortSignal;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L48)

### environmentArguments

**Signature**

```ts
declare const environmentArguments: (
  values: Readonly<Record<string, string>> | undefined,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L87)

### healthArgs

**Signature**

```ts
declare const healthArgs: (
  command: readonly string[],
  interval: number,
  timeout: number,
  retries: number,
) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L30)

### inspectNetwork

**Signature**

```ts
declare const inspectNetwork: (
  client: DockerClient,
  networkName: string,
  request: LocalServiceStartRequest,
) => Promise<Readonly<Record<string, string>> | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L106)

### mountPath

**Signature**

```ts
declare const mountPath: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L59)

### owned

**Signature**

```ts
declare const owned: (
  actual: Readonly<Record<string, string>>,
  expected: Readonly<Record<string, string>>,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L129)

### positive

**Signature**

```ts
declare const positive: (value: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L100)

### resourceName

**Signature**

```ts
declare const resourceName: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L54)

### volumeNames

**Signature**

```ts
declare const volumeNames: (
  serviceName: string,
  requested: Readonly<Record<string, string>> | undefined,
  recipe: NormalizedLocalServiceRecipe,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-support.ts#L8)

## `docker-composite-unit.ts`

### reusedUnit

**Signature**

```ts
declare const reusedUnit: (
  existing: LocalServiceInstance,
  unit: NormalizedLocalServiceUnit,
  serviceName: string,
) => LocalServiceInstance;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-unit.ts#L20)

### startUnit

**Signature**

```ts
declare const startUnit: (
  client: DockerClient,
  request: LocalServiceStartRequest,
  recipe: NormalizedLocalServiceRecipe,
  unit: NormalizedLocalServiceUnit,
  networkName: string,
  volumes: Readonly<Record<string, string>>,
  gatewayAddress?: string,
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite-unit.ts#L44)

## `docker-composite.ts`

### startComposite

**Signature**

```ts
declare const startComposite: (
  client: DockerClient,
  request: LocalServiceStartRequest,
  gatewayAddress?: string,
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-composite.ts#L26)

## `docker-health.ts`

### healthTimeout

**Signature**

```ts
declare const healthTimeout: (id: string) => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L72)

### publishedPortArguments

**Signature**

```ts
declare const publishedPortArguments: (
  containerPort: number,
  gatewayAddress?: string,
  hostPort?: number,
) => Promise<string[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L14)

### randomLoopbackPort

**Signature**

```ts
declare const randomLoopbackPort: (containerPort: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L4)

### wait

**Signature**

```ts
declare const wait: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-health.ts#L79)

## `docker-inspect.ts`

### parseContainers

**Signature**

```ts
declare const parseContainers: (source: string) => readonly DockerContainer[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-inspect.ts#L4)

### parseVolumes

**Signature**

```ts
declare const parseVolumes: (source: string) => readonly DockerVolume[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-inspect.ts#L31)

## `docker-materializer-support.ts`

### argument

**Signature**

```ts
declare const argument: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L54)

### duration

**Signature**

```ts
declare const duration: (value: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L45)

### healthCommand

**Signature**

```ts
declare const healthCommand: (values: readonly string[]) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L23)

### labelArguments

**Signature**

```ts
declare const labelArguments: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L1)

### labelKey

**Signature**

```ts
declare const labelKey: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L18)

### labels

**Signature**

```ts
declare const labels: (values: Readonly<Record<string, string>>) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L13)

### mountPath

**Signature**

```ts
declare const mountPath: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L40)

### name

**Signature**

```ts
declare const name: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L35)

### networkLabelFilters

**Signature**

```ts
declare const networkLabelFilters: (values: Readonly<Record<string, string>>) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L7)

### positive

**Signature**

```ts
declare const positive: (value: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L49)

### resourceName

**Signature**

```ts
declare const resourceName: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer-support.ts#L30)

## `docker-materializer.ts`

### createDockerMaterializer

**Signature**

```ts
declare const createDockerMaterializer: (
  options?: DockerClientOptions & {
    readonly client?: DockerClient;
    readonly gatewayAddress?: string;
  },
) => LocalServiceMaterializerRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-materializer.ts#L25)

## `docker-runner.ts`

### dockerCommandRunner

**Signature**

```ts
declare const dockerCommandRunner: (executable?: string) => DockerCommandRunner;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-runner.ts#L8)

## `docker-types.ts`

### DockerClient (interface)

**Signature**

```ts
export interface DockerClient {
  readonly discover: (signal?: AbortSignal) => Promise<DockerEngineInfo>;
  readonly command: (
    arguments_: readonly string[],
    operation: string,
    options?: DockerCommandOptions,
  ) => Promise<string>;
  readonly containers: (
    labels?: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly DockerContainer[]>;
  readonly volumes: (
    labels?: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly DockerVolume[]>;
  readonly inspectContainer: (id: string, signal?: AbortSignal) => Promise<DockerContainer>;
  readonly waitForHealthy: (id: string, options?: DockerHealthOptions) => Promise<DockerContainer>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L75)

### DockerClientOptions (interface)

**Signature**

```ts
export interface DockerClientOptions {
  readonly executable?: string;
  readonly run?: DockerCommandRunner;
  readonly maxOutputBytes?: number;
  readonly commandTimeoutMs?: number;
  readonly now?: () => number;
  readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L66)

### DockerCommandOptions (interface)

**Signature**

```ts
export interface DockerCommandOptions {
  readonly signal?: AbortSignal;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L22)

### DockerCommandRequest (interface)

**Signature**

```ts
export interface DockerCommandRequest extends DockerCommandOptions {
  readonly maxOutputBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L27)

### DockerCommandResult (interface)

**Signature**

```ts
export interface DockerCommandResult {
  readonly exitCode: number;
  readonly stdout: string;
  readonly stderr: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L31)

### DockerCommandRunner (type alias)

**Signature**

```ts
type DockerCommandRunner = (
  command: readonly string[],
  options: DockerCommandRequest,
) => Promise<DockerCommandResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L37)

### DockerContainer (interface)

**Signature**

```ts
export interface DockerContainer {
  readonly id: string;
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly state: string;
  readonly health?: "starting" | "healthy" | "unhealthy";
  readonly ports: Readonly<Record<string, number>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L46)

### DockerEngineError (class)

**Signature**

```ts
declare class DockerEngineError { constructor(
    readonly code: DockerEngineErrorCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L12)

### DockerEngineErrorCode (type alias)

**Signature**

```ts
type DockerEngineErrorCode =
  | "RELKIT_DOCKER_ARGUMENT_INVALID"
  | "RELKIT_DOCKER_UNAVAILABLE"
  | "RELKIT_DOCKER_COMMAND_FAILED"
  | "RELKIT_DOCKER_COMMAND_TIMEOUT"
  | "RELKIT_DOCKER_OUTPUT_LIMIT"
  | "RELKIT_DOCKER_RESPONSE_INVALID"
  | "RELKIT_DOCKER_HEALTH_FAILED"
  | "RELKIT_DOCKER_HEALTH_TIMEOUT"
  | "RELKIT_DOCKER_CANCELLED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L1)

### DockerEngineInfo (interface)

**Signature**

```ts
export interface DockerEngineInfo {
  readonly version: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L42)

### DockerHealthOptions (interface)

**Signature**

```ts
export interface DockerHealthOptions {
  readonly timeoutMs?: number;
  readonly pollIntervalMs?: number;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L60)

### DockerVolume (interface)

**Signature**

```ts
export interface DockerVolume {
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-types.ts#L55)

## `docker-validation.ts`

### cancelled

**Signature**

```ts
declare const cancelled: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L68)

### invalidArgument

**Signature**

```ts
declare const invalidArgument: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L60)

### invalidResponse

**Signature**

```ts
declare const invalidResponse: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L64)

### labelFilters

**Signature**

```ts
declare const labelFilters: (labels: Readonly<Record<string, string>> | undefined) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L3)

### optionalSignal

**Signature**

```ts
declare const optionalSignal: (signal: AbortSignal | undefined) => DockerCommandOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L56)

### positive

**Signature**

```ts
declare const positive: (value: number, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L38)

### requiredText

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L45)

### resourceLines

**Signature**

```ts
declare const resourceLines: (value: string) => string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L13)

### responseText

**Signature**

```ts
declare const responseText: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L51)

### validateArgument

**Signature**

```ts
declare const validateArgument: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L30)

### validateArguments

**Signature**

```ts
declare const validateArguments: (values: readonly string[]) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L25)

### validateResourceId

**Signature**

```ts
declare const validateResourceId: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/docker-validation.ts#L34)

## `index.ts`

### "./docker-client.js" (namespace export)

Re-exports all named exports from the "./docker-client.js" module.

**Signature**

```ts
export * from "./docker-client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L6)

### "./docker-materializer.js" (namespace export)

Re-exports all named exports from the "./docker-materializer.js" module.

**Signature**

```ts
export * from "./docker-materializer.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L7)

### "./docker-types.js" (namespace export)

Re-exports all named exports from the "./docker-types.js" module.

**Signature**

```ts
export * from "./docker-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L8)

### dockerMaterializer

**Signature**

```ts
declare const dockerMaterializer: Readonly<{
  kind: "local-service-materializer";
  protocolVersion: 1;
  integrationId: "docker";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/docker/src/runtime/index.ts#L10)

---

# Effect MQ API
Source: https://relkit.dev/docs/api/integrations/effect-mq

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [schedules](/docs/modules/jobs/schedules), [docker](/docs/modules/jobs/docker), [providers](/docs/modules/jobs/providers).

## Public imports

- `@relkit/effect-mq` — 7 exports
- `@relkit/effect-mq/runtime` — 22 exports
- `@relkit/effect-mq/local-recipe` — 1 exports
- `@relkit/effect-mq/deployment` — 4 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                               | Kind  | Import from                      | Example                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [createEffectMqJob](/docs/api/integrations/effect-mq#createeffectmqjob)                                           | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [createEffectMqPostgresLayer](/docs/api/integrations/effect-mq#createeffectmqpostgreslayer)                       | Value | `@relkit/effect-mq/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/jobs/compatibility/effect-mq-native.ts#L39)                   |
| [createEffectMqPostgresNativeClient](/docs/api/integrations/effect-mq#createeffectmqpostgresnativeclient)         | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [createEffectMqPostgresSchema](/docs/api/integrations/effect-mq#createeffectmqpostgresschema)                     | Value | `@relkit/effect-mq/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/tests/postgres-listen.test.ts#L122) |
| [createEffectMqRuntime](/docs/api/integrations/effect-mq#createeffectmqruntime)                                   | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [createEffectMqScheduleOperations](/docs/api/integrations/effect-mq#createeffectmqscheduleoperations)             | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [createEffectMqWorker](/docs/api/integrations/effect-mq#createeffectmqworker)                                     | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [createEffectMqWorkerLayer](/docs/api/integrations/effect-mq#createeffectmqworkerlayer)                           | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [deploymentProfile](/docs/api/integrations/effect-mq#deploymentprofile)                                           | Value | `@relkit/effect-mq/deployment`   | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [effectMq](/docs/api/integrations/effect-mq#effectmq)                                                             | Value | `@relkit/effect-mq`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/providers/effect-mq-config.ts#L12)          |
| [EffectMqAdapter](/docs/api/integrations/effect-mq#effectmqadapter-type-alias)                                    | Type  | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqBehavior](/docs/api/integrations/effect-mq#effectmqbehavior-type-alias)                                  | Type  | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [effectMqConnectionContract](/docs/api/integrations/effect-mq#effectmqconnectioncontract)                         | Value | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqDeploymentProfile](/docs/api/integrations/effect-mq#effectmqdeploymentprofile-interface)                 | Type  | `@relkit/effect-mq/deployment`   | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [effectMqIntegration](/docs/api/integrations/effect-mq#effectmqintegration)                                       | Value | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqJobDefinition](/docs/api/integrations/effect-mq#effectmqjobdefinition-interface)                         | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqJobOptions](/docs/api/integrations/effect-mq#effectmqjoboptions-interface)                               | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [effectMqLocalRecipe](/docs/api/integrations/effect-mq#effectmqlocalrecipe)                                       | Value | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqNativeClient](/docs/api/integrations/effect-mq#effectmqnativeclient-interface)                           | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqOptions](/docs/api/integrations/effect-mq#effectmqoptions-interface)                                     | Type  | `@relkit/effect-mq`              | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqPostgresNativeOptions](/docs/api/integrations/effect-mq#effectmqpostgresnativeoptions-interface)         | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqPostgresSchema](/docs/api/integrations/effect-mq#effectmqpostgresschema-interface)                       | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqRuntime](/docs/api/integrations/effect-mq#effectmqruntime-interface)                                     | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqRuntimeOptions](/docs/api/integrations/effect-mq#effectmqruntimeoptions-interface)                       | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqScheduleBridge](/docs/api/integrations/effect-mq#effectmqschedulebridge-interface)                       | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqScheduleStore](/docs/api/integrations/effect-mq#effectmqschedulestore-interface)                         | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqTaskDefinition](/docs/api/integrations/effect-mq#effectmqtaskdefinition-interface)                       | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqWorkerHandle](/docs/api/integrations/effect-mq#effectmqworkerhandle-interface)                           | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqWorkerPublication](/docs/api/integrations/effect-mq#effectmqworkerpublication-interface)                 | Type  | `@relkit/effect-mq/deployment`   | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [EffectMqWorkerRegistrationOptions](/docs/api/integrations/effect-mq#effectmqworkerregistrationoptions-interface) | Type  | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [localRecipe](/docs/api/integrations/effect-mq#localrecipe-1)                                                     | Value | `@relkit/effect-mq/local-recipe` | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [nativeWorkerPublication](/docs/api/integrations/effect-mq#nativeworkerpublication)                               | Value | `@relkit/effect-mq/deployment`   | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [runEffectMq](/docs/api/integrations/effect-mq#runeffectmq)                                                       | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |
| [runtimeIntegration](/docs/api/integrations/effect-mq#runtimeintegration)                                         | Value | `@relkit/effect-mq/runtime`      | [Module example](/docs/modules/jobs/schedules)                                                                                   |

## `build-catalog.ts`

### effectMqSdk

**Signature**

```ts
declare const effectMqSdk: "effect-mq@0.7.0";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/build-catalog.ts#L3)

### effectVersion

**Signature**

```ts
declare const effectVersion: "4.0.1";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/build-catalog.ts#L2)

## `index.ts`

### EffectMqDeploymentProfile (interface)

**Signature**

```ts
export interface EffectMqDeploymentProfile {
  readonly provider: "effect-mq";
  readonly compatibility: "native";
  readonly adapterId: "effect-mq";
  readonly effect: typeof effectVersion;
  readonly sdk: typeof effectMqSdk;
  readonly database: "postgresql";
  readonly durableSleep: false;
  readonly workerRuntime: "bun";
  readonly executionLimits: Readonly<{
    readonly inputBytes: number;
    readonly progressBytes: number;
    readonly maxRunList: number;
  }>;
  readonly policyIdentity: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/deployment/index.ts#L3)

### EffectMqWorkerPublication (interface)

**Signature**

```ts
export interface EffectMqWorkerPublication {
  readonly provider: "effect-mq";
  readonly mechanism: "effect-mq-sdk";
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly serviceGeneration: string;
  readonly entrypoint: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/deployment/index.ts#L20)

### deploymentProfile

**Signature**

```ts
declare const deploymentProfile: EffectMqDeploymentProfile;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/deployment/index.ts#L30)

### nativeWorkerPublication

**Signature**

```ts
declare const nativeWorkerPublication: (
  value: Omit<EffectMqWorkerPublication, "provider" | "mechanism">,
) => EffectMqWorkerPublication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/deployment/index.ts#L50)

## `index.ts`

### EffectMqAdapter (type alias)

**Signature**

```ts
type EffectMqAdapter<Options extends EffectMqOptions = EffectMqOptions> = ProviderAdapter<
  typeof job,
  "effect-mq",
  ProviderConnectionValues,
  ProviderBehavior<EffectMqBehavior>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L46)

### EffectMqBehavior (type alias)

**Signature**

```ts
type EffectMqBehavior = JobsServiceBehavior;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L45)

### EffectMqOptions (interface)

**Signature**

```ts
export interface EffectMqOptions extends JobsServiceOptions {
  readonly postgresUrl?: string | TextReference | SecretReference;
  readonly schema?: string;
  readonly tablePrefix?: string;
  readonly queue?: string;
  readonly native?: Readonly<Record<string, import("@relkit/contracts").JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L37)

### effectMq

**Signature**

```ts
declare const effectMq: <const Options extends EffectMqOptions = EffectMqOptions>(
  options?: Options,
) => EffectMqAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L57)

### effectMqConnectionContract

**Signature**

```ts
declare const effectMqConnectionContract: ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L54)

### effectMqIntegration

**Signature**

```ts
declare const effectMqIntegration: IntegrationReference<"effect-mq">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L53)

### effectMqLocalRecipe

**Signature**

```ts
declare const effectMqLocalRecipe: ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/index.ts#L55)

## `job.ts`

### EffectMqJobDefinition (interface)

**Signature**

```ts
export interface EffectMqJobDefinition {
  readonly job: ReturnType<typeof Job.make>;
  readonly workerLayer: ReturnType<typeof Worker.layer>;
  readonly handlerLayer: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/job.ts#L21)

### EffectMqJobOptions (interface)

**Signature**

```ts
export interface EffectMqJobOptions {
  readonly name: string;
  readonly queue?: string;
  readonly attempts?: number;
  readonly backoff?: {
    readonly type: "fixed" | "exponential";
    readonly delay: Duration.Input;
    readonly factor?: number;
  };
  readonly handler: (
    input: unknown,
    signal: AbortSignal,
    context: Worker.JobContext,
  ) => Promise<unknown>;
  readonly worker?: Parameters<typeof Worker.layer>[0];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/job.ts#L4)

### createEffectMqJob

Builds a schema-first native Job.make definition without exposing app schemas.

**Signature**

```ts
declare const createEffectMqJob: (options: EffectMqJobOptions) => EffectMqJobDefinition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/job.ts#L28)

### createEffectMqWorkerLayer

**Signature**

```ts
declare const createEffectMqWorkerLayer: (
  options?: Parameters<typeof Worker.layer>[0],
) => ReturnType<typeof Worker.layer>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/job.ts#L55)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "effect-mq";
  recipeId: "effect-mq-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    Readonly<{
      id: "postgres";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      ports: Readonly<{ postgres: 5432 }>;
      volumes: ReadonlyArray<{ name: string; mountPath: string }>;
      environment: Readonly<{
        POSTGRES_DB: Readonly<{ value: "relkit" }>;
        POSTGRES_USER: Readonly<{ value: "relkit" }>;
        POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
      }>;
      health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
      networkAliases: ReadonlyArray<string>;
    }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 120 }>;
      networkAliases: ReadonlyArray<string>;
      hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
      environment: Readonly<{
        POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        RELKIT_EFFECT_MQ_MIGRATIONS: Readonly<{ value: "owned-by-jobs-service" }>;
      }>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{ postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }> }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({
    ports,
    secrets,
  }: LocalServiceRecipeOutputContext) => Readonly<{ postgresUrl: string }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local-recipe/index.ts#L1)

## `local-support.ts`

### BUN_IMAGE

**Signature**

```ts
declare const BUN_IMAGE: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local-support.ts#L3)

### POSTGRES_IMAGE

**Signature**

```ts
declare const POSTGRES_IMAGE: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local-support.ts#L1)

### number

**Signature**

```ts
declare const number: (value: unknown, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local-support.ts#L11)

### text

**Signature**

```ts
declare const text: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local-support.ts#L6)

## `local.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "effect-mq";
  recipeId: "effect-mq-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    Readonly<{
      id: "postgres";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      ports: Readonly<{ postgres: 5432 }>;
      volumes: ReadonlyArray<{ name: string; mountPath: string }>;
      environment: Readonly<{
        POSTGRES_DB: Readonly<{ value: "relkit" }>;
        POSTGRES_USER: Readonly<{ value: "relkit" }>;
        POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
      }>;
      health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
      networkAliases: ReadonlyArray<string>;
    }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 120 }>;
      networkAliases: ReadonlyArray<string>;
      hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
      environment: Readonly<{
        POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        RELKIT_EFFECT_MQ_MIGRATIONS: Readonly<{ value: "owned-by-jobs-service" }>;
      }>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{ postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }> }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({
    ports,
    secrets,
  }: LocalServiceRecipeOutputContext) => Readonly<{ postgresUrl: string }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/local.ts#L108)

## `postgres-listen.ts`

## `postgres.ts`

Builds lazy native PostgreSQL job-store Layers with scoped driver ownership and explicit timestamp compatibility.

### EffectMqPostgresSchema

**Signature**

```ts
declare const EffectMqPostgresSchema: EffectMqPostgresSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/postgres.ts#L17)

### createEffectMqPostgresLayer

Builds the native PostgreSQL store Layer; the calling application owns schema migration and Layer lifetime.

**Signature**

```ts
declare const createEffectMqPostgresLayer: (
  postgresUrl: string,
  prefix?: string,
) => Layer.Layer<
  JobStore.JobStore,
  JobStore.JobStoreError | Layer.Error<ReturnType<typeof PgClient.layer>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/postgres.ts#L44)

### createEffectMqPostgresSchema

Builds the existing native store's complete schema without opening a database connection.

**Signature**

```ts
declare const createEffectMqPostgresSchema: (prefix?: string) => EffectMqPostgresSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/postgres.ts#L24)

### runEffectMq

Existing native Promise edge; callers supply and own the complete store/worker Layer lifetime.

**Signature**

```ts
declare const runEffectMq: <A, E>(
  effect: Effect.Effect<A, E>,
  options?: Effect.RunOptions | undefined,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/postgres.ts#L86)

## `postgres.types.ts`

Describes the complete native Drizzle PostgreSQL schema used by the scoped effect-mq integration.

### EffectMqPostgresSchema (interface)

Native table handles retain the SDK's exact row, query and foreign-key contracts.

**Signature**

```ts
export interface EffectMqPostgresSchema {
  /** Durable job state and acceptance metadata. */
  readonly jobs: ReturnType<typeof mqJobs>;
  /** Ordered native attempt ledger. */
  readonly attempts: ReturnType<typeof mqJobAttempts>;
  /** Provider-owned schedule definitions and next occurrences. */
  readonly schedules: ReturnType<typeof mqSchedules>;
  /** Native queue pause controls. */
  readonly queues: ReturnType<typeof mqQueueControl>;
  /** Native deduplication keys and windows. */
  readonly dedupe: ReturnType<typeof mqDedupe>;
  /** Durable child-flow admission and completion state. */
  readonly flowChildren: ReturnType<typeof mqFlowChildren>;
  /** Provider-owned parent-flow completion outbox. */
  readonly flowOutbox: ReturnType<typeof mqFlowOutbox>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/postgres.types.ts#L13)

## `index.ts`

### "../job.js" (namespace export)

Re-exports all named exports from the "../job.js" module.

**Signature**

```ts
export * from "../job.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L21)

### "../postgres.js" (namespace export)

Re-exports all named exports from the "../postgres.js" module.

**Signature**

```ts
export * from "../postgres.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L22)

### "./native.js" (namespace export)

Re-exports all named exports from the "./native.js" module.

**Signature**

```ts
export * from "./native.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L18)

### "./schedules.js" (namespace export)

Re-exports all named exports from the "./schedules.js" module.

**Signature**

```ts
export * from "./schedules.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L19)

### "./worker.js" (namespace export)

Re-exports all named exports from the "./worker.js" module.

**Signature**

```ts
export * from "./worker.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L20)

### EffectMqRuntime (interface)

**Signature**

```ts
export interface EffectMqRuntime extends JobsAdapterRuntime {
  readonly registerWorker: (options: EffectMqWorkerRegistrationOptions) => EffectMqWorkerHandle;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L36)

### EffectMqRuntimeOptions (interface)

**Signature**

```ts
export interface EffectMqRuntimeOptions {
  readonly native?: EffectMqNativeClient;
  readonly postgresUrl?: string;
  readonly tablePrefix?: string;
  readonly queue?: string;
  readonly schedules?: NativeScheduleOperations;
  readonly pollIntervalMs?: number;
  readonly maxPolls?: number;
  readonly readTimeoutMs?: number;
  readonly serviceOptions?: JobsServiceOptions;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L24)

### createEffectMqRuntime

**Signature**

```ts
declare const createEffectMqRuntime: (options?: EffectMqRuntimeOptions) => EffectMqRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L40)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: RuntimeProviderIntegration<"effect-mq">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/index.ts#L129)

## `native.ts`

### EffectMqNativeClient (interface)

**Signature**

```ts
export interface EffectMqNativeClient {
  readonly submit: (request: NativeSubmission, context: OperationContext) => Promise<NativeReceipt>;
  readonly get: (runId: string, context: OperationContext) => Promise<NativeRun>;
  readonly list: (query: NativeRunQuery, context: OperationContext) => Promise<NativeRunPage>;
  readonly cancel: (
    runId: string,
    operationId: string,
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly retry: (
    request: Parameters<NonNullable<JobsAdapterRuntime["retry"]>>[0],
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly observe?: JobsAdapterRuntime["observe"];
  readonly schedules?: NativeScheduleOperations;
  readonly close?: () => Promise<void>;
  readonly registerWorker?: (options: EffectMqWorkerRegistrationOptions) => EffectMqWorkerHandle;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/native.ts#L24)

### EffectMqPostgresNativeOptions (interface)

**Signature**

```ts
export interface EffectMqPostgresNativeOptions {
  readonly postgresUrl: string;
  readonly tablePrefix?: string;
  readonly queue?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/native.ts#L43)

### createEffectMqPostgresNativeClient

**Signature**

```ts
declare const createEffectMqPostgresNativeClient: (
  options: EffectMqPostgresNativeOptions,
) => EffectMqNativeClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/native.ts#L49)

## `observe.ts`

### EffectMqObservationOptions (interface)

**Signature**

```ts
export interface EffectMqObservationOptions {
  readonly pollIntervalMs?: number;
  readonly maxPolls?: number;
  readonly readTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/observe.ts#L9)

### observeEffectMqRun

**Signature**

```ts
declare const observeEffectMqRun: (
  get: EffectMqNativeClient["get"],
  request: NativeWatchRequest,
  context: OperationContext,
  options: EffectMqObservationOptions,
) => AsyncIterable<NativeObservation>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/observe.ts#L15)

## `postgres-operations-support.ts`

### object

**Signature**

```ts
declare const object: (value: unknown) => Record<string, any> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations-support.ts#L40)

### submissionId

**Signature**

```ts
declare const submissionId: (request: NativeSubmission) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations-support.ts#L3)

### submissionMetadata

**Signature**

```ts
declare const submissionMetadata: (
  request: NativeSubmission,
  context: OperationContext,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations-support.ts#L7)

### text

**Signature**

```ts
declare const text: (value: unknown, fallback: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations-support.ts#L46)

## `postgres-operations.ts`

### NativeReceiptValue (type alias)

**Signature**

```ts
type NativeReceiptValue = NativeSubmissionReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L157)

### cancelEffectMqRun

**Signature**

```ts
declare const cancelEffectMqRun: (
  state: EffectMqPostgresState,
  runId: string,
  operationId: string,
  context: OperationContext,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L83)

### getEffectMqRun

**Signature**

```ts
declare const getEffectMqRun: (
  state: EffectMqPostgresState,
  runId: string,
  context: OperationContext,
) => Promise<NativeRun>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L45)

### listEffectMqRuns

**Signature**

```ts
declare const listEffectMqRuns: (
  state: EffectMqPostgresState,
  query: NativeRunQuery,
  context: OperationContext,
) => Promise<NativeRunPage>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L55)

### readRecord

**Signature**

```ts
declare const readRecord: (
  state: EffectMqPostgresState,
  runId: string,
  signal: AbortSignal,
) => Promise<JobStore.JobRecord | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L144)

### retryEffectMqRun

**Signature**

```ts
declare const retryEffectMqRun: (
  state: EffectMqPostgresState,
  request: NativeRetryRequest,
  context: OperationContext,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L98)

### submitEffectMq

**Signature**

```ts
declare const submitEffectMq: (
  state: EffectMqPostgresState,
  request: NativeSubmission,
  context: OperationContext,
) => Promise<NativeReceiptValue>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-operations.ts#L17)

## `postgres-query.ts`

### matches

**Signature**

```ts
declare const matches: (query: NativeRunQuery, run: NativeRun) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-query.ts#L34)

### metadataFilter

**Signature**

```ts
declare const metadataFilter: (query: NativeRunQuery) => Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-query.ts#L5)

### states

**Signature**

```ts
declare const states: (
  statuses: NativeRunQuery["status"],
) => readonly JobStore.JobState[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-query.ts#L17)

### terminal

**Signature**

```ts
declare const terminal: (status: RunSnapshot["status"]) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-query.ts#L70)

### terminalState

**Signature**

```ts
declare const terminalState: (state: JobStore.JobState) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-query.ts#L79)

## `postgres-schedules.ts`

### createEffectMqPostgresSchedules

**Signature**

```ts
declare const createEffectMqPostgresSchedules: (
  getState: () => EffectMqPostgresState,
  queue: string | undefined,
) => NativeScheduleOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-schedules.ts#L8)

## `postgres-snapshots.ts`

### effectMqSnapshot

**Signature**

```ts
declare const effectMqSnapshot: (
  state: EffectMqPostgresState,
  record: JobStore.JobRecord,
  context: OperationContext,
) => Promise<NativeRun>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-snapshots.ts#L7)

### statusOf

**Signature**

```ts
declare const statusOf: (record: JobStore.JobRecord) => NativeRun["status"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-snapshots.ts#L84)

## `postgres-state-support.ts`

### attempts

**Signature**

```ts
declare const attempts: (policy: unknown) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state-support.ts#L80)

### bindingFrom

**Signature**

```ts
declare const bindingFrom: (
  envelope: TaskExecutionEnvelope,
  signal: AbortSignal,
) => TaskExecutionBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state-support.ts#L45)

### envelopeFrom

**Signature**

```ts
declare const envelopeFrom: (
  input: unknown,
  definition: EffectMqTaskDefinition,
  context: Worker.JobContext,
) => TaskExecutionEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state-support.ts#L6)

## `postgres-state.ts`

### EffectMqPostgresState (interface)

**Signature**

```ts
export interface EffectMqPostgresState {
  readonly jobs: Map<string, EffectMqJobDefinition["job"]>;
  readonly definitions: Map<string, EffectMqTaskDefinition>;
  readonly run: <A>(effect: Effect.Effect<A, unknown, unknown>, signal?: AbortSignal) => Promise<A>;
  readonly ready: () => Promise<void>;
  readonly ensureJob: (name: string) => EffectMqJobDefinition["job"];
  readonly workerStarted: boolean;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state.ts#L18)

### EffectMqPostgresStateOptions (interface)

**Signature**

```ts
export interface EffectMqPostgresStateOptions {
  readonly postgresUrl: string;
  readonly tablePrefix?: string;
  readonly queue?: string;
  readonly definitions?: readonly EffectMqTaskDefinition[];
  readonly executor?: TaskExecutor;
  readonly startWorker?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state.ts#L9)

### createEffectMqPostgresState

**Signature**

```ts
declare const createEffectMqPostgresState: (
  options: EffectMqPostgresStateOptions,
) => EffectMqPostgresState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/postgres-state.ts#L28)

## `schedules.ts`

### EffectMqScheduleBridge (interface)

**Signature**

```ts
export interface EffectMqScheduleBridge {
  readonly store: EffectMqScheduleStore;
  readonly run: <A>(effect: Effect.Effect<A, unknown, unknown>) => Promise<A>;
  readonly jobName: string;
  readonly queue?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/schedules.ts#L23)

### EffectMqScheduleStore (interface)

**Signature**

```ts
export interface EffectMqScheduleStore {
  readonly listSchedules: (options?: {
    readonly jobName?: string;
    readonly group?: string;
  }) => Effect.Effect<ReadonlyArray<EffectScheduleRecord>, unknown, unknown>;
  readonly upsertSchedule: (
    schedule: EffectScheduleRecord,
  ) => Effect.Effect<void, unknown, unknown>;
  readonly removeSchedule: (key: ScheduleKey) => Effect.Effect<boolean, unknown, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/schedules.ts#L12)

### createEffectMqScheduleOperations

Maps effect-mq JobSchedules' native Postgres records to the RELKIT schedule SPI.

**Signature**

```ts
declare const createEffectMqScheduleOperations: (
  options: EffectMqScheduleBridge,
) => NativeScheduleOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/schedules.ts#L31)

## `support.ts`

### optionalText

**Signature**

```ts
declare const optionalText: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/support.ts#L1)

## `worker.ts`

### EffectMqTaskDefinition (interface)

**Signature**

```ts
export interface EffectMqTaskDefinition {
  readonly id: string;
  readonly jobId: string;
  readonly taskId: string;
  readonly version: string;
  readonly taskVersion?: string;
  readonly buildId: string;
  readonly policy?: unknown;
  readonly schedules?: readonly unknown[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/worker.ts#L3)

### EffectMqWorkerHandle (interface)

**Signature**

```ts
export interface EffectMqWorkerHandle {
  readonly definitions: readonly EffectMqTaskDefinition[];
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/worker.ts#L21)

### EffectMqWorkerRegistrationOptions (interface)

**Signature**

```ts
export interface EffectMqWorkerRegistrationOptions {
  readonly definitions: readonly EffectMqTaskDefinition[];
  readonly executor: TaskExecutor;
  readonly startWorker?: boolean;
  readonly register?: (definitions: readonly EffectMqTaskDefinition[]) => Promise<void> | void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/worker.ts#L14)

### createEffectMqWorker

**Signature**

```ts
declare const createEffectMqWorker: (
  options: EffectMqWorkerRegistrationOptions,
) => EffectMqWorkerHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/effect-mq/src/runtime/worker.ts#L27)

---

# Inngest API
Source: https://relkit.dev/docs/api/integrations/inngest

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [bindings](/docs/modules/jobs/bindings), [schedules](/docs/modules/jobs/schedules), [docker](/docs/modules/jobs/docker).

## Public imports

- `@relkit/inngest` — 7 exports
- `@relkit/inngest/runtime` — 26 exports
- `@relkit/inngest/local-recipe` — 1 exports
- `@relkit/inngest/deployment` — 4 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                            | Kind  | Import from                    | Example                                                                                                               |
| -------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [createInngestFunction](/docs/api/integrations/inngest#createinngestfunction)                                  | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [createInngestFunctionConfig](/docs/api/integrations/inngest#createinngestfunctionconfig)                      | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [createInngestRunApi](/docs/api/integrations/inngest#createinngestrunapi)                                      | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [createInngestRuntime](/docs/api/integrations/inngest#createinngestruntime)                                    | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [createInngestServeHandler](/docs/api/integrations/inngest#createinngestservehandler)                          | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [createInngestWorker](/docs/api/integrations/inngest#createinngestworker)                                      | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [deploymentProfile](/docs/api/integrations/inngest#deploymentprofile)                                          | Value | `@relkit/inngest/deployment`   | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [inngest](/docs/api/integrations/inngest#inngest)                                                              | Value | `@relkit/inngest`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/providers/inngest-config.ts#L12) |
| [InngestAdapter](/docs/api/integrations/inngest#inngestadapter-type-alias)                                     | Type  | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestApiRequestError](/docs/api/integrations/inngest#inngestapirequesterror-class)                          | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestBehavior](/docs/api/integrations/inngest#inngestbehavior-type-alias)                                   | Type  | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [inngestConnectionContract](/docs/api/integrations/inngest#inngestconnectioncontract)                          | Value | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestDeploymentProfile](/docs/api/integrations/inngest#inngestdeploymentprofile-interface)                  | Type  | `@relkit/inngest/deployment`   | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [inngestFunctionId](/docs/api/integrations/inngest#inngestfunctionid)                                          | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [inngestIntegration](/docs/api/integrations/inngest#inngestintegration)                                        | Value | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [inngestLocalRecipe](/docs/api/integrations/inngest#inngestlocalrecipe)                                        | Value | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestObservationOptions](/docs/api/integrations/inngest#inngestobservationoptions-interface)                | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestOptions](/docs/api/integrations/inngest#inngestoptions-interface)                                      | Type  | `@relkit/inngest`              | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestRunApi](/docs/api/integrations/inngest#inngestrunapi-interface)                                        | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestRunMetadata](/docs/api/integrations/inngest#inngestrunmetadata-interface)                              | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestRuntime](/docs/api/integrations/inngest#inngestruntime-interface)                                      | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestRuntimeOptions](/docs/api/integrations/inngest#inngestruntimeoptions-interface)                        | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestSdk](/docs/api/integrations/inngest#inngestsdk-interface)                                              | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestTaskDefinition](/docs/api/integrations/inngest#inngesttaskdefinition-interface)                        | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestWorkerHandle](/docs/api/integrations/inngest#inngestworkerhandle-interface)                            | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestWorkerOptions](/docs/api/integrations/inngest#inngestworkeroptions-interface)                          | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestWorkerPublication](/docs/api/integrations/inngest#inngestworkerpublication-interface)                  | Type  | `@relkit/inngest/deployment`   | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [InngestWorkerRegistrationOptions](/docs/api/integrations/inngest#inngestworkerregistrationoptions-type-alias) | Type  | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [isAmbiguousInngestWrite](/docs/api/integrations/inngest#isambiguousinngestwrite)                              | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [loadInngestSdk](/docs/api/integrations/inngest#loadinngestsdk)                                                | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [localRecipe](/docs/api/integrations/inngest#localrecipe-1)                                                    | Value | `@relkit/inngest/local-recipe` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L148)   |
| [MAX_LOCAL_INDEX_ENTRIES](/docs/api/integrations/inngest#max_local_index_entries)                              | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [nativeWorkerPublication](/docs/api/integrations/inngest#nativeworkerpublication)                              | Value | `@relkit/inngest/deployment`   | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [observeInngestRun](/docs/api/integrations/inngest#observeinngestrun)                                          | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [rememberInngestRecord](/docs/api/integrations/inngest#rememberinngestrecord)                                  | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [runtimeIntegration](/docs/api/integrations/inngest#runtimeintegration)                                        | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [snapshot](/docs/api/integrations/inngest#snapshot)                                                            | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |
| [statusOf](/docs/api/integrations/inngest#statusof)                                                            | Value | `@relkit/inngest/runtime`      | [Module example](/docs/modules/jobs/bindings)                                                                         |

## `index.ts`

### InngestDeploymentProfile (interface)

**Signature**

```ts
export interface InngestDeploymentProfile {
  readonly provider: "inngest";
  readonly compatibility: "native";
  readonly adapterId: "inngest";
  readonly sdk: "inngest@4.20.0";
  readonly serverImageDigest: string;
  readonly profile: "self-hosted-docker";
  readonly workerRuntime: "bun";
  readonly executionLimits: Readonly<{
    readonly inputBytes: number;
    readonly progressBytes: number;
    readonly maxRunList: number;
  }>;
  readonly policyIdentity: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/deployment/index.ts#L1)

### InngestWorkerPublication (interface)

**Signature**

```ts
export interface InngestWorkerPublication {
  readonly provider: "inngest";
  readonly mechanism: "inngest-sdk";
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly serviceGeneration: string;
  readonly entrypoint: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/deployment/index.ts#L17)

### deploymentProfile

**Signature**

```ts
declare const deploymentProfile: InngestDeploymentProfile;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/deployment/index.ts#L27)

### nativeWorkerPublication

**Signature**

```ts
declare const nativeWorkerPublication: (
  value: Omit<InngestWorkerPublication, "provider" | "mechanism">,
) => InngestWorkerPublication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/deployment/index.ts#L46)

## `index.ts`

### InngestAdapter (type alias)

**Signature**

```ts
type InngestAdapter<Options extends InngestOptions = InngestOptions> = ProviderAdapter<
  typeof job,
  "inngest",
  ProviderConnectionValues,
  ProviderBehavior<InngestBehavior>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L53)

### InngestBehavior (type alias)

**Signature**

```ts
type InngestBehavior = JobsServiceBehavior;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L52)

### InngestOptions (interface)

**Signature**

```ts
export interface InngestOptions extends JobsServiceOptions {
  readonly appId?: string;
  readonly baseUrl?: string | URL | TextReference;
  readonly eventKey?: SecretReference;
  readonly signingKey?: SecretReference;
  readonly serveOrigin?: string | URL | TextReference;
  readonly appVersion?: string;
  readonly native?: Readonly<Record<string, import("@relkit/contracts").JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L42)

### inngest

Defines a native Inngest durable-jobs adapter without importing the SDK.

**Signature**

```ts
declare const inngest: <const Options extends InngestOptions = InngestOptions>(
  options?: Options,
) => InngestAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L65)

### inngestConnectionContract

**Signature**

```ts
declare const inngestConnectionContract: ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L61)

### inngestIntegration

**Signature**

```ts
declare const inngestIntegration: IntegrationReference<"inngest">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L60)

### inngestLocalRecipe

**Signature**

```ts
declare const inngestLocalRecipe: ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/index.ts#L62)

## `local-readiness.ts`

### waitForInngestReadiness

**Signature**

```ts
declare const waitForInngestReadiness: (context: LocalServiceRecipeOutputContext) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local-readiness.ts#L5)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "inngest";
  recipeId: "inngest-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    | Readonly<{
        id: "postgres";
        image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        environment: Readonly<{
          POSTGRES_DB: Readonly<{ value: "inngest" }>;
          POSTGRES_USER: Readonly<{ value: "inngest" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "redis";
        image: "redis:7-alpine@sha256:ff02b58f971e7d7d156a1267e283fcbbeee91773b6aa36c49dac28ecfe28eadf";
        command: ReadonlyArray<string>;
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "inngest";
        image: "inngest/inngest@sha256:d5365a31f8bf504dc2d54ddd114fcdc1a0413f8b57a450365c095ab6234ad8c2";
        command: ReadonlyArray<string>;
        dependsOn: ReadonlyArray<string>;
        ports: Readonly<{ api: 8288 }>;
        health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
        hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
        environment: Readonly<{
          INNGEST_EVENT_KEY: Readonly<{ secret: "eventKey" }>;
          INNGEST_SIGNING_KEY: Readonly<{ secret: "signingKey" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
      }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{
        command: Array<string>;
        intervalMs: 500;
        timeoutMs: 2000;
        retries: number;
      }>;
      networkAliases: ReadonlyArray<string>;
      hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
    }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
    redis: Readonly<{ mountPath: "/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{
    eventKey: Readonly<{ bytes: 24; encoding: "hex" }>;
    signingKey: Readonly<{ bytes: 32; encoding: "hex" }>;
    postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }>;
  }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({ ports, secrets, endpoints }: LocalServiceRecipeOutputContext) => Readonly<{
    baseUrl: `http://127.0.0.1:${number}`;
    eventKey: string;
    signingKey: string;
    serveOrigin: string;
  }>;
  initialize: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local-recipe/index.ts#L1)

## `local-timeouts.ts`

Startup budget shared by the Docker worker health check and readiness probes.

### INNGEST_LOCAL_HEALTH_INTERVAL_MS

**Signature**

```ts
declare const INNGEST_LOCAL_HEALTH_INTERVAL_MS: 500;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local-timeouts.ts#L3)

### INNGEST_LOCAL_HEALTH_RETRIES

**Signature**

```ts
declare const INNGEST_LOCAL_HEALTH_RETRIES: number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local-timeouts.ts#L4)

### INNGEST_LOCAL_STARTUP_TIMEOUT_MS

Startup budget shared by the Docker worker health check and readiness probes.

**Signature**

```ts
declare const INNGEST_LOCAL_STARTUP_TIMEOUT_MS: 300000;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local-timeouts.ts#L2)

## `local.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "inngest";
  recipeId: "inngest-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    | Readonly<{
        id: "postgres";
        image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        environment: Readonly<{
          POSTGRES_DB: Readonly<{ value: "inngest" }>;
          POSTGRES_USER: Readonly<{ value: "inngest" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "redis";
        image: "redis:7-alpine@sha256:ff02b58f971e7d7d156a1267e283fcbbeee91773b6aa36c49dac28ecfe28eadf";
        command: ReadonlyArray<string>;
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "inngest";
        image: "inngest/inngest@sha256:d5365a31f8bf504dc2d54ddd114fcdc1a0413f8b57a450365c095ab6234ad8c2";
        command: ReadonlyArray<string>;
        dependsOn: ReadonlyArray<string>;
        ports: Readonly<{ api: 8288 }>;
        health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
        hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
        environment: Readonly<{
          INNGEST_EVENT_KEY: Readonly<{ secret: "eventKey" }>;
          INNGEST_SIGNING_KEY: Readonly<{ secret: "signingKey" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
      }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{
        command: Array<string>;
        intervalMs: 500;
        timeoutMs: 2000;
        retries: number;
      }>;
      networkAliases: ReadonlyArray<string>;
      hostAliases: Readonly<{ "host.docker.internal": "host-gateway" }>;
    }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
    redis: Readonly<{ mountPath: "/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{
    eventKey: Readonly<{ bytes: 24; encoding: "hex" }>;
    signingKey: Readonly<{ bytes: 32; encoding: "hex" }>;
    postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }>;
  }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({ ports, secrets, endpoints }: LocalServiceRecipeOutputContext) => Readonly<{
    baseUrl: `http://127.0.0.1:${number}`;
    eventKey: string;
    signingKey: string;
    serveOrigin: string;
  }>;
  initialize: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/local.ts#L18)

## `index.ts`

### "./observe.js" (namespace export)

Re-exports all named exports from the "./observe.js" module.

**Signature**

```ts
export * from "./observe.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L190)

### "./runs.js" (namespace export)

Re-exports all named exports from the "./runs.js" module.

**Signature**

```ts
export * from "./runs.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L191)

### "./task-binding.js" (namespace export)

Re-exports all named exports from the "./task-binding.js" module.

**Signature**

```ts
export * from "./task-binding.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L192)

### InngestRuntime (interface)

**Signature**

```ts
export interface InngestRuntime extends JobsAdapterRuntime {
  readonly registerWorker: (options: InngestWorkerRegistrationOptions) => InngestWorkerHandle;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L25)

### InngestRuntimeOptions (interface)

**Signature**

```ts
export interface InngestRuntimeOptions {
  readonly appId: string;
  readonly baseUrl: string;
  readonly eventKey?: string;
  readonly signingKey?: string;
  readonly serveOrigin?: string;
  readonly appVersion?: string;
  readonly fetch?: typeof globalThis.fetch;
  readonly pollIntervalMs?: number;
  readonly maxPolls?: number;
  readonly serviceOptions?: JobsServiceOptions;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L29)

### createInngestRuntime

**Signature**

```ts
declare const createInngestRuntime: (options: InngestRuntimeOptions) => InngestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L42)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: RuntimeProviderIntegration<"inngest">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/index.ts#L153)

## `observe.ts`

### InngestObservationOptions (interface)

**Signature**

```ts
export interface InngestObservationOptions {
  readonly get: (runId: string, context: OperationContext) => Promise<RunSnapshot>;
  readonly pollIntervalMs?: number;
  readonly readTimeoutMs?: number;
  readonly maxPolls?: number;
  readonly subscribe?: (
    runId: string,
    onSnapshot: (run: RunSnapshot) => void,
    context: OperationContext,
  ) => Promise<(() => void) | undefined>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/observe.ts#L4)

### observeInngestRun

**Signature**

```ts
declare const observeInngestRun: (
  request: NativeWatchRequest,
  context: OperationContext,
  options: InngestObservationOptions,
) => AsyncIterable<NativeObservation>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/observe.ts#L16)

## `policy.ts`

### InngestPolicyMapping (interface)

**Signature**

```ts
export interface InngestPolicyMapping {
  readonly retries?: number;
  readonly timeoutSeconds?: number;
  readonly concurrency?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/policy.ts#L3)

### mapInngestPolicy

Maps only fields whose semantics are certified by the pinned Inngest profile.

**Signature**

```ts
declare const mapInngestPolicy: (value: unknown) => InngestPolicyMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/policy.ts#L10)

## `realtime.ts`

### subscribeInngestRun

**Signature**

```ts
declare const subscribeInngestRun: (
  client: Inngest.Any,
  appId: string,
  runId: string,
  onMessage: () => Promise<void>,
  context: OperationContext,
) => Promise<(() => void) | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/realtime.ts#L4)

## `run-controls.ts`

### cancelInngestRun

**Signature**

```ts
declare const cancelInngestRun: (
  locator: string,
  operationId: string,
  reason: string | undefined,
  context: OperationContext,
  api: InngestRunApi,
  records: Map<string, InngestRunMetadata>,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-controls.ts#L18)

### retryInngestRun

**Signature**

```ts
declare const retryInngestRun: (
  request: NativeRetryRequest,
  context: OperationContext,
  api: InngestRunApi,
  records: Map<string, InngestRunMetadata>,
  retryResults: Map<string, NativeControlReceipt>,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-controls.ts#L45)

## `run-operations.ts`

### listInngestRuns

**Signature**

```ts
declare const listInngestRuns: (
  query: RunListQuery,
  context: OperationContext,
  api: InngestRunApi,
  records: Map<string, InngestRunMetadata>,
) => Promise<RunPage>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-operations.ts#L49)

### readInngestRun

**Signature**

```ts
declare const readInngestRun: (
  locator: NativeLocator,
  context: OperationContext,
  api: InngestRunApi,
  records: Map<string, InngestRunMetadata>,
) => Promise<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-operations.ts#L18)

## `run-query.ts`

### decodeCursor

**Signature**

```ts
declare const decodeCursor: (value: string | undefined) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L44)

### encodeCursor

**Signature**

```ts
declare const encodeCursor: (offset: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L53)

### matchesMetadata

**Signature**

```ts
declare const matchesMetadata: (query: RunListQuery, metadata: InngestRunMetadata) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L7)

### matchesSnapshot

**Signature**

```ts
declare const matchesSnapshot: (query: RunListQuery, run: RunSnapshot) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L25)

### normalizeLimit

**Signature**

```ts
declare const normalizeLimit: (value: number | undefined) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L37)

### uniqueRecords

**Signature**

```ts
declare const uniqueRecords: (records: Map<string, InngestRunMetadata>) => InngestRunMetadata[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/run-query.ts#L33)

## `runs-support.ts`

### date

**Signature**

```ts
declare const date: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L21)

### hashSigningKey

**Signature**

```ts
declare const hashSigningKey: (signingKey: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L25)

### number

**Signature**

```ts
declare const number: (value: unknown) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L17)

### record

**Signature**

```ts
declare const record: (value: unknown) => Record<string, unknown> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L7)

### rows

**Signature**

```ts
declare const rows: (value: unknown) => Record<string, unknown>[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L3)

### text

**Signature**

```ts
declare const text: (value: unknown, fallback: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs-support.ts#L13)

## `runs.ts`

### InngestApiRequestError (class)

**Signature**

```ts
declare class InngestApiRequestError { constructor(
    readonly status: number,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L28)

### InngestRunApi (interface)

**Signature**

```ts
export interface InngestRunApi {
  readonly eventRuns: (
    eventId: string,
    signal?: AbortSignal,
  ) => Promise<readonly Record<string, unknown>[]>;
  readonly run: (runId: string, signal?: AbortSignal) => Promise<Record<string, unknown>>;
  readonly cancel: (
    runId: string,
    reason: string | undefined,
    signal?: AbortSignal,
  ) => Promise<Record<string, unknown>>;
  readonly retry: (runId: string, signal?: AbortSignal) => Promise<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L38)

### InngestRunMetadata (interface)

**Signature**

```ts
export interface InngestRunMetadata extends RunHandle {
  readonly eventId: string;
  readonly input?: JsonValue;
  readonly inputHash?: string;
  readonly inputSchemaHash?: string;
  readonly buildId: string;
  readonly service: string;
  readonly scope?: string;
  readonly acceptanceIdentity?: string;
  readonly occurrenceIdentity?: string;
  readonly parentRunId?: string;
  readonly scheduledFor?: string;
  readonly retryOfRunId?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
  readonly propagation?: TracePropagation;
  readonly serviceGeneration?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L9)

### MAX_LOCAL_INDEX_ENTRIES

**Signature**

```ts
declare const MAX_LOCAL_INDEX_ENTRIES: 1000;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L7)

### createInngestRunApi

**Signature**

```ts
declare const createInngestRunApi: (options: {
  readonly baseUrl: string;
  readonly signingKey?: string;
  readonly fetch?: typeof globalThis.fetch;
}) => InngestRunApi;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L52)

### isAmbiguousInngestWrite

**Signature**

```ts
declare const isAmbiguousInngestWrite: (error: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L178)

### rememberInngestRecord

**Signature**

```ts
declare const rememberInngestRecord: (
  records: Map<string, InngestRunMetadata>,
  key: string,
  value: InngestRunMetadata,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L182)

### snapshot

**Signature**

```ts
declare const snapshot: (
  value: Record<string, unknown>,
  metadata: InngestRunMetadata,
  observedAt?: string,
) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L114)

### statusOf

**Signature**

```ts
declare const statusOf: (value: unknown) => RunSnapshot["status"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/runs.ts#L164)

## `submission.ts`

### providerEventId

**Signature**

```ts
declare const providerEventId: (request: NativeSubmission, context: OperationContext) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/submission.ts#L93)

### submitInngestEvent

**Signature**

```ts
declare const submitInngestEvent: (
  client: Inngest.Any,
  request: NativeSubmission,
  context: OperationContext,
  records: Map<string, InngestRunMetadata>,
  submitted: Map<string, InngestRunMetadata>,
) => Promise<NativeReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/submission.ts#L8)

## `support.ts`

### duplicateReceipt

**Signature**

```ts
declare const duplicateReceipt: (value: NativeReceipt) => NativeReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L40)

### eventIdFrom

**Signature**

```ts
declare const eventIdFrom: (value: unknown, fallback: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L26)

### eventNameFor

**Signature**

```ts
declare const eventNameFor: (request: NativeSubmission) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L5)

### observationOptions

**Signature**

```ts
declare const observationOptions: (
  options: InngestRuntimeOptions,
) => Readonly<Record<string, number>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L50)

### optionalText

**Signature**

```ts
declare const optionalText: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L22)

### text

**Signature**

```ts
declare const text: (value: unknown, label: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L11)

### url

**Signature**

```ts
declare const url: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/support.ts#L16)

## `task-binding-function.ts`

### createInngestFunction

**Signature**

```ts
declare const createInngestFunction: (
  client: Inngest.Any,
  definition: InngestTaskDefinition,
  executor: TaskExecutor,
  activeSignals?: Set<AbortController>,
) => InngestFunction.Any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-function.ts#L15)

## `task-binding-support.ts`

### duration

**Signature**

```ts
declare const duration: (milliseconds: number) => `${number}s`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L90)

### envelopeFrom

**Signature**

```ts
declare const envelopeFrom: (
  context: Context,
  native: Record<string, unknown>,
  input: unknown,
) => TaskExecutionEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L50)

### record

**Signature**

```ts
declare const record: (value: unknown) => Record<string, any> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L96)

### safeSegment

**Signature**

```ts
declare const safeSegment: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L41)

### scheduleMetadata

**Signature**

```ts
declare const scheduleMetadata: (
  context: Context,
  definition: InngestTaskDefinition,
) => Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L14)

### signalFrom

**Signature**

```ts
declare const signalFrom: (value: unknown) => AbortSignal | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L45)

### wireInput

**Signature**

```ts
declare const wireInput: (input: unknown) => TaskExecutionEnvelope["input"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L37)

### withoutSchedules

**Signature**

```ts
declare const withoutSchedules: (
  definition: InngestTaskDefinition,
) => Omit<InngestTaskDefinition, "schedules" | "schedule">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding-support.ts#L7)

## `task-binding.ts`

### InngestSdk (interface)

**Signature**

```ts
export interface InngestSdk {
  readonly Inngest: InngestConstructor;
  readonly serve: InngestServe;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L14)

### InngestTaskDefinition (interface)

**Signature**

```ts
export interface InngestTaskDefinition {
  readonly functionId: string;
  readonly eventName: string;
  readonly jobId?: string;
  readonly taskId?: string;
  readonly version?: string;
  readonly taskVersion?: string;
  readonly buildId?: string;
  readonly retries?: number;
  readonly timeoutSeconds?: number;
  readonly concurrency?: number;
  readonly policy?: unknown;
  readonly schedules?: readonly ScheduleDefinition[];
  readonly schedule?: ScheduleDefinition;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L23)

### InngestWorkerHandle (interface)

**Signature**

```ts
export interface InngestWorkerHandle {
  readonly path: string;
  readonly handler: (request: Request) => Promise<Response>;
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L99)

### InngestWorkerOptions (interface)

**Signature**

```ts
export interface InngestWorkerOptions {
  readonly client: Inngest.Any;
  readonly definitions: readonly InngestTaskDefinition[];
  readonly executor: TaskExecutor;
  readonly servePath?: string;
  readonly serveOrigin?: string;
  readonly startWorker?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L88)

### InngestWorkerRegistrationOptions (type alias)

**Signature**

```ts
type InngestWorkerRegistrationOptions = Omit<InngestWorkerOptions, "client">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L97)

### createInngestFunction

**Signature**

```ts
declare const createInngestFunction: (
  client: Inngest.Any,
  definition: InngestTaskDefinition,
  executor: TaskExecutor,
  activeSignals?: Set<AbortController>,
) => InngestFunction.Any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L9)

### createInngestFunctionConfig

**Signature**

```ts
declare const createInngestFunctionConfig: (
  definition: InngestTaskDefinition,
) => Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L39)

### createInngestServeHandler

**Signature**

```ts
declare const createInngestServeHandler: (
  options: InngestWorkerOptions,
  activeSignals?: Set<AbortController>,
) => (request: Request) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L135)

### createInngestWorker

**Signature**

```ts
declare const createInngestWorker: (options: InngestWorkerOptions) => {
  readonly path: string;
  readonly handler: (request: Request) => Promise<Response>;
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L106)

### inngestFunctionId

**Signature**

```ts
declare const inngestFunctionId: (
  jobId: string,
  taskId: string,
  taskVersion: string,
  buildId: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L77)

### loadInngestSdk

**Signature**

```ts
declare const loadInngestSdk: () => InngestSdk;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/inngest/src/runtime/task-binding.ts#L19)

---

# LangChain API
Source: https://relkit.dev/docs/api/integrations/langchain

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [ai](/docs/modules/ai), [tools](/docs/modules/ai/tools), [function tools](/docs/modules/ai/function-tools).

## Frontend usage

[Observe an agent and send controls](/docs/modules/ai/streaming#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/langchain` — 298 exports
- `@relkit/langchain/runtime` — 20 exports
- `@relkit/langchain/continuation-validation` — 3 exports
- `@relkit/langchain/testing` — 19 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                               | Kind  | Import from                                                      | Example                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| [AcceptControlRequest](/docs/api/app#acceptcontrolrequest-interface)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AcceptRunReceipt](/docs/api/app#acceptrunreceipt-interface)                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AcceptRunRequest](/docs/api/app#acceptrunrequest-interface)                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AdmitContinuationRequest](/docs/api/app#admitcontinuationrequest-type-alias)                                     | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AGENT_OBSERVABILITY_PROTOCOL](/docs/api/agents#agent_observability_protocol)                                     | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AGENT_OBSERVABILITY_VERSION](/docs/api/agents#agent_observability_version)                                       | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentApprovalHandler](/docs/api/integrations/langchain#agentapprovalhandler-type-alias)                          | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentCapturePolicy](/docs/api/agents#agentcapturepolicy-interface)                                               | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentcapturepolicy-interface)                                                                                    |
| [AgentCapturePolicyError](/docs/api/agents#agentcapturepolicyerror-class)                                         | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentCaptureRecord](/docs/api/agents#agentcapturerecord-interface)                                               | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentcapturerecord-interface)                                                                                    |
| [AgentChatMapping](/docs/api/agents#agentchatmapping-interface)                                                   | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentchatmapping-interface)                                                                                      |
| [AgentClientEvent](/docs/api/app#agentclientevent-type-alias)                                                     | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L174)                |
| [agentClientEvents](/docs/api/agents#agentclientevents-1)                                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentclientevents-1)                                                                                             |
| [AgentClientEvents](/docs/api/agents#agentclientevents-type-alias)                                                | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentclientevents-type-alias)                                                                                    |
| [agentClientEventsEffect](/docs/api/agents#agentclienteventseffect)                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentclienteventseffect)                                                                                         |
| [AgentClientPolicy](/docs/api/agents#agentclientpolicy-type-alias)                                                | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentclientpolicy-type-alias)                                                                                    |
| [AgentClientPolicyError](/docs/api/agents#agentclientpolicyerror-class)                                           | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentClientStateKey](/docs/api/integrations/langchain#agentclientstatekey-type-alias)                            | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/middleware-state.types.ts#L26)               |
| [AgentContentSink](/docs/api/integrations/langchain#agentcontentsink-interface)                                   | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/fixtures/native-todo.ts#L40)                           |
| [AgentControl](/docs/api/agents#agentcontrol-type-alias)                                                          | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentcontrol-type-alias)                                                                                         |
| [AgentConversationMessage](/docs/api/integrations/langchain#agentconversationmessage-interface)                   | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentDescriptor](/docs/api/integrations/langchain#agentdescriptor-interface)                                     | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentEdgeRelationship](/docs/api/agents#agentedgerelationship-type-alias)                                        | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentedgerelationship-type-alias)                                                                                |
| [AgentExecution](/docs/api/integrations/langchain#agentexecution-class)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#agentexecution-class)                                                                            |
| [AgentExecutionEvent](/docs/api/app#agentexecutionevent-interface)                                                | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L236)                |
| [AgentExecutionLive](/docs/api/integrations/langchain#agentexecutionlive)                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#agentexecutionlive)                                                                              |
| [AgentExecutionService](/docs/api/integrations/langchain#agentexecutionservice-interface)                         | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentExecutionSnapshot](/docs/api/app#agentexecutionsnapshot-interface)                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentFilesystemBackend](/docs/api/integrations/langchain#agentfilesystembackend-type-alias)                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentInstructions](/docs/api/integrations/langchain#agentinstructions-type-alias)                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentInvocationFailure](/docs/api/integrations/langchain#agentinvocationfailure-class)                           | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentInvocationOptions](/docs/api/integrations/langchain#agentinvocationoptions-interface)                       | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentLimits](/docs/api/integrations/langchain#agentlimits-interface)                                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentMiddleware](/docs/api/integrations/langchain#agentmiddleware-type-alias)                                    | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/native-authoring.test.ts#L117)               |
| [AgentMiddlewareState](/docs/api/integrations/langchain#agentmiddlewarestate-type-alias)                          | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/middleware-state.types.ts#L23)               |
| [AgentModel](/docs/api/integrations/langchain#agentmodel-type-alias)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentModelFactory](/docs/api/integrations/langchain#agentmodelfactory-type-alias)                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentObservabilitySink](/docs/api/agents#agentobservabilitysink-interface)                                       | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentobservabilitysink-interface)                                                                                |
| [AgentObservation](/docs/api/app#agentobservation-type-alias)                                                     | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observer.test.ts#L97)                    |
| [AgentObservedEdge](/docs/api/agents#agentobservededge-interface)                                                 | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentobservededge-interface)                                                                                     |
| [AgentOperation](/docs/api/agents#agentoperation-type-alias)                                                      | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentoperation-type-alias)                                                                                       |
| [AgentPersistenceDeclaration](/docs/api/integrations/langchain#agentpersistencedeclaration-interface)             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentProgressEvent](/docs/api/app#agentprogressevent-type-alias)                                                 | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentProgressScope](/docs/api/app#agentprogressscope-type-alias)                                                 | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentRequestScope](/docs/api/app#agentrequestscope-interface)                                                    | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L57)                 |
| [AgentRuntime](/docs/api/integrations/langchain#agentruntime-interface)                                           | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentRuntimeBaseOptions](/docs/api/integrations/langchain#agentruntimebaseoptions-interface)                     | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentRuntimeError](/docs/api/integrations/langchain#agentruntimeerror-class)                                     | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/failure-diagnostics.test.ts#L67)             |
| [AgentRuntimeHooks](/docs/api/agents#agentruntimehooks-interface)                                                 | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentruntimehooks-interface)                                                                                     |
| [AgentRuntimeOptions](/docs/api/integrations/langchain#agentruntimeoptions-type-alias)                            | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/packed-consumer/public-types.fixture.ts#L10) |
| [AgentSpanCapture](/docs/api/agents#agentspancapture-interface)                                                   | Type  | `@relkit/langchain`                                              | [API example](/docs/api/agents#agentspancapture-interface)                                                                                      |
| [AgentStateLimits](/docs/api/app#agentstatelimits-interface)                                                      | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L21)                 |
| [AgentStateProvider](/docs/api/app#agentstateprovider-interface)                                                  | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L57)                         |
| [AgentSteeringSource](/docs/api/integrations/langchain#agentsteeringsource-interface)                             | Type  | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentSubagent](/docs/api/integrations/langchain#agentsubagent-type-alias)                                        | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/native-authoring.test.ts#L129)               |
| [AgentTelemetry](/docs/api/agents#agenttelemetry-class)                                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#agenttelemetry-class)                                                                                            |
| [AgentTelemetryLive](/docs/api/agents#agenttelemetrylive)                                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#agenttelemetrylive)                                                                                              |
| [AgentTelemetryService](/docs/api/agents#agenttelemetryservice-interface)                                         | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentTool](/docs/api/integrations/langchain#agenttool-type-alias)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentToolEvent](/docs/api/app#agenttoolevent-type-alias)                                                         | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentTransitionError](/docs/api/app#agenttransitionerror-type-alias)                                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentWaitingRequest](/docs/api/app#agentwaitingrequest-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AgentWaitingState](/docs/api/app#agentwaitingstate-interface)                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [AppendJournalRequest](/docs/api/app#appendjournalrequest-interface)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [APPROVAL_STATES](/docs/api/agents#approval_states)                                                               | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalDeniedError](/docs/api/agents#approvaldeniederror-class)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#approvaldeniederror-class)                                                                                       |
| [ApprovalEffectError](/docs/api/agents#approvaleffecterror-class)                                                 | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalMetadata](/docs/api/agents#approvalmetadata-interface)                                                   | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalOptions](/docs/api/agents#approvaloptions-interface)                                                     | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalPolicy](/docs/api/agents#approvalpolicy-type-alias)                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalRecord](/docs/api/agents#approvalrecord-type-alias)                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalRequiredError](/docs/api/agents#approvalrequirederror-class)                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#approvalrequirederror-class)                                                                                     |
| [ApprovalSideEffect](/docs/api/agents#approvalsideeffect-type-alias)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalState](/docs/api/agents#approvalstate-type-alias)                                                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ApprovalStateError](/docs/api/agents#approvalstateerror-class)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#approvalstateerror-class)                                                                                        |
| [approveApproval](/docs/api/agents#approveapproval)                                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#approveapproval)                                                                                                 |
| [approveApprovalEffect](/docs/api/agents#approveapprovaleffect)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#approveapprovaleffect)                                                                                           |
| [ApprovedApproval](/docs/api/agents#approvedapproval-interface)                                                   | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [assertAgentDescriptor](/docs/api/integrations/langchain#assertagentdescriptor)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertagentdescriptor)                                                                           |
| [assertAgentRuntimeDependencies](/docs/api/integrations/langchain#assertagentruntimedependencies-1)               | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [assertAgentTrace](/docs/api/integrations/langchain#assertagenttrace)                                             | Value | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [assertApprovalGranted](/docs/api/agents#assertapprovalgranted)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#assertapprovalgranted)                                                                                           |
| [assertApprovalGrantedEffect](/docs/api/agents#assertapprovalgrantedeffect)                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#assertapprovalgrantedeffect)                                                                                     |
| [assertGraphDestination](/docs/api/integrations/langchain#assertgraphdestination)                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertgraphdestination)                                                                          |
| [assertGraphDestinationEffect](/docs/api/integrations/langchain#assertgraphdestinationeffect)                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertgraphdestinationeffect)                                                                    |
| [assertGraphNodeDestinations](/docs/api/integrations/langchain#assertgraphnodedestinations-1)                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertgraphnodedestinations-1)                                                                   |
| [assertPersistenceProtocol](/docs/api/integrations/langchain#assertpersistenceprotocol)                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertpersistenceprotocol)                                                                       |
| [assertPersistenceProtocolEffect](/docs/api/integrations/langchain#assertpersistenceprotocoleffect)               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#assertpersistenceprotocoleffect)                                                                 |
| [BrowserMessage](/docs/api/app#browsermessage-interface)                                                          | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L23)                 |
| [BrowserMessagePart](/docs/api/app#browsermessagepart-type-alias)                                                 | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [captureAgentContent](/docs/api/agents#captureagentcontent)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#captureagentcontent)                                                                                             |
| [captureAgentContentEffect](/docs/api/agents#captureagentcontenteffect)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#captureagentcontenteffect)                                                                                       |
| [CheckpointerResource](/docs/api/integrations/langchain#checkpointerresource-type-alias)                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ClaimControlRequest](/docs/api/app#claimcontrolrequest-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ClaimRunRequest](/docs/api/app#claimrunrequest-interface)                                                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [clientPolicyCount](/docs/api/agents#clientpolicycount)                                                           | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [clientPolicyFailures](/docs/api/agents#clientpolicyfailures)                                                     | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [CompleteRunRequest](/docs/api/app#completerunrequest-interface)                                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [CompletionReceipt](/docs/api/app#completionreceipt-interface)                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ContinuationIdentity](/docs/api/app#continuationidentity-interface)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ContinuationReceipt](/docs/api/app#continuationreceipt-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ContinuationReceiptLookup](/docs/api/app#continuationreceiptlookup-type-alias)                                   | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlClaim](/docs/api/app#controlclaim-interface)                                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlEffectOutcome](/docs/api/app#controleffectoutcome-type-alias)                                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlLimits](/docs/api/app#controllimits-interface)                                                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlPage](/docs/api/app#controlpage-interface)                                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlReceipt](/docs/api/app#controlreceipt-interface)                                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlReceiptLookup](/docs/api/app#controlreceiptlookup-type-alias)                                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlRecord](/docs/api/app#controlrecord-interface)                                                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ControlStatus](/docs/api/app#controlstatus-type-alias)                                                           | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [copyAgentChat](/docs/api/agents#copyagentchat)                                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentchat)                                                                                                   |
| [copyAgentChatEffect](/docs/api/agents#copyagentchateffect)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentchateffect)                                                                                             |
| [copyAgentClientPolicy](/docs/api/agents#copyagentclientpolicy)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentclientpolicy)                                                                                           |
| [copyAgentClientPolicyEffect](/docs/api/agents#copyagentclientpolicyeffect)                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentclientpolicyeffect)                                                                                     |
| [copyAgentControls](/docs/api/agents#copyagentcontrols)                                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentcontrols)                                                                                               |
| [copyAgentControlsEffect](/docs/api/agents#copyagentcontrolseffect)                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentcontrolseffect)                                                                                         |
| [copyAgentLimits](/docs/api/agents#copyagentlimits)                                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentlimits)                                                                                                 |
| [copyAgentLimitsEffect](/docs/api/agents#copyagentlimitseffect)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#copyagentlimitseffect)                                                                                           |
| [createAgentCapturePolicy](/docs/api/agents#createagentcapturepolicy)                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createagentcapturepolicy)                                                                                        |
| [createAgentCapturePolicyEffect](/docs/api/agents#createagentcapturepolicyeffect)                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createagentcapturepolicyeffect)                                                                                  |
| [createAgentRuntime](/docs/api/integrations/langchain#createagentruntime)                                         | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#createagentruntime)                                                                              |
| [createAgentRuntimeEffect](/docs/api/integrations/langchain#createagentruntimeeffect)                             | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#createagentruntimeeffect)                                                                        |
| [createAgentSpanCapture](/docs/api/agents#createagentspancapture)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createagentspancapture)                                                                                          |
| [createAgentSpanCaptureEffect](/docs/api/agents#createagentspancaptureeffect)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createagentspancaptureeffect)                                                                                    |
| [createApproval](/docs/api/agents#createapproval)                                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createapproval)                                                                                                  |
| [createApprovalEffect](/docs/api/agents#createapprovaleffect)                                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#createapprovaleffect)                                                                                            |
| [createGeneratedAgentFunction](/docs/api/agents#creategeneratedagentfunction)                                     | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/agents#creategeneratedagentfunction)                                                                                    |
| [createGeneratedAgentFunctionEffect](/docs/api/agents#creategeneratedagentfunctioneffect)                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#creategeneratedagentfunctioneffect)                                                                              |
| [createGraphEdgeBuilder](/docs/api/integrations/langchain#creategraphedgebuilder)                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#creategraphedgebuilder)                                                                          |
| [createGraphEdgeBuilderEffect](/docs/api/integrations/langchain#creategraphedgebuildereffect)                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#creategraphedgebuildereffect)                                                                    |
| [createSubgraphNode](/docs/api/integrations/langchain#createsubgraphnode)                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#createsubgraphnode)                                                                              |
| [createSubgraphNodeEffect](/docs/api/integrations/langchain#createsubgraphnodeeffect)                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#createsubgraphnodeeffect)                                                                        |
| [createTestAgent](/docs/api/integrations/langchain#createtestagent)                                               | Value | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/owned-compatibility.ts#L71)                        |
| [createTestModel](/docs/api/integrations/langchain#createtestmodel)                                               | Value | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/checked-examples.ts#L33)                           |
| [CreateThreadReceipt](/docs/api/app#createthreadreceipt-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [CreateThreadRequest](/docs/api/app#createthreadrequest-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [decideThreadTransition](/docs/api/agents#decidethreadtransition)                                                 | Value | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L20)               |
| [decideThreadTransitionEffect](/docs/api/agents#decidethreadtransitioneffect)                                     | Value | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L45)               |
| [DeepAgentCapabilities](/docs/api/integrations/langchain#deepagentcapabilities-interface)                         | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [defineAgent](/docs/api/integrations/langchain#defineagent)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#defineagent)                                                                                     |
| [defineAgentEffect](/docs/api/integrations/langchain#defineagenteffect)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#defineagenteffect)                                                                               |
| [DefineAgentOptions](/docs/api/integrations/langchain#defineagentoptions-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [defineCheckpointerDb](/docs/api/integrations/langchain#definecheckpointerdb)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definecheckpointerdb)                                                                            |
| [defineCheckpointerDbEffect](/docs/api/integrations/langchain#definecheckpointerdbeffect)                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definecheckpointerdbeffect)                                                                      |
| [defineGraph](/docs/api/integrations/langchain#definegraph)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definegraph)                                                                                     |
| [defineGraphEffect](/docs/api/integrations/langchain#definegrapheffect)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definegrapheffect)                                                                               |
| [defineGraphNode](/docs/api/integrations/langchain#definegraphnode)                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definegraphnode)                                                                                 |
| [defineGraphNodeEffect](/docs/api/integrations/langchain#definegraphnodeeffect)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definegraphnodeeffect)                                                                           |
| [DefineGraphNodeOptions](/docs/api/integrations/langchain#definegraphnodeoptions-interface)                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [DefineGraphOptions](/docs/api/integrations/langchain#definegraphoptions-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [defineMemoryDb](/docs/api/integrations/langchain#definememorydb)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definememorydb)                                                                                  |
| [defineMemoryDbEffect](/docs/api/integrations/langchain#definememorydbeffect)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#definememorydbeffect)                                                                            |
| [DeniedApproval](/docs/api/agents#deniedapproval-interface)                                                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [denyApproval](/docs/api/agents#denyapproval)                                                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#denyapproval)                                                                                                    |
| [denyApprovalEffect](/docs/api/agents#denyapprovaleffect)                                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#denyapprovaleffect)                                                                                              |
| [emitAgentEdge](/docs/api/agents#emitagentedge)                                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#emitagentedge)                                                                                                   |
| [emitAgentEdgeEffect](/docs/api/agents#emitagentedgeeffect)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#emitagentedgeeffect)                                                                                             |
| [ExecutionClaim](/docs/api/app#executionclaim-interface)                                                          | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state/fixture.ts#L61)                         |
| [GENERATED_AGENT_FUNCTION_PREFIX](/docs/api/agents#generated_agent_function_prefix)                               | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GENERATED_AGENT_FUNCTION_SUFFIX](/docs/api/agents#generated_agent_function_suffix)                               | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GeneratedAgentExecutor](/docs/api/agents#generatedagentexecutor-type-alias)                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GeneratedAgentFunction](/docs/api/agents#generatedagentfunction-type-alias)                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [generatedAgentFunctionId](/docs/api/agents#generatedagentfunctionid)                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#generatedagentfunctionid)                                                                                        |
| [generatedAgentFunctionIdEffect](/docs/api/agents#generatedagentfunctionideffect)                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#generatedagentfunctionideffect)                                                                                  |
| [GeneratedAgentFunctionMarker](/docs/api/agents#generatedagentfunctionmarker-interface)                           | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GeneratedAgentFunctionUnboundError](/docs/api/agents#generatedagentfunctionunbounderror-class)                   | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphAsNodeOptions](/docs/api/integrations/langchain#graphasnodeoptions-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphConditionalRoute](/docs/api/integrations/langchain#graphconditionalroute-type-alias)                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphDescriptor](/docs/api/integrations/langchain#graphdescriptor-interface)                                     | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/graph-continuation-effect.test.ts#L40)       |
| [GraphEdgeBuilder](/docs/api/integrations/langchain#graphedgebuilder-interface)                                   | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/define-graph-effect.test.ts#L27)             |
| [GraphEdgeOperation](/docs/api/integrations/langchain#graphedgeoperation-type-alias)                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [graphExecution](/docs/api/integrations/langchain#graphexecution)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphexecution)                                                                                  |
| [GraphExecution](/docs/api/integrations/langchain#graphexecution-interface)                                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [graphExecutionEffect](/docs/api/integrations/langchain#graphexecutioneffect)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphexecutioneffect)                                                                            |
| [GraphInput](/docs/api/integrations/langchain#graphinput-type-alias)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphInterruptedError](/docs/api/integrations/langchain#graphinterruptederror-class)                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphinterruptederror-class)                                                                     |
| [GraphInvocationFailure](/docs/api/integrations/langchain#graphinvocationfailure-class)                           | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphInvocationIdentity](/docs/api/integrations/langchain#graphinvocationidentity-class)                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphinvocationidentity-class)                                                                   |
| [GraphInvocationIdentityLive](/docs/api/integrations/langchain#graphinvocationidentitylive)                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphinvocationidentitylive)                                                                     |
| [GraphNodeAny](/docs/api/integrations/langchain#graphnodeany-type-alias)                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeDescriptor](/docs/api/integrations/langchain#graphnodedescriptor-interface)                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeHandler](/docs/api/integrations/langchain#graphnodehandler-type-alias)                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeId](/docs/api/integrations/langchain#graphnodeid-type-alias)                                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeImplementation](/docs/api/integrations/langchain#graphnodeimplementation-type-alias)                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeLike](/docs/api/integrations/langchain#graphnodelike-type-alias)                                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphNodeResult](/docs/api/integrations/langchain#graphnoderesult-type-alias)                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphOutput](/docs/api/integrations/langchain#graphoutput-type-alias)                                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphRoute](/docs/api/integrations/langchain#graphroute-type-alias)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphRuntimeOptions](/docs/api/integrations/langchain#graphruntimeoptions-type-alias)                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphState](/docs/api/integrations/langchain#graphstate-type-alias)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphStateKey](/docs/api/integrations/langchain#graphstatekey-type-alias)                                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphWaitingInterrupt](/docs/api/integrations/langchain#graphwaitinginterrupt-interface)                         | Type  | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphwaitinginterrupt-interface)                                                                 |
| [graphWaitingResponse](/docs/api/integrations/langchain#graphwaitingresponse)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphwaitingresponse)                                                                            |
| [graphWaitingResponseEffect](/docs/api/integrations/langchain#graphwaitingresponseeffect)                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphwaitingresponseeffect)                                                                      |
| [GraphWaitingResponseError](/docs/api/integrations/langchain#graphwaitingresponseerror-class)                     | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [graphWorkflow](/docs/api/integrations/langchain#graphworkflow)                                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphworkflow)                                                                                   |
| [GraphWorkflow](/docs/api/integrations/langchain#graphworkflow-interface)                                         | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [GraphWorkflowEdge](/docs/api/integrations/langchain#graphworkflowedge-type-alias)                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [graphWorkflowEffect](/docs/api/integrations/langchain#graphworkfloweffect)                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphworkfloweffect)                                                                             |
| [GraphWorkflowNode](/docs/api/integrations/langchain#graphworkflownode-interface)                                 | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [graphWorkflowRequiresPersistence](/docs/api/integrations/langchain#graphworkflowrequirespersistence)             | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphworkflowrequirespersistence)                                                                |
| [graphWorkflowRequiresPersistenceEffect](/docs/api/integrations/langchain#graphworkflowrequirespersistenceeffect) | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#graphworkflowrequirespersistenceeffect)                                                          |
| [InterruptionReceipt](/docs/api/app#interruptionreceipt-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [InterruptOwnedRunRequest](/docs/api/app#interruptownedrunrequest-interface)                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [invokeAgent](/docs/api/integrations/langchain#invokeagent)                                                       | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#invokeagent)                                                                                     |
| [invokeAgentEffect](/docs/api/integrations/langchain#invokeagenteffect)                                           | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#invokeagenteffect)                                                                               |
| [invokeAgentFunction](/docs/api/integrations/langchain#invokeagentfunction)                                       | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#invokeagentfunction)                                                                             |
| [invokeGraph](/docs/api/integrations/langchain#invokegraph)                                                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#invokegraph)                                                                                     |
| [invokeGraphEffect](/docs/api/integrations/langchain#invokegrapheffect)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#invokegrapheffect)                                                                               |
| [isAgentDescriptor](/docs/api/integrations/langchain#isagentdescriptor)                                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isagentdescriptor)                                                                               |
| [isApprovalRecord](/docs/api/agents#isapprovalrecord)                                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#isapprovalrecord)                                                                                                |
| [isApprovalRecordEffect](/docs/api/agents#isapprovalrecordeffect)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#isapprovalrecordeffect)                                                                                          |
| [isGeneratedAgentFunction](/docs/api/agents#isgeneratedagentfunction)                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#isgeneratedagentfunction)                                                                                        |
| [isGeneratedAgentFunctionEffect](/docs/api/agents#isgeneratedagentfunctioneffect)                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#isgeneratedagentfunctioneffect)                                                                                  |
| [isGraphDescriptor](/docs/api/integrations/langchain#isgraphdescriptor-1)                                         | Value | `@relkit/langchain`, `@relkit/langchain/continuation-validation` | [API example](/docs/api/integrations/langchain#isgraphdescriptor-1)                                                                             |
| [isGraphDescriptorEffect](/docs/api/integrations/langchain#isgraphdescriptoreffect)                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isgraphdescriptoreffect)                                                                         |
| [isGraphInterruptedError](/docs/api/integrations/langchain#isgraphinterruptederror)                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isgraphinterruptederror)                                                                         |
| [isGraphInterruptedErrorEffect](/docs/api/integrations/langchain#isgraphinterruptederroreffect)                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isgraphinterruptederroreffect)                                                                   |
| [isGraphNodeDescriptor](/docs/api/integrations/langchain#isgraphnodedescriptor)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isgraphnodedescriptor)                                                                           |
| [isGraphNodeDescriptorEffect](/docs/api/integrations/langchain#isgraphnodedescriptoreffect)                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#isgraphnodedescriptoreffect)                                                                     |
| [isPersistenceResource](/docs/api/integrations/langchain#ispersistenceresource)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#ispersistenceresource)                                                                           |
| [isPersistenceResourceEffect](/docs/api/integrations/langchain#ispersistenceresourceeffect)                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#ispersistenceresourceeffect)                                                                     |
| [isSubgraphNode](/docs/api/integrations/langchain#issubgraphnode)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#issubgraphnode)                                                                                  |
| [isSubgraphNodeEffect](/docs/api/integrations/langchain#issubgraphnodeeffect)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#issubgraphnodeeffect)                                                                            |
| [JournalCheckpoint](/docs/api/app#journalcheckpoint-interface)                                                    | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-observation.test.ts#L13)                 |
| [JournalPage](/docs/api/app#journalpage-interface)                                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [JournalReceipt](/docs/api/app#journalreceipt-interface)                                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [JournalRecord](/docs/api/app#journalrecord-interface)                                                            | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L100)                                  |
| [ListThreadsRequest](/docs/api/app#listthreadsrequest-interface)                                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [LoadThreadRequest](/docs/api/app#loadthreadrequest-interface)                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [LookupContinuationReceiptRequest](/docs/api/app#lookupcontinuationreceiptrequest-interface)                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [LookupControlReceiptRequest](/docs/api/app#lookupcontrolreceiptrequest-interface)                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [LookupRunReceiptRequest](/docs/api/app#lookuprunreceiptrequest-interface)                                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [MarkControlEffectStartedRequest](/docs/api/app#markcontroleffectstartedrequest-interface)                        | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [MemoryResource](/docs/api/integrations/langchain#memoryresource-type-alias)                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ModelProviderConfiguration](/docs/api/agents#modelproviderconfiguration-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ModelSelectionEffectError](/docs/api/agents#modelselectioneffecterror-class)                                     | Value | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ModelSelectionError](/docs/api/agents#modelselectionerror-class)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#modelselectionerror-class)                                                                                       |
| [ModelSelectionErrorCode](/docs/api/agents#modelselectionerrorcode-type-alias)                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [NativeAgentTool](/docs/api/integrations/langchain#nativeagenttool-type-alias)                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [normalizeModelSelector](/docs/api/agents#normalizemodelselector)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#normalizemodelselector)                                                                                          |
| [normalizeModelSelectorEffect](/docs/api/agents#normalizemodelselectoreffect)                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#normalizemodelselectoreffect)                                                                                    |
| [observeAgent](/docs/api/agents#observeagent)                                                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#observeagent)                                                                                                    |
| [parseModelProviderConfiguration](/docs/api/agents#parsemodelproviderconfiguration)                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#parsemodelproviderconfiguration)                                                                                 |
| [parseModelProviderConfigurationEffect](/docs/api/agents#parsemodelproviderconfigurationeffect)                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#parsemodelproviderconfigurationeffect)                                                                           |
| [PendingApproval](/docs/api/agents#pendingapproval-interface)                                                     | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/agent-approval.fixture.ts#L40)                         |
| [PersistenceContext](/docs/api/integrations/langchain#persistencecontext-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [PersistenceOptions](/docs/api/integrations/langchain#persistenceoptions-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [PersistenceResource](/docs/api/integrations/langchain#persistenceresource-interface)                             | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [PromptInstructions](/docs/api/integrations/langchain#promptinstructions-interface)                               | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [PromptTemplate](/docs/api/integrations/langchain#prompttemplate-interface)                                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [publicWaitingRequests](/docs/api/integrations/langchain#publicwaitingrequests)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#publicwaitingrequests)                                                                           |
| [publicWaitingRequestsEffect](/docs/api/integrations/langchain#publicwaitingrequestseffect)                       | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#publicwaitingrequestseffect)                                                                     |
| [ReadControlsRequest](/docs/api/app#readcontrolsrequest-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ReadJournalRequest](/docs/api/app#readjournalrequest-interface)                                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ReadSnapshotHistoryRequest](/docs/api/app#readsnapshothistoryrequest-interface)                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [RecoverAbandonedControlRequest](/docs/api/app#recoverabandonedcontrolrequest-interface)                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [releaseAgentPersistence](/docs/api/integrations/langchain#releaseagentpersistence)                               | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [API example](/docs/api/integrations/langchain#releaseagentpersistence)                                                                         |
| [releaseAgentPersistenceEffect](/docs/api/integrations/langchain#releaseagentpersistenceeffect)                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#releaseagentpersistenceeffect)                                                                   |
| [RenewControlClaimRequest](/docs/api/app#renewcontrolclaimrequest-interface)                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [RenewRunClaimRequest](/docs/api/app#renewrunclaimrequest-interface)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [requiresApproval](/docs/api/agents#requiresapproval)                                                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#requiresapproval)                                                                                                |
| [requiresApprovalEffect](/docs/api/agents#requiresapprovaleffect)                                                 | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#requiresapprovaleffect)                                                                                          |
| [resolveAgentPersistence](/docs/api/integrations/langchain#resolveagentpersistence)                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#resolveagentpersistence)                                                                         |
| [resolveAgentPersistenceEffect](/docs/api/integrations/langchain#resolveagentpersistenceeffect)                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#resolveagentpersistenceeffect)                                                                   |
| [ResolvedGraphPersistence](/docs/api/integrations/langchain#resolvedgraphpersistence-interface)                   | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ResolvedModelSelection](/docs/api/agents#resolvedmodelselection-interface)                                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [resolveGraphPersistence](/docs/api/integrations/langchain#resolvegraphpersistence)                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#resolvegraphpersistence)                                                                         |
| [resolveGraphPersistenceEffect](/docs/api/integrations/langchain#resolvegraphpersistenceeffect)                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#resolvegraphpersistenceeffect)                                                                   |
| [resolveModelSelector](/docs/api/agents#resolvemodelselector)                                                     | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#resolvemodelselector)                                                                                            |
| [resolveModelSelectorEffect](/docs/api/agents#resolvemodelselectoreffect)                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/agents#resolvemodelselectoreffect)                                                                                      |
| [runAgent](/docs/api/integrations/langchain#runagent)                                                             | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [runGraphNodeHandlerEffect](/docs/api/integrations/langchain#rungraphnodehandlereffect)                           | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#rungraphnodehandlereffect)                                                                       |
| [RunOwner](/docs/api/app#runowner-interface)                                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [RunReceiptLookup](/docs/api/app#runreceiptlookup-type-alias)                                                     | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [RunStatus](/docs/api/app#runstatus-type-alias)                                                                   | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [runtimeIntegration](/docs/api/integrations/langchain#runtimeintegration)                                         | Value | `@relkit/langchain`, `@relkit/langchain/runtime`                 | [Module example](/docs/modules/ai)                                                                                                              |
| [SettleControlRequest](/docs/api/app#settlecontrolrequest-interface)                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [SnapshotHistoryPage](/docs/api/app#snapshothistorypage-interface)                                                | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [StoredApproval](/docs/api/app#storedapproval-interface)                                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [StoredRun](/docs/api/app#storedrun-interface)                                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [StoredRunRouting](/docs/api/app#storedrunrouting-interface)                                                      | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [StoredThread](/docs/api/app#storedthread-interface)                                                              | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [subgraphForNode](/docs/api/integrations/langchain#subgraphfornode)                                               | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#subgraphfornode)                                                                                 |
| [subgraphForNodeEffect](/docs/api/integrations/langchain#subgraphfornodeeffect)                                   | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#subgraphfornodeeffect)                                                                           |
| [SubgraphNodeDescriptor](/docs/api/integrations/langchain#subgraphnodedescriptor-interface)                       | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [SuspendRunRequest](/docs/api/app#suspendrunrequest-interface)                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [SuspensionReceipt](/docs/api/app#suspensionreceipt-interface)                                                    | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgent](/docs/api/integrations/langchain#testagent-interface)                                                 | Type  | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/native-authoring.test.ts#L55)                |
| [TestAgentApproval](/docs/api/integrations/langchain#testagentapproval-type-alias)                                | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentApprovalMode](/docs/api/integrations/langchain#testagentapprovalmode-type-alias)                        | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentApprovals](/docs/api/integrations/langchain#testagentapprovals-interface)                               | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentDescriptor](/docs/api/integrations/langchain#testagentdescriptor-type-alias)                            | Type  | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/native-authoring.test.ts#L54)                |
| [TestAgentHarness](/docs/api/integrations/langchain#testagentharness-class)                                       | Value | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentInvocationOptions](/docs/api/integrations/langchain#testagentinvocationoptions-type-alias)              | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [testAgentLayer](/docs/api/integrations/langchain#testagentlayer)                                                 | Value | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentModel](/docs/api/integrations/langchain#testagentmodel-interface)                                       | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentModelCall](/docs/api/integrations/langchain#testagentmodelcall-interface)                               | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentModelOptions](/docs/api/integrations/langchain#testagentmodeloptions-interface)                         | Type  | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/agent-matrix-helpers.ts#L123)                 |
| [TestAgentOptions](/docs/api/integrations/langchain#testagentoptions-interface)                                   | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentTrace](/docs/api/integrations/langchain#testagenttrace-interface)                                       | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentTraceExpectation](/docs/api/integrations/langchain#testagenttraceexpectation-interface)                 | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestAgentTraceSnapshot](/docs/api/integrations/langchain#testagenttracesnapshot-interface)                       | Type  | `@relkit/langchain/testing`                                      | [Module example](/docs/modules/ai)                                                                                                              |
| [TestModelTurn](/docs/api/integrations/langchain#testmodelturn-type-alias)                                        | Type  | `@relkit/langchain/testing`                                      | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/agent-matrix-helpers.ts#L101)                 |
| [ThreadAction](/docs/api/app#threadaction-type-alias)                                                             | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L15)               |
| [ThreadList](/docs/api/app#threadlist-interface)                                                                  | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ThreadListItem](/docs/api/app#threadlistitem-interface)                                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ThreadSnapshot](/docs/api/app#threadsnapshot-interface)                                                          | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/agent-continuation.test.ts#L127)               |
| [ThreadStatus](/docs/api/app#threadstatus-type-alias)                                                             | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/thread-transition.test.ts#L8)                |
| [ThreadTransition](/docs/api/app#threadtransition-type-alias)                                                     | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [ToolPartState](/docs/api/app#toolpartstate-type-alias)                                                           | Type  | `@relkit/langchain`                                              | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/agents/tests/client-events.test.ts#L12)                                   |
| [validateGraphResumeInput](/docs/api/integrations/langchain#validategraphresumeinput-1)                           | Value | `@relkit/langchain`, `@relkit/langchain/continuation-validation` | [API example](/docs/api/integrations/langchain#validategraphresumeinput-1)                                                                      |
| [validateGraphRoute](/docs/api/integrations/langchain#validategraphroute)                                         | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#validategraphroute)                                                                              |
| [validateGraphRouteEffect](/docs/api/integrations/langchain#validategraphrouteeffect)                             | Value | `@relkit/langchain`                                              | [API example](/docs/api/integrations/langchain#validategraphrouteeffect)                                                                        |
| [validateNativeAgentResumeInput](/docs/api/integrations/langchain#validatenativeagentresumeinput-2)               | Value | `@relkit/langchain`, `@relkit/langchain/continuation-validation` | [API example](/docs/api/integrations/langchain#validatenativeagentresumeinput-2)                                                                |
| [WaitForControlsRequest](/docs/api/app#waitforcontrolsrequest-interface)                                          | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |
| [WaitForJournalRequest](/docs/api/app#waitforjournalrequest-interface)                                            | Type  | `@relkit/langchain`                                              | [Module example](/docs/modules/ai)                                                                                                              |

## `client-contract-metadata.ts`

Projects native agent and graph schemas into serializable client metadata; SDK-specific inspection remains inside this integration before the generic contract is published.

### "./client-contract-metadata.types.js" (namespace export)

Re-exports all named exports from the "./client-contract-metadata.types.js" module.

**Signature**

```ts
export * from "./client-contract-metadata.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.ts#L28)

### agentClientContractMetadata

Builds native agent metadata for existing synchronous callers.

**Throws**

The original invalid metadata error.

**Example**

```ts
agentClientContractMetadata(options);
```

**Signature**

```ts
declare const agentClientContractMetadata: (
  options: AgentClientMetadataOptions,
) => AgentClientContractMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.ts#L50)

### agentClientContractMetadataEffect

Builds client contract metadata for a native agent.

**Example**

```ts
Effect.runSync(agentClientContractMetadataEffect(options));
```

**Signature**

```ts
declare const agentClientContractMetadataEffect: (
  options: AgentClientMetadataOptions,
) => Effect.Effect<AgentClientContractMetadata, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.ts#L35)

### graphClientContractMetadata

Builds graph metadata for existing synchronous callers.

**Throws**

The original invalid graph metadata error.

**Example**

```ts
graphClientContractMetadata(options);
```

**Signature**

```ts
declare const graphClientContractMetadata: (
  options: GraphClientMetadataOptions,
) => AgentClientContractMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.ts#L103)

### graphClientContractMetadataEffect

Builds client contract metadata for a native graph.

**Example**

```ts
Effect.runSync(graphClientContractMetadataEffect(options));
```

**Signature**

```ts
declare const graphClientContractMetadataEffect: (
  options: GraphClientMetadataOptions,
) => Effect.Effect<AgentClientContractMetadata, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.ts#L88)

## `client-contract-metadata.types.ts`

Projects native agent and graph schemas into serializable client metadata; SDK-specific inspection remains inside this integration before the generic contract is published. This companion preserves the native input and output types without starting runtime work.

### AgentClientContractMetadata (interface)

Complete metadata needed to generate an agent client contract.

**Signature**

```ts
export interface AgentClientContractMetadata {
  readonly tools: readonly ClientToolMetadata[];
  readonly state: readonly ClientTypeField[];
  readonly events: readonly ClientEventMetadata[];
  readonly scopes: readonly ClientScopeMetadata[];
  readonly waiting: readonly ClientWaitingMetadata[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L33)

### AgentClientMetadataOptions (interface)

Inputs for native agent client metadata.

**Signature**

```ts
export interface AgentClientMetadataOptions {
  readonly id: string;
  readonly tools: readonly AgentTool[];
  readonly middleware: readonly AgentMiddleware[];
  readonly client?: AgentClientPolicy;
  readonly subagents?: readonly SubagentMetadataSource[];
  readonly interruptOn?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L48)

### ClientEventMetadata (type alias)

Client visible event schema or dynamic event marker.

**Signature**

```ts
type ClientEventMetadata = ClientTypeField | { readonly kind: "dynamic" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L9)

### ClientScopeMetadata (interface)

Client visible agent, subagent, or graph node scope.

**Signature**

```ts
export interface ClientScopeMetadata {
  readonly kind: "agent" | "subagent" | "node" | "dynamic";
  readonly id?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L21)

### ClientToolMetadata (type alias)

Client visible tool schema or dynamic tool marker.

**Signature**

```ts
type ClientToolMetadata =
  | {
      readonly id: string;
      readonly input: ClientSchemaMetadata;
      readonly output: ClientSchemaMetadata;
    }
  | { readonly kind: "dynamic" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L12)

### ClientWaitingMetadata (interface)

Client visible continuation response schema.

**Signature**

```ts
export interface ClientWaitingMetadata {
  readonly scope: ClientScopeMetadata;
  readonly response: ClientSchemaMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L27)

### GraphClientMetadataOptions (interface)

Inputs for graph client metadata.

**Signature**

```ts
export interface GraphClientMetadataOptions {
  readonly id: string;
  readonly state: { readonly getJsonSchema: () => unknown };
  readonly client?: AgentClientPolicy;
  readonly workflow: GraphWorkflow;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L58)

### SubagentMetadataSource (interface)

Source of nested subagent scope identities.

**Signature**

```ts
export interface SubagentMetadataSource {
  readonly id: string;
  readonly subagents?: readonly SubagentMetadataSource[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-metadata.types.ts#L42)

## `client-contract-schema.ts`

Inspects native schema adapters to describe client-visible inputs and outputs; unsupported shapes produce the existing contract errors before execution.

### ClientSchemaMetadata

**Signature**

```ts
declare const ClientSchemaMetadata: ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L13)

### ClientTypeField

**Signature**

```ts
declare const ClientTypeField: ClientTypeField;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L14)

### clientSchemaMetadata

Synchronously projects schema metadata for existing descriptor callers.

**Example**

```ts
const metadata = clientSchemaMetadata({ type: "string" });
```

**Signature**

```ts
declare const clientSchemaMetadata: (value: unknown) => ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L144)

### clientSchemaMetadataEffect

Projects a schema-like value to safe client metadata.

**Example**

```ts
const metadata = Effect.runSync(clientSchemaMetadataEffect({ type: "string" }));
```

**Signature**

```ts
declare const clientSchemaMetadataEffect: (
  value: unknown,
) => Effect.Effect<ClientSchemaMetadata, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L120)

### dynamicClientSchema

Marker for a schema that cannot be represented in the client contract.

**Signature**

```ts
declare const dynamicClientSchema: Readonly<{ kind: "dynamic" }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L18)

### mergeClientSchemas

Synchronously merges client schemas for existing descriptor callers.

**Example**

```ts
const schema = mergeClientSchemas([{ type: "object" }]);
```

**Signature**

```ts
declare const mergeClientSchemas: (values: readonly unknown[]) => ClientSchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L58)

### mergeClientSchemasEffect

Merges projected object schemas while preserving input order.

**Example**

```ts
const schema = Effect.runSync(mergeClientSchemasEffect([{ type: "object" }]));
```

**Signature**

```ts
declare const mergeClientSchemasEffect: (
  values: ReadonlyArray<unknown>,
) => Effect.Effect<JsonValue, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L32)

### selectedClientFields

Synchronously selects client fields for existing descriptor callers.

**Example**

```ts
const fields = selectedClientFields({ type: "object" }, ["name"]);
```

**Signature**

```ts
declare const selectedClientFields: (
  schema: ClientSchemaMetadata,
  keys?: readonly string[],
) => readonly ClientTypeField[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L105)

### selectedClientFieldsEffect

Selects named client state fields from a projected object schema.

**Example**

```ts
const fields = Effect.runSync(selectedClientFieldsEffect({ type: "object" }, ["name"]));
```

**Signature**

```ts
declare const selectedClientFieldsEffect: (
  schema: ClientSchemaMetadata,
  keys?: ReadonlyArray<string> | undefined,
) => Effect.Effect<ReadonlyArray<ClientTypeField>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/client-contract-schema.ts#L71)

## `continuation-validation.ts`

Exposes graph identity and continuation validators to transport adapters without
importing the agent execution barrel. Validation remains owned by its existing
implementations and preserves their public failure and reply contracts.

### isGraphDescriptor

**Signature**

```ts
declare const isGraphDescriptor: (value: unknown) => value is GraphDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/continuation-validation.ts#L6)

### validateGraphResumeInput

**Signature**

```ts
declare const validateGraphResumeInput: (
  descriptor: GraphDescriptor,
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/continuation-validation.ts#L7)

### validateNativeAgentResumeInput

**Signature**

```ts
declare const validateNativeAgentResumeInput: (
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/continuation-validation.ts#L8)

## `deepagent-bucket-backend.ts`

Adapts a configured RELKIT bucket to the DeepAgents file backend, sharing the invocation scope and preserving bucket failures at the native adapter.

### DeepAgentBucketBackendOptions

**Signature**

```ts
declare const DeepAgentBucketBackendOptions: DeepAgentBucketBackendOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-backend.ts#L18)

### createDeepAgentBucketBackend

Creates a backend for existing synchronous callers.

**Throws**

The original invalid bucket or prefix error.

**Example**

```ts
const backend = createDeepAgentBucketBackend(bucket);
```

**Signature**

```ts
declare const createDeepAgentBucketBackend: (
  bucket: DeepAgentBucketClient,
  options?: DeepAgentBucketBackendOptions,
) => BackendProtocolV2;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-backend.ts#L62)

### createDeepAgentBucketBackendEffect

Builds a DeepAgents backend from a RELKIT bucket client.

**Example**

```ts
Effect.runSync(createDeepAgentBucketBackendEffect(bucket));
```

**Signature**

```ts
declare const createDeepAgentBucketBackendEffect: (
  bucket: DeepAgentBucketClient,
  options?: DeepAgentBucketBackendOptions | undefined,
) => Effect.Effect<
  Readonly<{
    ls: (path: string) => Promise<LsResult>;
    read: (path: string, offset?: number, limit?: number) => Promise<ReadResult>;
    readRaw: (path: string) => Promise<ReadRawResult>;
    write: (path: string, content: string) => Promise<WriteResult>;
    edit: (
      path: string,
      oldText: string,
      newText: string,
      replaceAll?: boolean,
    ) => Promise<EditResult>;
    grep: (
      pattern: string,
      path?: string | null,
      glob?: string | null,
      maxCount?: number | null,
    ) => Promise<GrepResult>;
    glob: (pattern: string, path?: string) => Promise<GlobResult>;
    delete: (path: string) => Promise<DeleteResult>;
    uploadFiles: (files: Array<[string, Uint8Array]>) => Promise<Array<FileUploadResponse>>;
    downloadFiles: (paths: string[]) => Promise<Array<FileDownloadResponse>>;
  }>,
  DeepAgentBucketFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-backend.ts#L26)

## `deepagent-bucket-backend.types.ts`

Configuration for a DeepAgents backend bound to a RELKIT bucket.

### DeepAgentBucketBackendOptions (interface)

Configuration for a DeepAgents backend bound to a RELKIT bucket.

**Signature**

```ts
export interface DeepAgentBucketBackendOptions {
  /** Key prefix owned by this backend instance. */
  readonly prefix?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-backend.types.ts#L2)

## `deepagent-bucket-client.types.ts`

Bucket client and prefix bound to one DeepAgents backend.

### DeepAgentBucketClient (interface)

IO operations required by the DeepAgents bucket bridge.

**Signature**

```ts
export interface DeepAgentBucketClient {
  readonly put: (
    key: string,
    bytes: Uint8Array,
    options?: {
      readonly contentType?: string;
      readonly metadata?: Readonly<Record<string, string>>;
    },
  ) => Promise<void>;
  readonly get: (key: string) => Promise<Uint8Array | undefined>;
  readonly head: (key: string) => Promise<DeepAgentBucketMetadata | undefined>;
  readonly delete: (key: string) => Promise<void>;
  readonly exists: (key: string) => Promise<boolean>;
  readonly list: (prefix?: string) => Promise<readonly string[]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-client.types.ts#L17)

### DeepAgentBucketContext (interface)

Bucket client and prefix bound to one DeepAgents backend.

**Signature**

```ts
export interface DeepAgentBucketContext {
  readonly bucket: DeepAgentBucketClient;
  readonly prefix: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-client.types.ts#L4)

### DeepAgentBucketMetadata (interface)

Metadata needed to expose a bucket object as a virtual file.

**Signature**

```ts
export interface DeepAgentBucketMetadata {
  readonly contentType?: string;
  readonly size?: number;
  readonly metadata?: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-client.types.ts#L10)

## `deepagent-bucket-delete.ts`

Deletes normalized DeepAgents file paths through the selected bucket service and reports native file-operation results without changing unrelated keys.

### removeBucketPath

Removes a bucket path for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await removeBucketPath(context, "/notes");
```

**Signature**

```ts
declare const removeBucketPath: (
  context: DeepAgentBucketContext,
  path: string,
) => Promise<DeleteResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-delete.ts#L63)

### removeBucketPathEffect

Removes a virtual file or directory with at most eight bucket requests in flight.

**Example**

```ts
Effect.runPromise(Effect.provide(removeBucketPathEffect("/notes"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const removeBucketPathEffect: (
  path: string,
) => Effect.Effect<
  | { error: string; path?: never; filesUpdate?: never }
  | { path: string; filesUpdate: null; error?: never },
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-delete.ts#L21)

## `deepagent-bucket-error.ts`

Translates bucket operation failures into the DeepAgents backend error format while retaining the affected operation and path.

### DeepAgentBucketFailure (class)

Typed bucket validation or IO failure for DeepAgents operations.

**Signature**

```ts
declare class DeepAgentBucketFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-error.ts#L6)

### deepAgentBucketFailure

Captures a bucket error while preserving its original cause.

**Example**

```ts
deepAgentBucketFailure(new Error("not found"));
```

**Signature**

```ts
declare const deepAgentBucketFailure: (cause: unknown) => DeepAgentBucketFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-error.ts#L16)

## `deepagent-bucket-file-data.ts`

Encodes and decodes DeepAgents file records stored in bucket objects, preserving file content and timestamps across backend operations.

### putFileData

Writes a file for existing Promise callers.

**Throws**

The original bucket or path failure.

**Example**

```ts
await putFileData(context, "/a.md", "hi");
```

**Signature**

```ts
declare const putFileData: (
  context: DeepAgentBucketContext,
  path: string,
  content: string | Uint8Array,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-data.ts#L108)

### putFileDataEffect

Writes file content with timestamps from the Effect clock.

**Example**

```ts
Effect.runPromise(Effect.provide(putFileDataEffect("/a.md", "hi"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const putFileDataEffect: (
  path: string,
  content: string | Uint8Array<ArrayBufferLike>,
) => Effect.Effect<void, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-data.ts#L68)

### readFileData

Reads a file for existing Promise callers.

**Throws**

The original bucket or path failure.

**Example**

```ts
await readFileData(context, "/a.md");
```

**Signature**

```ts
declare const readFileData: (
  context: DeepAgentBucketContext,
  path: string,
) => Promise<DeepAgentBucketFileData | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-data.ts#L50)

### readFileDataEffect

Reads bytes and metadata together from the current bucket service.

**Example**

```ts
Effect.runPromise(Effect.provide(readFileDataEffect("/a.md"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const readFileDataEffect: (path: string) => Effect.Effect<
  | {
      content: string | Uint8Array<ArrayBufferLike>;
      mimeType: string;
      created_at: string;
      modified_at: string;
    }
  | undefined,
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-data.ts#L19)

## `deepagent-bucket-file-index.ts`

Maintains the invocation file index used by bucket-backed listing and lookup; reads and mutations share the same backend state.

### infoFor

Reads metadata for existing Promise callers.

**Throws**

The original bucket or path failure.

**Example**

```ts
await infoFor(context, "deepagents/a.md");
```

**Signature**

```ts
declare const infoFor: (
  context: DeepAgentBucketContext,
  key: string,
) => Promise<FileInfo | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-index.ts#L98)

### infoForEffect

Reads metadata for one bucket key.

**Example**

```ts
Effect.runPromise(Effect.provide(infoForEffect("deepagents/a.md"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const infoForEffect: (
  key: string,
) => Effect.Effect<FileInfo | undefined, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-index.ts#L68)

### scopedKeys

Lists keys for existing Promise callers.

**Throws**

The original bucket or path failure.

**Example**

```ts
await scopedKeys(context, "/notes");
```

**Signature**

```ts
declare const scopedKeys: (
  context: DeepAgentBucketContext,
  path: string | null | undefined,
) => Promise<readonly string[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-index.ts#L51)

### scopedKeysEffect

Lists sorted keys in a virtual file or directory.

**Example**

```ts
Effect.runPromise(Effect.provide(scopedKeysEffect("/notes"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const scopedKeysEffect: (
  path: string | null | undefined,
) => Effect.Effect<Array<string>, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-file-index.ts#L19)

## `deepagent-bucket-files.ts`

Collects bucket-backed file entries for native filesystem operations after path normalization, keeping metadata separate from fetched file content.

### "./deepagent-bucket-files.types.js" (namespace export)

Re-exports all named exports from the "./deepagent-bucket-files.types.js" module.

**Signature**

```ts
export * from "./deepagent-bucket-files.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L3)

### bucketKey

**Signature**

```ts
declare const bucketKey: (context: DeepAgentBucketContext, path: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L5)

### bucketKeyEffect

**Signature**

```ts
declare const bucketKeyEffect: (
  context: DeepAgentBucketContext,
  path: string,
) => Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L6)

### createBucketContext

**Signature**

```ts
declare const createBucketContext: (
  bucket: DeepAgentBucketClient,
  prefix?: string,
) => DeepAgentBucketContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L7)

### createBucketContextEffect

**Signature**

```ts
declare const createBucketContextEffect: (
  bucket: DeepAgentBucketClient,
  prefix?: any,
) => Effect<
  Readonly<{ bucket: DeepAgentBucketClient; prefix: string }>,
  DeepAgentBucketFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L8)

### errorMessage

**Signature**

```ts
declare const errorMessage: (cause: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L15)

### errorMessageEffect

**Signature**

```ts
declare const errorMessageEffect: (cause: unknown) => Effect<string, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L16)

### filePath

**Signature**

```ts
declare const filePath: (context: DeepAgentBucketContext, key: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L9)

### filePathEffect

**Signature**

```ts
declare const filePathEffect: (
  context: DeepAgentBucketContext,
  key: string,
) => Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L10)

### isControlFailure

**Signature**

```ts
declare const isControlFailure: (cause: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L17)

### isControlFailureEffect

**Signature**

```ts
declare const isControlFailureEffect: (cause: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L18)

### isTextMimeType

**Signature**

```ts
declare const isTextMimeType: (mimeType: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L19)

### isTextMimeTypeEffect

**Signature**

```ts
declare const isTextMimeTypeEffect: (mimeType: string) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L20)

### normalizedPage

**Signature**

```ts
declare const normalizedPage: (
  offset?: number,
  limit?: number,
) => { offset: number; limit: number };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L21)

### normalizedPageEffect

**Signature**

```ts
declare const normalizedPageEffect: (
  offset: number,
  limit: number,
) => Effect<{ offset: number; limit: number }, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L22)

### virtualPath

**Signature**

```ts
declare const virtualPath: (value: string, directory?: boolean) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L11)

### virtualPathEffect

**Signature**

```ts
declare const virtualPathEffect: (
  value: string,
  directory?: any,
) => Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.ts#L12)

## `deepagent-bucket-files.types.ts`

Collects bucket-backed file entries for native filesystem operations after path normalization, keeping metadata separate from fetched file content. This companion preserves the native input and output types without starting runtime work.

### "./deepagent-bucket-client.types.js" (namespace export)

Re-exports all named exports from the "./deepagent-bucket-client.types.js" module.

**Signature**

```ts
export * from "./deepagent-bucket-client.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.types.ts#L4)

### DeepAgentBucketFileData (type alias)

DeepAgents file payload that carries a concrete MIME type.

**Signature**

```ts
type DeepAgentBucketFileData = Extract<FileData, { readonly mimeType: string }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-files.types.ts#L7)

## `deepagent-bucket-format.ts`

Formats bucket file records into the native DeepAgents listing and content shapes consumed by backend callers.

### errorMessage

Reads a failure message for existing synchronous callers.

**Example**

```ts
errorMessage(error);
```

**Signature**

```ts
declare const errorMessage: (cause: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L76)

### errorMessageEffect

Reads a failure message without requiring an Error instance.

**Example**

```ts
Effect.runSync(errorMessageEffect(error));
```

**Signature**

```ts
declare const errorMessageEffect: (cause: unknown) => Effect.Effect<string, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L66)

### isControlFailure

Classifies a control failure for existing synchronous callers.

**Example**

```ts
isControlFailure(error);
```

**Signature**

```ts
declare const isControlFailure: (cause: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L57)

### isControlFailureEffect

Classifies cancellation and timeout control failures.

**Example**

```ts
Effect.runSync(isControlFailureEffect(error));
```

**Signature**

```ts
declare const isControlFailureEffect: (cause: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L38)

### isTextMimeType

Checks a text MIME type for existing synchronous callers.

**Example**

```ts
isTextMimeType("text/plain");
```

**Signature**

```ts
declare const isTextMimeType: (mimeType: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L96)

### isTextMimeTypeEffect

Checks whether a MIME type should be decoded as text.

**Example**

```ts
Effect.runSync(isTextMimeTypeEffect("text/plain"));
```

**Signature**

```ts
declare const isTextMimeTypeEffect: (mimeType: string) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L85)

### normalizedPage

Normalizes paging for existing synchronous callers.

**Example**

```ts
normalizedPage(0, 500);
```

**Signature**

```ts
declare const normalizedPage: (
  offset?: number,
  limit?: number,
) => { offset: number; limit: number };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L29)

### normalizedPageEffect

Normalizes paging arguments to nonnegative integers.

**Example**

```ts
Effect.runSync(normalizedPageEffect(0, 500));
```

**Signature**

```ts
declare const normalizedPageEffect: (
  offset: number,
  limit: number,
) => Effect.Effect<{ offset: number; limit: number }, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-format.ts#L14)

## `deepagent-bucket-glob.ts`

Matches normalized bucket paths against DeepAgents glob patterns so search traverses only the backend's visible file namespace.

### compileGlob

Validates and normalizes a user glob without changing match semantics.

**Signature**

```ts
declare const compileGlob: (pattern: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-glob.ts#L87)

### globFiles

Finds files for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await globFiles(context, "*.md", "/notes");
```

**Signature**

```ts
declare const globFiles: (
  context: DeepAgentBucketContext,
  pattern: string,
  path?: string,
) => Promise<GlobResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-glob.ts#L69)

### globFilesEffect

Finds matching bucket files and orders them by modification time.

**Example**

```ts
Effect.runPromise(Effect.provide(globFilesEffect("*.md"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const globFilesEffect: (
  pattern: string,
  path?: any,
) => Effect.Effect<{ files: Array<FileInfo> }, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-glob.ts#L24)

## `deepagent-bucket-grep.ts`

Searches bucket file content for native grep requests and projects matching lines into DeepAgents results.

### grepFiles

Searches text files for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await grepFiles(context, "TODO", "/notes", "*.md", 10);
```

**Signature**

```ts
declare const grepFiles: (
  context: DeepAgentBucketContext,
  pattern: string,
  path?: string | null,
  globPattern?: string | null,
  maxCount?: number | null,
) => Promise<GrepResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-grep.ts#L85)

### grepFilesEffect

Searches text files in key order and stops as soon as the match cap is exceeded.

**Example**

```ts
Effect.runPromise(Effect.provide(grepFilesEffect("TODO"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const grepFilesEffect: (
  pattern: string,
  path?: string | null | undefined,
  globPattern?: string | null | undefined,
  maxCount?: number | null | undefined,
) => Effect.Effect<
  | { matches: Array<GrepMatch>; truncated: boolean }
  | { matches: Array<GrepMatch>; truncated?: never },
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-grep.ts#L28)

## `deepagent-bucket-path.ts`

Normalizes native file paths into scoped bucket keys and rejects paths that would escape the configured backend prefix.

### bucketKey

Converts a virtual path to a bucket key for synchronous callers.

**Throws**

The original invalid path error.

**Example**

```ts
bucketKey(context, "/readme.md");
```

**Signature**

```ts
declare const bucketKey: (context: DeepAgentBucketContext, path: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L108)

### bucketKeyEffect

Converts a virtual path to its bucket key.

**Example**

```ts
Effect.runSync(bucketKeyEffect(context, "/readme.md"));
```

**Signature**

```ts
declare const bucketKeyEffect: (
  context: DeepAgentBucketContext,
  path: string,
) => Effect.Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L92)

### createBucketContext

Creates a bucket context for existing synchronous callers.

**Throws**

The original invalid bucket or prefix error.

**Example**

```ts
createBucketContext(bucket, "agents");
```

**Signature**

```ts
declare const createBucketContext: (
  bucket: DeepAgentBucketClient,
  prefix?: string,
) => DeepAgentBucketContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L36)

### createBucketContextEffect

Validates a bucket client and creates its private prefix context.

**Example**

```ts
Effect.runSync(createBucketContextEffect(bucket));
```

**Signature**

```ts
declare const createBucketContextEffect: (
  bucket: DeepAgentBucketClient,
  prefix?: any,
) => Effect.Effect<
  Readonly<{ bucket: DeepAgentBucketClient; prefix: string }>,
  DeepAgentBucketFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L17)

### filePath

Converts a scoped bucket key for existing synchronous callers.

**Throws**

Error for a key outside the context prefix.

**Example**

```ts
filePath(context, "agents/readme.md");
```

**Signature**

```ts
declare const filePath: (context: DeepAgentBucketContext, key: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L142)

### filePathEffect

Converts a scoped bucket key to a virtual path.

**Example**

```ts
Effect.runSync(filePathEffect(context, "agents/readme.md"));
```

**Signature**

```ts
declare const filePathEffect: (
  context: DeepAgentBucketContext,
  key: string,
) => Effect.Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L122)

### virtualPath

Normalizes a virtual path for existing synchronous callers.

**Throws**

Error for empty, unsafe, or traversing paths.

**Example**

```ts
virtualPath("docs/readme.md");
```

**Signature**

```ts
declare const virtualPath: (value: string, directory?: boolean) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L66)

### virtualPathEffect

Normalizes a virtual backend path and rejects traversal.

**Example**

```ts
Effect.runSync(virtualPathEffect("/docs/readme.md"));
```

**Signature**

```ts
declare const virtualPathEffect: (
  value: string,
  directory?: any,
) => Effect.Effect<string, DeepAgentBucketFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-path.ts#L53)

## `deepagent-bucket-read.ts`

Reads normalized native files from the selected bucket, applying the backend's content and missing-file conventions.

### readBucket

Reads a file for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await readBucket(context, "/a.md", 0, 50);
```

**Signature**

```ts
declare const readBucket: (
  context: DeepAgentBucketContext,
  path: string,
  offset?: number,
  limit?: number,
) => Promise<ReadResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-read.ts#L98)

### readBucketEffect

Reads a paged text file or an unmodified binary payload.

**Example**

```ts
Effect.runPromise(Effect.provide(readBucketEffect("/a.md", 0, 50), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const readBucketEffect: (
  path: string,
  offset?: any,
  limit?: any,
) => Effect.Effect<
  | { error: string; content?: never; mimeType?: never }
  | { content: string | Uint8Array<ArrayBufferLike>; mimeType: string; error?: never }
  | {
      nextOffset?: number;
      content: string;
      mimeType: string;
      totalLines: number;
      startLine: number;
      endLine: number;
      error?: never;
    },
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-read.ts#L60)

### readBucketRaw

Reads the full file payload for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await readBucketRaw(context, "/a.md");
```

**Signature**

```ts
declare const readBucketRaw: (
  context: DeepAgentBucketContext,
  path: string,
) => Promise<ReadRawResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-read.ts#L37)

### readBucketRawEffect

Reads the full file payload from the current bucket service.

**Example**

```ts
Effect.runPromise(Effect.provide(readBucketRawEffect("/a.md"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const readBucketRawEffect: (path: string) => Effect.Effect<
  | { error: string; data?: never }
  | {
      data: {
        content: string | Uint8Array<ArrayBufferLike>;
        mimeType: string;
        created_at: string;
        modified_at: string;
      };
      error?: never;
    },
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-read.ts#L21)

## `deepagent-bucket-scope.ts`

Owns bucket backend access for an agent invocation and closes acquired resources only after the scoped operation settles.

### createThreadBucketBackend

Creates a private thread backend for existing synchronous callers.

**Throws**

The original invalid bucket or thread error.

**Example**

```ts
const backend = createThreadBucketBackend(bucket, "agent", "thread");
```

**Signature**

```ts
declare const createThreadBucketBackend: (
  bucket: DeepAgentBucketClient,
  agentId: string,
  threadId: string,
) => Readonly<{
  ls: (path: string) => Promise<LsResult>;
  read: (path: string, offset?: number, limit?: number) => Promise<ReadResult>;
  readRaw: (path: string) => Promise<ReadRawResult>;
  write: (path: string, content: string) => Promise<WriteResult>;
  edit: (
    path: string,
    oldText: string,
    newText: string,
    replaceAll?: boolean,
  ) => Promise<EditResult>;
  grep: (
    pattern: string,
    path?: string | null,
    glob?: string | null,
    maxCount?: number | null,
  ) => Promise<GrepResult>;
  glob: (pattern: string, path?: string) => Promise<GlobResult>;
  delete: (path: string) => Promise<DeleteResult>;
  uploadFiles: (files: Array<[string, Uint8Array]>) => Promise<Array<FileUploadResponse>>;
  downloadFiles: (paths: string[]) => Promise<Array<FileDownloadResponse>>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-scope.ts#L41)

### createThreadBucketBackendEffect

Creates a private filesystem partition for one exact agent thread.

**Example**

```ts
Effect.runSync(createThreadBucketBackendEffect(bucket, "agent", "thread"));
```

**Signature**

```ts
declare const createThreadBucketBackendEffect: (
  bucket: DeepAgentBucketClient,
  agentId: string,
  threadId: string,
) => Effect.Effect<
  Readonly<{
    ls: (path: string) => Promise<LsResult>;
    read: (path: string, offset?: number, limit?: number) => Promise<ReadResult>;
    readRaw: (path: string) => Promise<ReadRawResult>;
    write: (path: string, content: string) => Promise<WriteResult>;
    edit: (
      path: string,
      oldText: string,
      newText: string,
      replaceAll?: boolean,
    ) => Promise<EditResult>;
    grep: (
      pattern: string,
      path?: string | null,
      glob?: string | null,
      maxCount?: number | null,
    ) => Promise<GrepResult>;
    glob: (pattern: string, path?: string) => Promise<GlobResult>;
    delete: (path: string) => Promise<DeleteResult>;
    uploadFiles: (files: Array<[string, Uint8Array]>) => Promise<Array<FileUploadResponse>>;
    downloadFiles: (paths: string[]) => Promise<Array<FileDownloadResponse>>;
  }>,
  DeepAgentBucketFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-scope.ts#L17)

## `deepagent-bucket-search.ts`

Coordinates native bucket listing and content search, sharing normalized paths and file metadata with the read backend.

### listDirectory

Lists a virtual directory for existing DeepAgents Promise callers.

**Throws**

A cancellation or control failure.

**Example**

```ts
await listDirectory(context, "/notes");
```

**Signature**

```ts
declare const listDirectory: (context: DeepAgentBucketContext, path: string) => Promise<LsResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-search.ts#L66)

### listDirectoryEffect

Lists direct files and child directories through bounded metadata IO.

**Example**

```ts
Effect.runPromise(Effect.provide(listDirectoryEffect("/"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const listDirectoryEffect: (
  path: string,
) => Effect.Effect<{ files: Array<FileInfo> }, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-search.ts#L21)

## `deepagent-bucket-service.ts`

Provides the Effect service used by native bucket operations, translating selected provider access into the backend's typed operation boundary.

### DeepAgentBucket (class)

Injectable bucket context for DeepAgents filesystem operations.

**Example**

```ts
Effect.provide(listDirectoryEffect("/"), deepAgentBucketLayer(context));
```

**Signature**

```ts
declare class DeepAgentBucket
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-service.ts#L9)

### deepAgentBucketLayer

Provides one bucket client and path prefix to an Effect operation.

**Example**

```ts
deepAgentBucketLayer({ bucket, prefix: "threads/one" });
```

**Signature**

```ts
declare const deepAgentBucketLayer: (
  context: DeepAgentBucketContext,
) => Layer.Layer<DeepAgentBucket, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-service.ts#L18)

## `deepagent-bucket-transfer.ts`

Transfers native file content between backend requests and bucket objects while retaining per-file success and failure results.

### downloadBucketFiles

Downloads files for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await downloadBucketFiles(context, ["/a"]);
```

**Signature**

```ts
declare const downloadBucketFiles: (
  context: DeepAgentBucketContext,
  paths: string[],
) => Promise<FileDownloadResponse[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-transfer.ts#L109)

### downloadBucketFilesEffect

Downloads files in input order with a result for each path.

**Example**

```ts
Effect.runPromise(Effect.provide(downloadBucketFilesEffect(["/a"]), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const downloadBucketFilesEffect: (
  paths: Array<string>,
) => Effect.Effect<
  Array<
    | { path: string; content: null; error: "file_not_found" }
    | { path: string; content: Uint8Array<ArrayBufferLike>; error: null }
    | { path: string; content: null; error: "invalid_path" }
  >,
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-transfer.ts#L71)

### uploadBucketFiles

Uploads files for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await uploadBucketFiles(context, [["/a", bytes]]);
```

**Signature**

```ts
declare const uploadBucketFiles: (
  context: DeepAgentBucketContext,
  files: Array<[string, Uint8Array]>,
) => Promise<FileUploadResponse[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-transfer.ts#L54)

### uploadBucketFilesEffect

Uploads files in input order so repeated paths retain last-write behavior.

**Example**

```ts
Effect.runPromise(
  Effect.provide(uploadBucketFilesEffect([["/a", bytes]]), deepAgentBucketLayer(context)),
);
```

**Signature**

```ts
declare const uploadBucketFilesEffect: (
  files: Array<[string, Uint8Array<ArrayBufferLike>]>,
) => Effect.Effect<
  Array<{ path: string; error: null } | { path: string; error: "invalid_path" }>,
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-transfer.ts#L17)

## `deepagent-bucket-write.ts`

Applies native file writes and edits to the selected bucket and updates the shared file index after successful storage mutations.

### editBucket

Edits text for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await editBucket(context, "/a.md", "old", "new", true);
```

**Signature**

```ts
declare const editBucket: (
  context: DeepAgentBucketContext,
  path: string,
  oldText: string,
  newText: string,
  replaceAll?: boolean,
) => Promise<EditResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-write.ts#L104)

### editBucketEffect

Replaces text with the existing DeepAgents edit rules.

**Example**

```ts
Effect.runPromise(
  Effect.provide(editBucketEffect("/a.md", "old", "new"), deepAgentBucketLayer(context)),
);
```

**Signature**

```ts
declare const editBucketEffect: (
  path: string,
  oldText: string,
  newText: string,
  replaceAll?: any,
) => Effect.Effect<
  | { error: string; path?: never; filesUpdate?: never; occurrences?: never }
  | { path: string; filesUpdate: null; occurrences: number; error?: never },
  DeepAgentBucketFailure,
  DeepAgentBucket
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-write.ts#L67)

### writeBucket

Writes text for existing DeepAgents Promise callers.

**Throws**

A cancellation or timeout failure from the bucket client.

**Example**

```ts
await writeBucket(context, "/a.md", "hi");
```

**Signature**

```ts
declare const writeBucket: (
  context: DeepAgentBucketContext,
  path: string,
  content: string,
) => Promise<WriteResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-write.ts#L42)

### writeBucketEffect

Writes a text file through the current bucket service.

**Example**

```ts
Effect.runPromise(Effect.provide(writeBucketEffect("/a.md", "hi"), deepAgentBucketLayer(context)));
```

**Signature**

```ts
declare const writeBucketEffect: (
  path: string,
  content: string,
) => Effect.Effect<{ path: string; filesUpdate: null }, DeepAgentBucketFailure, DeepAgentBucket>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/deepagent-bucket-write.ts#L18)

## `define-agent-build.ts`

Assembles validated native agent configuration into a RELKIT descriptor, preserving native model, tools and execution metadata for runtime selection.

### prepareAgentDescriptor

Validates agent options and returns an assembler for a resolved identity.

**Throws**

Validation errors from fields and client policy.

**Example**

```ts
prepareAgentDescriptor(options)("support");
```

**Signature**

```ts
declare const prepareAgentDescriptor: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Middleware extends readonly AgentMiddleware[],
  const Tools extends readonly AgentTool[],
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Middleware, Tools>,
) => (
  id: Id,
) => AgentDescriptor<
  Id,
  InferInput<InputSchema>,
  InferOutput<OutputSchema>,
  InputSchema,
  OutputSchema,
  Middleware,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-build.ts#L31)

## `define-agent-deep.ts`

Normalizes optional DeepAgents authoring fields without loading the DeepAgents runtime; the same defined-field selection controls the graph marker.

### "./define-agent-deep.types.js" (namespace export)

Re-exports all named exports from the "./define-agent-deep.types.js" module.

**Signature**

```ts
export * from "./define-agent-deep.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.ts#L9)

### copyDeepAgentCapabilities

Copies DeepAgents options for existing synchronous authoring callers.

**Throws**

The original invalid capability error.

**Example**

```ts
const options = copyDeepAgentCapabilities({ skills: ["/skills"] });
```

**Signature**

```ts
declare const copyDeepAgentCapabilities: (value: DeepAgentCapabilities) => DeepAgentCapabilities;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.ts#L31)

### copyDeepAgentCapabilitiesEffect

Validates and freezes native DeepAgents options.

**Example**

```ts
Effect.runSync(copyDeepAgentCapabilitiesEffect({ skills: ["/skills"] }));
```

**Signature**

```ts
declare const copyDeepAgentCapabilitiesEffect: (
  value: DeepAgentCapabilities,
) => Effect.Effect<DeepAgentCapabilities, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.ts#L16)

### hasDeepAgentCapabilities

Checks capabilities for existing synchronous authoring callers.

**Example**

```ts
if (hasDeepAgentCapabilities(options)) enableDeep();
```

**Signature**

```ts
declare const hasDeepAgentCapabilities: (value: DeepAgentCapabilities) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.ts#L81)

### hasDeepAgentCapabilitiesEffect

Checks whether a descriptor enables native DeepAgents capabilities.

**Example**

```ts
Effect.runSync(hasDeepAgentCapabilitiesEffect({ skills: ["/skills"] }));
```

**Signature**

```ts
declare const hasDeepAgentCapabilitiesEffect: (
  value: DeepAgentCapabilities,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.ts#L71)

## `define-agent-deep.types.ts`

Normalizes optional DeepAgents authoring fields without loading the DeepAgents runtime; the same defined-field selection controls the graph marker. This companion preserves the native input and output types without starting runtime work.

### AgentFilesystemBackend (type alias)

DeepAgents filesystem backend or a state-bound backend factory.

**Signature**

```ts
type AgentFilesystemBackend =
  object | ((context: { readonly state: unknown; readonly store?: unknown }) => object);
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.types.ts#L12)

### AgentSubagent (type alias)

Agent descriptor nested under a DeepAgent.

**Signature**

```ts
type AgentSubagent = AgentDescriptor<string, unknown, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.types.ts#L9)

### DeepAgentCapabilities (interface)

Optional capabilities enabled for a DeepAgent.

**Signature**

```ts
export interface DeepAgentCapabilities {
  readonly subagents?: readonly AgentSubagent[];
  readonly skills?: readonly string[];
  readonly memory?: readonly string[];
  readonly backend?: AgentFilesystemBackend;
  readonly checkpointer?: BaseCheckpointSaver | CheckpointerResource;
  readonly store?: BaseStore | MemoryResource;
  readonly interruptOn?: Readonly<Record<string, boolean | InterruptOnConfig>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-deep.types.ts#L16)

## `define-agent-native-middleware.ts`

Validates and retains SDK middleware supplied by native agent authors so runtime construction receives the original middleware objects.

### copyAgentMiddleware

Copies middleware for existing synchronous authoring callers.

**Throws**

The original invalid middleware error.

**Example**

```ts
const middleware = copyAgentMiddleware([]);
```

**Signature**

```ts
declare const copyAgentMiddleware: <Middleware extends readonly AgentMiddleware[]>(
  value: Middleware | undefined,
) => Middleware;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-middleware.ts#L43)

### copyAgentMiddlewareEffect

Validates middleware names and brands, retaining input order.

**Example**

```ts
Effect.runSync(copyAgentMiddlewareEffect([]));
```

**Signature**

```ts
declare const copyAgentMiddlewareEffect: <Middleware extends readonly AgentMiddleware[]>(
  value: Middleware | undefined,
) => Effect.Effect<Middleware, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-middleware.ts#L14)

### middlewareStateKeys

Collects state keys for existing synchronous authoring callers.

**Throws**

The original schema access error.

**Example**

```ts
const keys = middlewareStateKeys([]);
```

**Signature**

```ts
declare const middlewareStateKeys: <Middleware extends readonly AgentMiddleware[]>(
  middleware: Middleware,
) => ReadonlySet<AgentClientStateKey<Middleware>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-middleware.ts#L84)

### middlewareStateKeysEffect

Collects public state keys declared by middleware schemas.

**Example**

```ts
Effect.runSync(middlewareStateKeysEffect([]));
```

**Signature**

```ts
declare const middlewareStateKeysEffect: <Middleware extends readonly AgentMiddleware[]>(
  middleware: Middleware,
) => Effect.Effect<
  ReadonlySet<MiddlewareStateKey<Middleware[number]>>,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-middleware.ts#L58)

## `define-agent-native-model.ts`

Accepts native chat-model instances or supported model selectors and preserves the model's inference contract for descriptor construction.

### isAgentModel

Checks a model for existing synchronous authoring callers.

**Example**

```ts
if (isAgentModel(value)) use(value);
```

**Signature**

```ts
declare const isAgentModel: (value: unknown) => value is AgentModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-model.ts#L28)

### isAgentModelEffect

Checks whether a value can select or provide a native agent model.

**Example**

```ts
Effect.runSync(isAgentModelEffect("openai:gpt"));
```

**Signature**

```ts
declare const isAgentModelEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-model.ts#L12)

## `define-agent-native-tools.ts`

Separates native SDK tools from RELKIT callable references while retaining native identity and serializable generic tool references.

### copyAgentTools

Copies tools for existing synchronous authoring callers.

**Throws**

The original invalid or duplicate tool error.

**Example**

```ts
const tools = copyAgentTools([]);
```

**Signature**

```ts
declare const copyAgentTools: <Tools extends readonly AgentTool[]>(value: Tools) => Tools;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-tools.ts#L47)

### copyAgentToolsEffect

Validates and freezes RELKIT and native agent tools in input order.

**Example**

```ts
Effect.runSync(copyAgentToolsEffect([]));
```

**Signature**

```ts
declare const copyAgentToolsEffect: <Tools extends readonly AgentTool[]>(
  value: Tools,
) => Effect.Effect<Tools, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-tools.ts#L15)

### relkitToolRefs

Selects RELKIT references for existing synchronous authoring callers.

**Example**

```ts
const refs = relkitToolRefs(tools);
```

**Signature**

```ts
declare const relkitToolRefs: (tools: readonly AgentTool[]) => readonly ToolRefAny[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-tools.ts#L70)

### relkitToolRefsEffect

Selects RELKIT tool references from a mixed native tool list.

**Example**

```ts
Effect.runSync(relkitToolRefsEffect([]));
```

**Signature**

```ts
declare const relkitToolRefsEffect: (
  tools: ReadonlyArray<AgentTool>,
) => Effect.Effect<Array<ToolRefAny>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native-tools.ts#L60)

## `define-agent-native.ts`

Builds the native execution payload from model, tool and middleware inputs after validation, without starting model execution during authoring.

### "./define-agent-native-middleware.js" (namespace export)

Re-exports all named exports from the "./define-agent-native-middleware.js" module.

**Signature**

```ts
export * from "./define-agent-native-middleware.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.ts#L5)

### "./define-agent-native-model.js" (namespace export)

Re-exports all named exports from the "./define-agent-native-model.js" module.

**Signature**

```ts
export * from "./define-agent-native-model.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.ts#L4)

### "./define-agent-native-tools.js" (namespace export)

Re-exports all named exports from the "./define-agent-native-tools.js" module.

**Signature**

```ts
export * from "./define-agent-native-tools.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.ts#L6)

### "./define-agent-native.types.js" (namespace export)

Re-exports all named exports from the "./define-agent-native.types.js" module.

**Signature**

```ts
export * from "./define-agent-native.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.ts#L3)

## `define-agent-native.types.ts`

Builds the native execution payload from model, tool and middleware inputs after validation, without starting model execution during authoring. This companion preserves the native input and output types without starting runtime work.

### AgentClientStateKey (type alias)

Public state keys selected from each middleware schema without erasing tuples.

**Signature**

```ts
type AgentClientStateKey<Middleware extends readonly AgentMiddleware[]> = MiddlewareStateKey<
  Middleware[number]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L64)

### AgentLanguageModel (interface)

Native model object accepted by an agent descriptor.

**Signature**

```ts
export interface AgentLanguageModel {
  readonly invoke: (...args: never[]) => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L10)

### AgentMiddleware (type alias)

SDK fields RELKIT inspects; each descriptor retains its complete inferred middleware tuple, including native hooks, tools and phantom schema data. Runtime validation checks the SDK brand.

**Signature**

```ts
type AgentMiddleware = Pick<NativeAgentMiddleware, "name" | "stateSchema">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L29)

### AgentMiddlewareState (type alias)

Public state composed from middleware state schemas.

**Signature**

```ts
type AgentMiddlewareState<Middleware extends readonly AgentMiddleware[]> =
  Middleware extends readonly [infer First, ...infer Rest]
    ? First extends AgentMiddleware
      ? Rest extends readonly AgentMiddleware[]
        ? MiddlewareState<First> & AgentMiddlewareState<Rest>
        : MiddlewareState<First>
      : {}
    : {};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L32)

### AgentModel (type alias)

Model selector, native model, or model factory.

**Signature**

```ts
type AgentModel = string | AgentLanguageModel | AgentModelFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L20)

### AgentModelFactory (type alias)

Environment-bound factory for a native model.

**Signature**

```ts
type AgentModelFactory<Environment = Readonly<Record<string, unknown>>> = (
  environment: Environment,
) => MaybePromise<AgentLanguageModel>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L15)

### AgentTool (type alias)

RELKIT reference or native LangChain tool.

**Signature**

```ts
type AgentTool = ToolRefAny | NativeAgentTool;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L26)

### NativeAgentTool (type alias)

LangChain client or server tool.

**Signature**

```ts
type NativeAgentTool = ClientTool | ServerTool;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-native.types.ts#L23)

## `define-agent-validation.ts`

Validates shared and native agent configuration before descriptor assembly, keeping invalid authoring failures out of the invocation path.

### assertAgentDescriptor

Requires a descriptor for existing synchronous authoring callers.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
assertAgentDescriptor(candidate);
```

**Signature**

```ts
declare const assertAgentDescriptor: (value: unknown) => asserts value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L81)

### assertAgentDescriptorEffect

Requires a valid agent descriptor.

**Example**

```ts
Effect.runSync(assertAgentDescriptorEffect(agent));
```

**Signature**

```ts
declare const assertAgentDescriptorEffect: (
  value: unknown,
) => Effect.Effect<void, AgentDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L64)

### isAgentDescriptor

Checks a descriptor for existing synchronous authoring callers.

**Example**

```ts
if (isAgentDescriptor(candidate)) use(candidate);
```

**Signature**

```ts
declare const isAgentDescriptor: (value: unknown) => value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L35)

### isAgentDescriptorEffect

Checks the complete runtime shape of an agent descriptor.

**Example**

```ts
Effect.runSync(isAgentDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isAgentDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L25)

### normalizeAgentModel

Normalizes a model for existing synchronous authoring callers.

**Throws**

The original invalid selector error.

**Example**

```ts
const model = normalizeAgentModel("openai:gpt");
```

**Signature**

```ts
declare const normalizeAgentModel: (value: AgentModel | undefined) => AgentModel | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L110)

### normalizeAgentModelEffect

Normalizes the selector of a string model definition.

**Example**

```ts
Effect.runSync(normalizeAgentModelEffect("openai:gpt"));
```

**Signature**

```ts
declare const normalizeAgentModelEffect: (
  value: AgentModel | undefined,
) => Effect.Effect<
  string | AgentLanguageModel | AgentModelFactory<Readonly<Record<string, unknown>>> | undefined,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent-validation.ts#L94)

## `define-agent.ts`

Exposes SDK-native agent authoring with inferred input and output types; validation and descriptor assembly are delegated to the integration's owning helpers.

### defineAgent

Defines a native agent for existing synchronous authoring callers.

**Throws**

The original invalid authoring or identity error.

**Example**

```ts
import { defineAgent } from "@relkit/langchain";
import { z } from "@relkit/app/schema";

const support = defineAgent({
  id: "support",
  input: z.object({ message: z.string() }),
  output: z.object({ answer: z.string() }),
  instructions: "Reply briefly.",
  tools: [],
  limits: { maxSteps: 4, maxToolCalls: 2, timeoutMs: 30_000 },
});
void support;
```

**Signature**

```ts
declare const defineAgent: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Middleware extends readonly AgentMiddleware[] = readonly [],
  const Tools extends readonly AgentTool[] = ReadonlyArray<AgentTool>,
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Middleware, Tools>,
) => AgentDescriptor<
  Id,
  InferInput<InputSchema>,
  InferOutput<OutputSchema>,
  InputSchema,
  OutputSchema,
  Middleware,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L109)

Since v0.4.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="templates/default/v1/agent/src/services/hello/agents/assistant.agent.ts"
/** Runs an offline greeting agent with RELKIT/native tools, todo middleware and public state observation. */
import { defineAgent } from "@relkit/langchain";
import { z } from "@relkit/app/schema";
import { FakeToolCallingModel, todoListMiddleware, tool } from "langchain";
import lookup from "@app/services/hello/tools/lookup.tool.js";

export const uppercase = tool(async ({ text }: { readonly text: string }) => text.toUpperCase(), {
  name: "uppercase",
  description: "Uppercase text without leaving the process",
  schema: z.object({ text: z.string() }),
});

export default defineAgent({
  id: "hello.assistant",

  input: z.object({ message: z.string().min(1) }),
  output: z.object({ answer: z.string() }),

  model: new FakeToolCallingModel({
    toolCalls: [
      [
        {
          name: "write_todos",
          args: { todos: [{ content: "Answer the greeting", status: "completed" }] },
          id: "todo-1",
        },
      ],
      [
        {
          name: "relkit_output",
          args: { value: { answer: "Hello from the offline LangChain model." } },
          id: "output-1",
        },
      ],
    ],
  }),
  instructions: "Answer greeting questions with the available tools.",
  tools: [lookup, uppercase],
  middleware: [todoListMiddleware()],
  stateProfile: "default",
  client: {
    public: true,
    state: ["todos"],
    events: { notice: z.object({ message: z.string() }) },
  },
  chat: { input: "message", output: "answer" },
  controls: ["stop"],

  limits: {
    maxSteps: 4,
    maxToolCalls: 4,
    timeoutMs: 10_000,
  },
});
```

**Frontend**

After [frontend setup and pulling the greeting agent's contract](/guides/frontend/connect-react),
render this component under the provider. Supply a stable business `threadId` owned by your
application, such as the ID of the conversation the user opened:

```tsx title="src/Assistant.tsx"
"use client";

/** Sends one greeting to the documented hello.assistant agent and observes its typed answer. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Keeps the application-owned thread identity stable across rendering and observation.
 * @param props - Authorized conversation identity retained by the application.
 * @returns A greeting action, the observed answer, and explicit submission failure. */
export function Assistant({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const assistant = useAgent("hello.assistant");
  const [failure, setFailure] = useState("");

  /** Submits once and preserves uncertain outcomes for explicit recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function sendGreeting() {
    try {
      await assistant.send("Hello, RELKIT!", { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || assistant.status !== "idle" || failure !== ""}
        onClick={sendGreeting}
      >
        Say hello
      </button>
      <p role="status">{assistant.output?.answer ?? assistant.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

This is the same `hello.assistant` declaration: `client.public` exposes it, `chat.input: "message"`
makes `send` accept a string, and `chat.output: "answer"` selects its typed answer. Mounting
`useAgent` does not start a run. The backend owns models, credentials, tools, and authorization.

Reference: [`useAgent`](/docs/api/client#useagent).
Continue with [streaming and controls](/docs/modules/ai/streaming) or
[thread recovery](/docs/modules/ai/threads-recovery).

### AgentChatMapping

**Signature**

```ts
declare const AgentChatMapping: AgentChatMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L28)

### AgentClientPolicy

**Signature**

```ts
declare const AgentClientPolicy: AgentClientPolicy<Guard, StateKey, Events>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L29)

### AgentClientStateKey

**Signature**

```ts
declare const AgentClientStateKey: AgentClientStateKey<Middleware>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L19)

### AgentControl

**Signature**

```ts
declare const AgentControl: AgentControl;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L30)

### AgentDescriptor

**Signature**

```ts
declare const AgentDescriptor: AgentDescriptor<
  Id,
  Input,
  Output,
  InputSchema,
  OutputSchema,
  Middleware,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L38)

### AgentFilesystemBackend

**Signature**

```ts
declare const AgentFilesystemBackend: AgentFilesystemBackend;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L33)

### AgentInstructions

**Signature**

```ts
declare const AgentInstructions: AgentInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L39)

### AgentLimits

**Signature**

```ts
declare const AgentLimits: AgentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L40)

### AgentMiddleware

**Signature**

```ts
declare const AgentMiddleware: AgentMiddleware;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L20)

### AgentMiddlewareState

**Signature**

```ts
declare const AgentMiddlewareState: AgentMiddlewareState<Middleware>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L21)

### AgentModel

**Signature**

```ts
declare const AgentModel: AgentModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L22)

### AgentModelFactory

**Signature**

```ts
declare const AgentModelFactory: AgentModelFactory<Environment>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L23)

### AgentSubagent

**Signature**

```ts
declare const AgentSubagent: AgentSubagent;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L34)

### AgentTool

**Signature**

```ts
declare const AgentTool: AgentTool;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L24)

### DeepAgentCapabilities

**Signature**

```ts
declare const DeepAgentCapabilities: DeepAgentCapabilities;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L35)

### DefineAgentOptions

**Signature**

```ts
declare const DefineAgentOptions: DefineAgentOptions<
  Id,
  InputSchema,
  OutputSchema,
  Middleware,
  Tools
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L41)

### NativeAgentTool

**Signature**

```ts
declare const NativeAgentTool: NativeAgentTool;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L25)

### PromptInstructions

**Signature**

```ts
declare const PromptInstructions: PromptInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L42)

### PromptTemplate

**Signature**

```ts
declare const PromptTemplate: PromptTemplate;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L43)

### assertAgentDescriptor

**Signature**

```ts
declare const assertAgentDescriptor: (value: unknown) => asserts value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L13)

### copyAgentLimits

**Signature**

```ts
declare const copyAgentLimits: (value: unknown) => AgentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L15)

### copyAgentLimitsEffect

**Signature**

```ts
declare const copyAgentLimitsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<{ maxSteps: number; maxToolCalls: number; timeoutMs: number }>,
  import("@relkit/agents/internal/define-agent-error").AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L16)

### defineAgentEffect

Defines a native agent with validated authoring options and substitutable identity generation.

**Example**

```ts
Effect.runSync(
  defineAgentEffect({ id: "support", input, output, instructions: "Reply.", tools: [], limits }),
);
```

**Signature**

```ts
declare const defineAgentEffect: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Middleware extends readonly AgentMiddleware[] = readonly [],
  const Tools extends readonly AgentTool[] = ReadonlyArray<AgentTool>,
>(
  options: DefineAgentOptions<Id, InputSchema, OutputSchema, Middleware, Tools>,
) => Effect.Effect<
  AgentDescriptor<
    Id,
    InferInput<InputSchema>,
    InferOutput<OutputSchema>,
    InputSchema,
    OutputSchema,
    Middleware,
    Tools
  >,
  AgentDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L51)

### isAgentDescriptor

**Signature**

```ts
declare const isAgentDescriptor: (value: unknown) => value is AgentAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.ts#L13)

## `define-agent.types.ts`

Exposes SDK-native agent authoring with inferred input and output types; validation and descriptor assembly are delegated to the integration's owning helpers. This companion preserves the native input and output types without starting runtime work.

### AgentDescriptor (interface)

**Signature**

```ts
export interface AgentDescriptor<
  Id extends string,
  Input,
  Output,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  Middleware extends readonly AgentMiddleware[] = readonly AgentMiddleware[],
  Tools extends readonly AgentTool[] = readonly AgentTool[],
>
  extends
    DescriptorBase<"agent", Id>,
    AgentRef<Id, InputSchema, OutputSchema>,
    DeepAgentCapabilities {
  readonly model?: AgentModel;
  readonly instructions: AgentInstructions;
  readonly tools: Tools;
  readonly middleware: Middleware;
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<(...args: any[]) => unknown, AgentClientStateKey<Middleware>>;
  readonly chat?: AgentChatMapping;
  readonly controls?: readonly AgentControl[];
  readonly clientContract: AgentClientContractMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L40)

### AgentInstructions (type alias)

**Signature**

```ts
type AgentInstructions = string | PromptTemplate | PromptInstructions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L32)

### AgentLimits (interface)

**Signature**

```ts
export interface AgentLimits {
  readonly maxSteps: number;
  readonly maxToolCalls: number;
  readonly timeoutMs: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L34)

### DefineAgentOptions (interface)

**Signature**

```ts
export interface DefineAgentOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Middleware extends readonly AgentMiddleware[],
  Tools extends readonly AgentTool[],
>
  extends DescriptorMetadata, DeepAgentCapabilities {
  readonly id?: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly model?: AgentModel;
  readonly instructions: AgentInstructions;
  readonly tools: Tools;
  readonly middleware?: Middleware;
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<(...args: any[]) => unknown, AgentClientStateKey<Middleware>>;
  readonly chat?: AgentChatMapping;
  readonly controls?: readonly AgentControl[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L65)

### PromptInstructions (interface)

**Signature**

```ts
export interface PromptInstructions {
  readonly kind: "prompt";
  readonly id: string;
  readonly ref: { readonly kind: "prompt"; readonly id: string };
  readonly value: string | readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L25)

### PromptTemplate (interface)

**Signature**

```ts
export interface PromptTemplate {
  readonly template: string;
  readonly variables?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-agent.types.ts#L20)

## `define-graph-build.ts`

Assembles graph nodes, edges, state and persistence into the authored native descriptor that compilation consumes without invoking graph nodes.

### prepareGraphDescriptor

Validates graph authoring options and returns an assembler for its identity.

**Throws**

Invalid schema, node, edge, or client policy errors.

**Example**

```ts
prepareGraphDescriptor(options)("support.graph");
```

**Signature**

```ts
declare const prepareGraphDescriptor: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const State extends AnyStateSchema,
  const Nodes extends readonly GraphNodeLike[],
>(
  options: DefineGraphOptions<Id, InputSchema, OutputSchema, State, Nodes>,
) => (id: Id) => GraphDescriptor<Id, InputSchema, OutputSchema, State, Nodes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-build.ts#L29)

## `define-graph-error.ts`

Defines graph authoring failures reported before native compilation, retaining the invalid graph field and actionable diagnostic.

### GraphDefinitionFailure (class)

Tagged invalid graph authoring options or descriptor construction.

**Signature**

```ts
declare class GraphDefinitionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-error.ts#L6)

### graphDefinitionFailure

Preserves a graph authoring error for Effect callers.

**Example**

```ts
graphDefinitionFailure(new TypeError("invalid graph"));
```

**Signature**

```ts
declare const graphDefinitionFailure: (cause: unknown) => GraphDefinitionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-error.ts#L16)

## `define-graph-node.ts`

Creates typed native graph node descriptors from author callbacks and records their execution metadata for later graph compilation.

### "./define-graph-node.types.js" (namespace export)

Re-exports all named exports from the "./define-graph-node.types.js" module.

**Signature**

```ts
export * from "./define-graph-node.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L25)

### assertGraphNodeDestinations

**Signature**

```ts
declare const assertGraphNodeDestinations: (
  node: Pick<GraphNodeAny, "id" | "ends">,
  registeredNodeIds: ReadonlySet<string> | readonly string[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L26)

### defineGraphNode

Defines a graph node for existing synchronous authoring callers.

**Throws**

The original authoring error for invalid options.

**Example**

```ts
const node = defineGraphNode({ id: "step", input, output, handler });
```

**Signature**

```ts
declare const defineGraphNode: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const ResumeSchema extends StandardSchemaV1 | undefined = undefined,
  const Ends extends readonly string[] = readonly [],
>(
  options: DefineGraphNodeOptions<Id, InputSchema, OutputSchema, ResumeSchema, Ends>,
) => GraphNodeDescriptor<Id, InputSchema, OutputSchema, ResumeSchema, Ends>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L121)

### defineGraphNodeEffect

Defines a native LangGraph node with RELKIT schemas and declared dynamic routes.

**Example**

```ts
Effect.runSync(defineGraphNodeEffect({ id: "step", input, output, handler }));
```

**Signature**

```ts
declare const defineGraphNodeEffect: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const ResumeSchema extends StandardSchemaV1 | undefined = undefined,
  const Ends extends readonly string[] = readonly [],
>(
  options: DefineGraphNodeOptions<Id, InputSchema, OutputSchema, ResumeSchema, Ends>,
) => Effect.Effect<
  GraphNodeDescriptor<Id, InputSchema, OutputSchema, ResumeSchema, Ends>,
  GraphNodeValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L65)

### isGraphNodeDescriptor

Checks a graph node descriptor for existing synchronous callers.

**Example**

```ts
if (isGraphNodeDescriptor(value)) useNode(value);
```

**Signature**

```ts
declare const isGraphNodeDescriptor: (value: unknown) => value is GraphNodeAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L166)

### isGraphNodeDescriptorEffect

Checks whether a value is a native graph node descriptor.

**Example**

```ts
Effect.runSync(isGraphNodeDescriptorEffect(value));
```

**Signature**

```ts
declare const isGraphNodeDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L142)

### runGraphNodeHandlerEffect

Runs input validation, the user handler, and output validation in one Effect.

**Example**

```ts
await Effect.runPromise(runGraphNodeHandlerEffect(options, [], input));
```

**Signature**

```ts
declare const runGraphNodeHandlerEffect: <
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Ends extends readonly string[],
>(
  options: Pick<
    DefineGraphNodeOptions<
      string,
      InputSchema,
      OutputSchema,
      StandardSchemaV1<unknown, unknown> | undefined,
      Ends
    >,
    "input" | "output" | "handler"
  >,
  ends: Ends,
  input: unknown,
  config?: LangGraphRunnableConfig<Record<string, any>> | undefined,
) => Effect.Effect<GraphNodeResult<OutputSchema, Ends>, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.ts#L36)

## `define-graph-node.types.ts`

Creates typed native graph node descriptors from author callbacks and records their execution metadata for later graph compilation. This companion preserves the native input and output types without starting runtime work.

### DefineGraphNodeOptions (interface)

Authoring options for a native LangGraph node.

**Signature**

```ts
export interface DefineGraphNodeOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  ResumeSchema extends StandardSchemaV1 | undefined,
  Ends extends readonly string[],
> extends DescriptorMetadata {
  readonly id: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly resume?: ResumeSchema;
  readonly ends?: Ends;
  readonly handler: GraphNodeImplementation<InputSchema, OutputSchema, Ends>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L75)

### GraphNodeAny (type alias)

Erased graph node descriptor for runtime validation.

**Signature**

```ts
type GraphNodeAny = GraphNodeDescriptor<
  string,
  StandardSchemaV1,
  StandardSchemaV1,
  StandardSchemaV1 | undefined,
  readonly string[]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L66)

### GraphNodeDescriptor (interface)

Immutable native graph node descriptor.

**Signature**

```ts
export interface GraphNodeDescriptor<
  Id extends string = string,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  ResumeSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,
  Ends extends readonly string[] = readonly string[],
> extends DescriptorMetadata {
  readonly [RELKIT_GRAPH_NODE]: true;
  readonly kind: "graph-node";
  readonly id: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly resume?: ResumeSchema;
  readonly ends: Ends;
  readonly handler: GraphNodeHandler<InputSchema, OutputSchema, Ends>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L48)

### GraphNodeHandler (type alias)

Validated handler stored on a graph node descriptor.

**Signature**

```ts
type GraphNodeHandler<
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Ends extends readonly string[],
> = (
  input: InferOutput<InputSchema>,
  config?: LangGraphRunnableConfig,
) => MaybePromise<GraphNodeResult<OutputSchema, Ends>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L25)

### GraphNodeImplementation (type alias)

User implementation before RELKIT input and output validation.

**Signature**

```ts
type GraphNodeImplementation<
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Ends extends readonly string[],
> = (
  input: InferOutput<InputSchema>,
  config?: LangGraphRunnableConfig,
) => MaybePromise<
  | NodeUpdateInput<OutputSchema>
  | Command<unknown, NodeUpdateInput<OutputSchema>, CommandNodes<Ends>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L35)

### GraphNodeResult (type alias)

Validated graph node result or native routing command.

**Signature**

```ts
type GraphNodeResult<OutputSchema extends StandardSchemaV1, Ends extends readonly string[]> =
  NodeUpdate<OutputSchema> | Command<unknown, NodeUpdate<OutputSchema>, CommandNodes<Ends>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph-node.types.ts#L21)

## `define-graph.ts`

Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin.

### "./define-graph.types.js" (namespace export)

Re-exports all named exports from the "./define-graph.types.js" module.

**Signature**

```ts
export * from "./define-graph.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L19)

### defineGraph

Defines a graph for existing synchronous authoring callers.

**Throws**

The original invalid graph authoring or identity error.

**Example**

```ts
const graph = defineGraph({ id: "flow", state, input, output, nodes, edges, limits });
```

**Signature**

```ts
declare const defineGraph: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const State extends AnyStateSchema,
  const Nodes extends readonly GraphNodeLike[],
>(
  options: DefineGraphOptions<Id, InputSchema, OutputSchema, State, Nodes>,
) => GraphDescriptor<Id, InputSchema, OutputSchema, State, Nodes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L63)

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/orders/agents/order-review.agent.ts"
const orderReview = defineGraph({
  state,
  input: z.object({ orderId: z.string() }),
  output: z.object({ result: z.string() }),
  nodes: [inventory, risk, retry, review, finish],
  edges: (edge) =>
    edge
      .addEdge(START, "load-inventory")
      .addEdge(START, "assess-risk")
      .addEdge(["load-inventory", "assess-risk"], "retry")
      .addConditionalEdges("retry", ({ attempts }) => (attempts === 1 ? "again" : "ready"), {
        again: "retry",
        ready: "review",
      })
      .addEdge("finish", END),
  checkpointer: orderCheckpoints,
  store: orderMemory,
  limits: { maxSteps: 10, maxToolCalls: 1, timeoutMs: 20_000 },
  stateProfile: "agents",
  client: {
    public: true,
    state: ["inventory", "risk", "attempts", "approved", "result"],
  },
  controls: ["stop"],
});
```

**Frontend**

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider with your application's stable business `threadId`:

```tsx title="src/OrderReview.tsx"
"use client";

/** Starts the commerce review graph and answers its boolean interrupt on the same business thread. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Keeps initial input and a waiting reply distinct while rendering the graph's final result.
 * @param props - Authorized order-review thread retained by the application.
 * @returns Start/approve actions, current result, and visible submission failure. */
export function OrderReview({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const review = useAgent("orders.order-review");
  const [failure, setFailure] = useState("");

  /** Starts one review; uncertain acceptance is left for explicit thread recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function startReview() {
    try {
      await review.run({ orderId: "demo-1" }, { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  /** Replies with the review node's declared boolean on the original thread.
   * @returns Completion after the continuation is accepted or its failure is displayed. */
  async function approve() {
    try {
      await review.run(true, { threadId, resume: true });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || review.status !== "idle" || failure !== ""}
        onClick={startReview}
      >
        Start review
      </button>
      <button
        disabled={status !== "ready" || review.status !== "waiting" || failure !== ""}
        onClick={approve}
      >
        Approve order
      </button>
      <p role="status">{review.output?.result ?? review.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

`defineGraph` generates an agent client too. The initial `run` receives `{ orderId }`; the review
node's `resume: z.boolean()` makes the continuation accept a boolean. Resume the same thread with
`{ resume: true }`, and show the final `output.result`. Do not send a replacement initial run to
answer an interrupt or replay an uncertain submission.

Reference: [`useAgent`](/docs/api/client#useagent).
Continue with [threads and recovery](/docs/modules/ai/threads-recovery).

### defineGraphEffect

Defines an inspectable agent backed by native LangGraph.

**Example**

```ts
Effect.runSync(defineGraphEffect({ id: "flow", state, input, output, nodes, edges, limits }));
```

**Signature**

```ts
declare const defineGraphEffect: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const State extends AnyStateSchema,
  const Nodes extends readonly GraphNodeLike[],
>(
  options: DefineGraphOptions<Id, InputSchema, OutputSchema, State, Nodes>,
) => Effect.Effect<
  GraphDescriptor<Id, InputSchema, OutputSchema, State, Nodes>,
  GraphDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L26)

### graphExecution

Reads graph runtime state for existing synchronous callers.

**Example**

```ts
graphExecution(graph);
```

**Signature**

```ts
declare const graphExecution: (value: GraphDescriptor) => GraphExecution;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L94)

### graphExecutionEffect

Reads the hidden runtime state of an authored graph.

**Example**

```ts
Effect.runSync(graphExecutionEffect(graph));
```

**Signature**

```ts
declare const graphExecutionEffect: (
  value: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
) => Effect.Effect<GraphExecution<InferStateSchemaValue<any>>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L84)

### isGraphDescriptor

Checks a graph descriptor for existing synchronous callers.

**Example**

```ts
if (isGraphDescriptor(candidate)) invokeGraph(candidate);
```

**Signature**

```ts
declare const isGraphDescriptor: (value: unknown) => value is GraphDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L122)

### isGraphDescriptorEffect

Checks whether a value is a native graph descriptor.

**Example**

```ts
Effect.runSync(isGraphDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isGraphDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.ts#L103)

## `define-graph.types.ts`

Exposes typed LangGraph authoring and delegates descriptor validation and construction before any graph execution can begin. This companion preserves the native input and output types without starting runtime work.

### DefineGraphOptions (interface)

Authoring options for a native LangGraph agent descriptor.

**Signature**

```ts
export interface DefineGraphOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  State extends AnyStateSchema,
  Nodes extends readonly GraphNodeLike[],
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly state: State;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly nodes: Nodes & UniqueNodes<Nodes>;
  readonly edges: (
    graph: GraphEdgeBuilder<NoInfer<Extract<GraphNodeId<Nodes>, string>>, GraphState<State>>,
  ) => unknown;
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<(...args: any[]) => unknown, GraphStateKey<State>>;
  readonly controls?: readonly AgentControl[];
  readonly checkpointer?: BaseCheckpointSaver | CheckpointerResource;
  readonly store?: BaseStore | MemoryResource;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L79)

### GraphDescriptor (interface)

Inspectable agent descriptor backed by a native LangGraph graph.

**Signature**

```ts
export interface GraphDescriptor<
  Id extends string = string,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
  State extends AnyStateSchema = AnyStateSchema,
  Nodes extends readonly GraphNodeLike[] = readonly GraphNodeLike[],
>
  extends DescriptorBase<"agent", Id>, AgentRef<Id, InputSchema, OutputSchema> {
  readonly execution: "graph";
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly nodes: Nodes;
  readonly workflow: GraphWorkflow;
  readonly instructions: "";
  readonly tools: readonly [];
  readonly middleware: readonly [];
  readonly limits: AgentLimits;
  readonly stateProfile?: string;
  readonly client?: AgentClientPolicy<(...args: any[]) => unknown, GraphStateKey<State>>;
  readonly controls?: readonly AgentControl[];
  readonly clientContract: AgentClientContractMetadata;
  readonly [GRAPH_EXECUTION]: GraphExecution<GraphState<State>>;
  readonly asGraphNode: <const NodeId extends string = Id>(
    options?: GraphAsNodeOptions<NodeId>,
  ) => SubgraphNodeDescriptor<NodeId, InputSchema, OutputSchema>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L51)

### GraphExecution (interface)

Runtime state and persistence declarations hidden on a graph descriptor.

**Signature**

```ts
export interface GraphExecution<State = any> {
  readonly state: AnyStateSchema;
  readonly operations: readonly GraphEdgeOperation<string, State>[];
  readonly checkpointer?: BaseCheckpointSaver | CheckpointerResource;
  readonly store?: BaseStore | MemoryResource;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L43)

### GraphInput (type alias)

Input inferred from a graph descriptor.

**Signature**

```ts
type GraphInput<Graph extends GraphDescriptor> = InferInput<Graph["input"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L103)

### GraphNodeId (type alias)

ID union of a graph's authored nodes.

**Signature**

```ts
type GraphNodeId<Nodes extends readonly GraphNodeLike[]> = Nodes[number]["id"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L21)

### GraphNodeLike (type alias)

Authored node accepted by a graph descriptor.

**Signature**

```ts
type GraphNodeLike = GraphNodeAny | FunctionGraphNodeDescriptor | SubgraphNodeDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L18)

### GraphOutput (type alias)

Output inferred from a graph descriptor.

**Signature**

```ts
type GraphOutput<Graph extends GraphDescriptor> = InferOutput<Graph["output"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L106)

### GraphState (type alias)

State value inferred from a LangGraph StateSchema.

**Signature**

```ts
type GraphState<State extends AnyStateSchema> = State["State"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L24)

### GraphStateKey (type alias)

Public state keys selected from a LangGraph StateSchema.

**Signature**

```ts
type GraphStateKey<State extends AnyStateSchema> = Extract<keyof GraphState<State>, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-graph.types.ts#L27)

## `define-persistence-guards.ts`

Recognizes supported native checkpointer and store shapes before persistence descriptors accept them, preserving SDK identity rather than cloning resources.

### assertPersistenceProtocol

Validates a resolved handle for existing synchronous callers.

**Throws**

The original protocol TypeError.

**Example**

```ts
assertPersistenceProtocol("memory", store);
```

**Signature**

```ts
declare const assertPersistenceProtocol: (
  resource: "checkpointer" | "memory",
  value: unknown,
) => asserts value is BaseCheckpointSaver | BaseStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence-guards.ts#L68)

### assertPersistenceProtocolEffect

Validates a resolved LangGraph checkpointer or memory store.

**Example**

```ts
Effect.runSync(assertPersistenceProtocolEffect("memory", store));
```

**Signature**

```ts
declare const assertPersistenceProtocolEffect: (
  resource: "checkpointer" | "memory",
  value: unknown,
) => Effect.Effect<void, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence-guards.ts#L44)

### isPersistenceResource

Checks a resource for existing synchronous callers.

**Example**

```ts
if (isPersistenceResource(value)) await value.acquire(context);
```

**Signature**

```ts
declare const isPersistenceResource: (value: unknown) => value is PersistenceResource<any, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence-guards.ts#L34)

### isPersistenceResourceEffect

Checks whether a value is a RELKIT persistence resource descriptor.

**Example**

```ts
Effect.runSync(isPersistenceResourceEffect(candidate));
```

**Signature**

```ts
declare const isPersistenceResourceEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence-guards.ts#L15)

## `define-persistence.ts`

Creates native persistence descriptors around authored checkpointers and stores; runtime acquisition and release remain owned by the invocation scope.

### "./define-persistence.types.js" (namespace export)

Re-exports all named exports from the "./define-persistence.types.js" module.

**Signature**

```ts
export * from "./define-persistence.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L17)

### assertPersistenceProtocol

**Signature**

```ts
declare const assertPersistenceProtocol: (
  resource: "checkpointer" | "memory",
  value: unknown,
) => asserts value is BaseCheckpointSaver | BaseStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L19)

### assertPersistenceProtocolEffect

**Signature**

```ts
declare const assertPersistenceProtocolEffect: (
  resource: "checkpointer" | "memory",
  value: unknown,
) => Effect.Effect<void, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L20)

### defineCheckpointerDb

Defines a checkpointer for existing synchronous authoring callers.

**Throws**

The original invalid options error.

**Example**

```ts
const resource = defineCheckpointerDb({ id: "db", client: saver });
```

**Signature**

```ts
declare const defineCheckpointerDb: <Value extends BaseCheckpointSaver>(
  options: PersistenceOptions<Value>,
) => CheckpointerResource<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L45)

### defineCheckpointerDbEffect

Defines a lazily acquired checkpointer resource.

**Example**

```ts
Effect.runSync(defineCheckpointerDbEffect({ id: "db", client: saver }));
```

**Signature**

```ts
declare const defineCheckpointerDbEffect: <Value extends BaseCheckpointSaver>(
  options: PersistenceOptions<Value>,
) => Effect.Effect<PersistenceResource<"checkpointer", Value>, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L30)

### defineMemoryDb

Defines a memory store for existing synchronous authoring callers.

**Throws**

The original invalid options error.

**Example**

```ts
const resource = defineMemoryDb({ id: "memory", client: store });
```

**Signature**

```ts
declare const defineMemoryDb: <Value extends BaseStore>(
  options: PersistenceOptions<Value>,
) => MemoryResource<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L75)

### defineMemoryDbEffect

Defines a lazily acquired memory store resource.

**Example**

```ts
Effect.runSync(defineMemoryDbEffect({ id: "memory", client: store }));
```

**Signature**

```ts
declare const defineMemoryDbEffect: <Value extends BaseStore>(
  options: PersistenceOptions<Value>,
) => Effect.Effect<PersistenceResource<"memory", Value>, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L60)

### isPersistenceResource

**Signature**

```ts
declare const isPersistenceResource: (value: unknown) => value is PersistenceResource<any, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L21)

### isPersistenceResourceEffect

**Signature**

```ts
declare const isPersistenceResourceEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.ts#L22)

## `define-persistence.types.ts`

Creates native persistence descriptors around authored checkpointers and stores; runtime acquisition and release remain owned by the invocation scope. This companion preserves the native input and output types without starting runtime work.

### CheckpointerResource (type alias)

Checkpointer resource passed to a LangGraph runtime.

**Signature**

```ts
type CheckpointerResource<Value extends BaseCheckpointSaver = BaseCheckpointSaver> =
  PersistenceResource<"checkpointer", Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.types.ts#L24)

### MemoryResource (type alias)

Memory store resource passed to a LangGraph runtime.

**Signature**

```ts
type MemoryResource<Value extends BaseStore = BaseStore> = PersistenceResource<"memory", Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.types.ts#L27)

### PersistenceContext (interface)

Environment made available while acquiring persistence.

**Signature**

```ts
export interface PersistenceContext {
  readonly env: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.types.ts#L8)

### PersistenceOptions (interface)

Acquisition and disposal configuration for an agent persistence resource.

**Signature**

```ts
export interface PersistenceOptions<Value> {
  readonly id: string;
  readonly client: Value | ((context: PersistenceContext) => MaybePromise<Value>);
  readonly ownership?: "owned" | "borrowed";
  readonly dispose?: (value: Value) => MaybePromise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.types.ts#L33)

### PersistenceResource (interface)

Lazily acquired, explicitly released persistence descriptor.

**Signature**

```ts
export interface PersistenceResource<Kind extends "checkpointer" | "memory", Value> {
  readonly [RELKIT_PERSISTENCE]: true;
  readonly kind: "agent-persistence";
  readonly resource: Kind;
  readonly id: string;
  readonly ownership: "owned" | "borrowed";
  readonly acquire: (context: PersistenceContext) => Promise<Value>;
  readonly release: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/define-persistence.types.ts#L13)

## `graph-compile-error.ts`

Defines typed failures for native graph compilation, preserving the graph identity and underlying native compile cause.

### GraphCompilationFailure (class)

Tagged graph compilation or route execution failure.

**Signature**

```ts
declare class GraphCompilationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-compile-error.ts#L6)

### graphCompilationFailure

Preserves a graph compilation or route error for Effect callers.

**Example**

```ts
graphCompilationFailure(new TypeError("invalid route"));
```

**Signature**

```ts
declare const graphCompilationFailure: (cause: unknown) => GraphCompilationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-compile-error.ts#L16)

## `graph-compile.ts`

Compiles validated RELKIT graph descriptors into LangGraph execution objects using the authored nodes, edges, state and persistence options.

### compileGraph

Compiles a graph for existing synchronous runtime callers.

**Throws**

The original compilation error.

**Example**

```ts
const runnable = compileGraph(graph);
```

**Signature**

```ts
declare const compileGraph: (
  descriptor: GraphDescriptor,
  persistence?: ResolvedGraphPersistence,
) => any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-compile.ts#L112)

### compileGraphEffect

Compiles a graph descriptor and its resolved persistence resources.

**Example**

```ts
Effect.runSync(compileGraphEffect(graph));
```

**Signature**

```ts
declare const compileGraphEffect: (
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  persistence?: ResolvedGraphPersistence | undefined,
) => Effect.Effect<any, GraphCompilationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-compile.ts#L61)

### runGraphRouteEffect

Runs a user route and validates its destination with linked cancellation.

**Example**

```ts
await Effect.runPromise(runGraphRouteEffect(route, state, config, ids));
```

**Signature**

```ts
declare const runGraphRouteEffect: <Id extends string>(
  route: (state: unknown, config: LangGraphRunnableConfig) => MaybePromise<unknown>,
  state: unknown,
  config: LangGraphRunnableConfig<Record<string, any>>,
  nodeIds: ReadonlySet<Id>,
  destinations?: Readonly<Record<string, "__end__" | Id>> | undefined,
) => Effect.Effect<unknown, GraphCompilationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-compile.ts#L25)

## `graph-continuation-error.ts`

Defines continuation failures for persisted native graphs so invalid or unavailable resume state remains distinct from invocation failures.

### GraphContinuationFailure (class)

Tagged validation or state failure while resuming a graph.

**Signature**

```ts
declare class GraphContinuationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-error.ts#L6)

### graphContinuationFailure

Preserves the original graph continuation error.

**Example**

```ts
graphContinuationFailure(new TypeError("invalid reply"));
```

**Signature**

```ts
declare const graphContinuationFailure: (cause: unknown) => GraphContinuationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-error.ts#L16)

## `graph-continuation-validation.ts`

Checks persisted graph continuation input and identity before native resume admission, preventing execution against a mismatched thread or graph.

### validateGraphResumeInput

Validates graph continuation replies for existing Promise callers.

**Throws**

The original continuation validation error.

**Example**

```ts
await validateGraphResumeInput(graph, requests, reply);
```

**Signature**

```ts
declare const validateGraphResumeInput: (
  descriptor: GraphDescriptor,
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-validation.ts#L67)

### validateGraphResumeInputEffect

Validates one or more graph continuation replies with bounded concurrency.

**Example**

```ts
Effect.runPromise(validateGraphResumeInputEffect(graph, requests, reply));
```

**Signature**

```ts
declare const validateGraphResumeInputEffect: (
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  requests: ReadonlyArray<AgentWaitingRequest>,
  value: unknown,
) => Effect.Effect<unknown, GraphContinuationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-validation.ts#L19)

## `graph-continuation-waiting.ts`

Projects native graph interrupts into durable waiting state used by the RELKIT continuation protocol before returning control to callers.

### waitingInterrupts

Reads waiting interrupts for existing Promise callers.

**Throws**

The original graph state or schema failure.

**Example**

```ts
await waitingInterrupts(graph, descriptor, config);
```

**Signature**

```ts
declare const waitingInterrupts: (
  graph: CompiledGraph,
  descriptor: GraphDescriptor,
  config: GraphConfig,
) => Promise<readonly GraphWaitingInterrupt[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-waiting.ts#L42)

### waitingInterruptsEffect

Reads waiting interrupts from the graph state snapshot.

**Example**

```ts
Effect.runPromise(waitingInterruptsEffect(graph, descriptor, config));
```

**Signature**

```ts
declare const waitingInterruptsEffect: (
  graph: any,
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  config: GraphConfig,
) => Effect.Effect<ReadonlyArray<GraphWaitingInterrupt>, GraphContinuationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation-waiting.ts#L20)

## `graph-continuation.ts`

Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity.

### GraphConfig

**Signature**

```ts
declare const GraphConfig: GraphConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L13)

### graphConfig

Builds graph run configuration for existing synchronous callers.

**Throws**

The original missing thread error.

**Example**

```ts
const config = graphConfig(graph, "thread");
```

**Signature**

```ts
declare const graphConfig: (descriptor: GraphDescriptor, threadId?: string) => GraphConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L48)

### graphConfigEffect

Builds a persistent graph run configuration.

**Example**

```ts
Effect.runSync(graphConfigEffect(graph, "thread"));
```

**Signature**

```ts
declare const graphConfigEffect: (
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  threadId?: string | undefined,
) => Effect.Effect<GraphConfig, GraphContinuationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L26)

### resumeCommand

Constructs a native resume command for existing Promise callers.

**Throws**

The original state or continuation validation error.

**Example**

```ts
await resumeCommand(graph, descriptor, config, reply);
```

**Signature**

```ts
declare const resumeCommand: (
  graph: CompiledGraph,
  descriptor: GraphDescriptor,
  config: GraphConfig,
  value: unknown,
) => Promise<Command>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L98)

### resumeCommandEffect

Validates a reply and constructs a native LangGraph resume command.

**Example**

```ts
Effect.runPromise(resumeCommandEffect(graph, descriptor, config, reply));
```

**Signature**

```ts
declare const resumeCommandEffect: (
  graph: any,
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  config: GraphConfig,
  value: unknown,
) => Effect.Effect<
  Command<unknown, Record<string, unknown>, string>,
  GraphContinuationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L64)

### validateGraphResumeInput

**Signature**

```ts
declare const validateGraphResumeInput: (
  descriptor: GraphDescriptor,
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L15)

### validateGraphResumeInputEffect

**Signature**

```ts
declare const validateGraphResumeInputEffect: (
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  requests: ReadonlyArray<AgentWaitingRequest>,
  value: unknown,
) => Effect.Effect<unknown, GraphContinuationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L16)

### waitingInterrupts

**Signature**

```ts
declare const waitingInterrupts: (
  graph: CompiledGraph,
  descriptor: GraphDescriptor,
  config: GraphConfig,
) => Promise<readonly GraphWaitingInterrupt[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L18)

### waitingInterruptsEffect

**Signature**

```ts
declare const waitingInterruptsEffect: (
  graph: any,
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  config: GraphConfig,
) => Effect.Effect<ReadonlyArray<GraphWaitingInterrupt>, GraphContinuationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.ts#L18)

## `graph-continuation.types.ts`

Coordinates native graph resume requests with persisted waiting state and the invocation scope, preserving continuation failures and thread identity. This companion preserves the native input and output types without starting runtime work.

### CompiledGraph (type alias)

Compiled graph accepted by continuation helpers.

**Signature**

```ts
type CompiledGraph = ReturnType<typeof compileGraph>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.types.ts#L9)

### GraphConfig (type alias)

LangGraph run configuration with an optional persistent thread identity.

**Signature**

```ts
type GraphConfig = {} | { readonly configurable: { readonly thread_id: string } };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-continuation.types.ts#L6)

## `graph-definition.ts`

Validates graph structure and resolves authored node identities before native compilation, reporting missing or inconsistent graph definitions.

### prepareGraphDefinition

Validates graph authoring for existing synchronous callers.

**Throws**

The original graph authoring error.

**Example**

```ts
const prepared = prepareGraphDefinition(state, input, output, nodes, edges);
```

**Signature**

```ts
declare const prepareGraphDefinition: (
  state: AnyStateSchema,
  input: StandardSchemaV1,
  output: StandardSchemaV1,
  sourceNodes: readonly GraphNodeLike[],
  edges: (builder: GraphEdgeBuilder<string, any>) => unknown,
) => {
  readonly nodes: readonly GraphNodeLike[];
  readonly operations: readonly GraphEdgeOperation<string, any>[];
  readonly stateKeys: Set<string>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-definition.ts#L53)

### prepareGraphDefinitionEffect

Validates graph state, nodes, and edge declarations.

**Example**

```ts
Effect.runSync(prepareGraphDefinitionEffect(state, input, output, nodes, edges));
```

**Signature**

```ts
declare const prepareGraphDefinitionEffect: (
  state: AnyStateSchema,
  input: StandardSchemaV1<unknown, unknown>,
  output: StandardSchemaV1<unknown, unknown>,
  sourceNodes: ReadonlyArray<GraphNodeLike>,
  edges: (builder: GraphEdgeBuilder<string, any>) => unknown,
) => Effect.Effect<
  {
    readonly nodes: readonly GraphNodeLike[];
    readonly operations: readonly GraphEdgeOperation<string, any>[];
    readonly stateKeys: Set<string>;
  },
  GraphDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-definition.ts#L28)

## `graph-edge-destinations.ts`

Validates native graph endpoints and conditional route results before execution.
Mutation builders reuse the same endpoint and duplicate-edge rules.

### addUnique

**Signature**

```ts
declare const addUnique: (signatures: Set<string>, signature: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L140)

### assertEndpoint

**Signature**

```ts
declare const assertEndpoint: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
  source: boolean,
) => asserts value is Id | typeof START | typeof END;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L122)

### assertGraphDestination

Checks native route targets for existing synchronous callers.

**Throws**

The original invalid destination error.

**Example**

```ts
assertGraphDestination("next", ids);
```

**Signature**

```ts
declare const assertGraphDestination: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L32)

### assertGraphDestinationEffect

Checks native route targets against registered nodes.

**Example**

```ts
Effect.runSync(assertGraphDestinationEffect("next", ids));
```

**Signature**

```ts
declare const assertGraphDestinationEffect: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
) => Effect.Effect<void, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L16)

### copyDestinations

**Signature**

```ts
declare const copyDestinations: <Id extends string>(
  value: Readonly<Record<string, Id | typeof END>>,
  nodeIds: ReadonlySet<Id>,
) => Readonly<Record<string, Id | typeof END>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L112)

### validateGraphRoute

Validates dynamic routes for existing synchronous callers.

**Throws**

The original invalid route error.

**Example**

```ts
validateGraphRoute("yes", ids, { yes: "next" });
```

**Signature**

```ts
declare const validateGraphRoute: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
  destinations?: Readonly<Record<string, Id | typeof END>>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L82)

### validateGraphRouteEffect

Validates dynamic route labels or node destinations.

**Example**

```ts
Effect.runSync(validateGraphRouteEffect("yes", ids, { yes: "next" }));
```

**Signature**

```ts
declare const validateGraphRouteEffect: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
  destinations?: Readonly<Record<string, "__end__" | Id>> | undefined,
) => Effect.Effect<void, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-destinations.ts#L61)

## `graph-edge-mutations.ts`

Applies validated edge mutations to one builder-owned operation log. Factories
retain that builder's closure so duplicate checks and mutation order stay local.

### conditionalEdgeMutation

Creates conditional mutations sharing one checked operation log.

**Signature**

```ts
declare const conditionalEdgeMutation: <Id extends string, State>(
  context: GraphEdgeMutationContext<Id, State>,
) => (
  source: "__start__" | Id,
  route: (state: State, config: LangGraphRunnableConfig) => MaybePromise<unknown>,
  destinations?: Readonly<Record<string, "__end__" | Id>> | undefined,
) => Effect.Effect<GraphEdgeBuilder<Id, State>, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-mutations.ts#L18)

### edgeMutation

Creates direct/join mutations sharing the same checked operation log.

**Signature**

```ts
declare const edgeMutation: <Id extends string, State>(
  context: GraphEdgeMutationContext<Id, State>,
) => (
  start: "__start__" | Id | ReadonlyArray<Id>,
  end: "__end__" | Id,
) => Effect.Effect<GraphEdgeBuilder<Id, State>, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-mutations.ts#L55)

## `graph-edge-mutations.types.ts`

One graph builder's private ordered mutation authority.

### GraphEdgeMutationContext (interface)

**Signature**

```ts
export interface GraphEdgeMutationContext<Id extends string, State> {
  readonly nodeIds: ReadonlySet<Id>;
  readonly operations: GraphEdgeOperation<Id, State>[];
  readonly signatures: Set<string>;
  readonly builder: () => GraphEdgeBuilder<Id, State>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edge-mutations.types.ts#L3)

## `graph-edges.ts`

Defines typed native graph edge and routing descriptors whose endpoints are checked during graph assembly and compilation.

### "./graph-edges.types.js" (namespace export)

Re-exports all named exports from the "./graph-edges.types.js" module.

**Signature**

```ts
export * from "./graph-edges.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L12)

### assertGraphDestination

**Signature**

```ts
declare const assertGraphDestination: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L62)

### assertGraphDestinationEffect

**Signature**

```ts
declare const assertGraphDestinationEffect: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
) => Effect.Effect<void, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L63)

### createGraphEdgeBuilder

Creates an edge builder for existing synchronous graph authoring.

**Example**

```ts
const { builder, operations } = createGraphEdgeBuilder(ids);
```

**Signature**

```ts
declare const createGraphEdgeBuilder: <Id extends string, State>(
  nodeIds: ReadonlySet<Id>,
) => {
  readonly builder: GraphEdgeBuilder<Id, State>;
  readonly operations: readonly GraphEdgeOperation<Id, State>[];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L52)

### createGraphEdgeBuilderEffect

Creates an edge builder whose mutations run through Effect.

**Example**

```ts
Effect.runSync(createGraphEdgeBuilderEffect(ids));
```

**Signature**

```ts
declare const createGraphEdgeBuilderEffect: <Id extends string, State>(
  nodeIds: ReadonlySet<Id>,
) => Effect.Effect<
  {
    builder: Readonly<GraphEdgeBuilder<Id, State>>;
    operations: Array<GraphEdgeOperation<Id, State>>;
  },
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L18)

### validateGraphRoute

**Signature**

```ts
declare const validateGraphRoute: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
  destinations?: Readonly<Record<string, Id | typeof END>>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L64)

### validateGraphRouteEffect

**Signature**

```ts
declare const validateGraphRouteEffect: <Id extends string>(
  value: unknown,
  nodeIds: ReadonlySet<Id>,
  destinations?: Readonly<Record<string, "__end__" | Id>> | undefined,
) => Effect.Effect<void, GraphDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.ts#L65)

## `graph-edges.types.ts`

Defines typed native graph edge and routing descriptors whose endpoints are checked during graph assembly and compilation. This companion preserves the native input and output types without starting runtime work.

### GraphConditionalRoute (type alias)

Label based graph conditional route callback.

**Signature**

```ts
type GraphConditionalRoute<Id extends string, State, Key extends string> = (
  state: State,
  config: LangGraphRunnableConfig,
) => MaybePromise<Key | Send<Id, Partial<State>> | readonly (Key | Send<Id, Partial<State>>)[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.types.ts#L13)

### GraphEdgeBuilder (interface)

Mutable graph edge authoring interface backed by Effect operations.

**Signature**

```ts
export interface GraphEdgeBuilder<Id extends string, State> {
  /** Adds a static or join edge.
   * @param start - One or more source nodes.
   * @param end - Destination node.
   * @returns This builder.
   * @throws TypeError for invalid or duplicate edges.
   * @example edge.addEdge("start", "finish");
   */
  addEdge(
    start: typeof START | NoInfer<Id> | readonly NoInfer<Id>[],
    end: NoInfer<Id> | typeof END,
  ): GraphEdgeBuilder<Id, State>;
  /** Adds a dynamic edge.
   * @param source - Source node.
   * @param route - Route callback.
   * @returns This builder.
   * @throws TypeError for invalid or duplicate routes.
   * @example edge.addConditionalEdges("start", () => "finish");
   */
  addConditionalEdges(
    source: typeof START | NoInfer<Id>,
    route: GraphRoute<NoInfer<Id>, State>,
  ): GraphEdgeBuilder<Id, State>;
  /** Adds a labeled dynamic edge.
   * @param source - Source node.
   * @param route - Route callback.
   * @param destinations - Label to destination mapping.
   * @returns This builder.
   * @throws TypeError for invalid or duplicate routes.
   * @example edge.addConditionalEdges("start", () => "yes", { yes: "finish" });
   */
  addConditionalEdges<const Key extends string>(
    source: typeof START | NoInfer<Id>,
    route: GraphConditionalRoute<NoInfer<Id>, State, Key>,
    destinations: Readonly<Record<Key, NoInfer<Id> | typeof END>>,
  ): GraphEdgeBuilder<Id, State>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.types.ts#L19)

### GraphEdgeOperation (type alias)

Recorded edge operation consumed by the LangGraph compiler.

**Signature**

```ts
type GraphEdgeOperation<Id extends string, State> =
  | {
      readonly kind: "edge";
      readonly start: typeof START | Id | readonly Id[];
      readonly end: Id | typeof END;
    }
  | {
      readonly kind: "conditional";
      readonly source: typeof START | Id;
      readonly route: (state: State, config: LangGraphRunnableConfig) => MaybePromise<unknown>;
      readonly destinations?: Readonly<Record<string, Id | typeof END>>;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.types.ts#L58)

### GraphRoute (type alias)

Native graph conditional route callback.

**Signature**

```ts
type GraphRoute<Id extends string, State> = (
  state: State,
  config: LangGraphRunnableConfig,
) => MaybePromise<Id | typeof END | Send<Id> | readonly (Id | Send<Id>)[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-edges.types.ts#L7)

## `graph-execution-symbol.ts`

Private nonenumerable slot holding compiled graph authoring data.

### GRAPH_EXECUTION

Private nonenumerable slot holding compiled graph authoring data.

**Signature**

```ts
declare const GRAPH_EXECUTION: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-execution-symbol.ts#L2)

## `graph-interruption.ts`

Converts native graph interrupt observations into RELKIT continuation data while preserving the interrupt identifiers needed for resume.

### GraphInterruptedError (class)

Internal control result used by the server to publish a durable waiting snapshot.

**Example**

```ts
throw new GraphInterruptedError("thread-1", interrupts);
```

**Signature**

```ts
declare class GraphInterruptedError { constructor(
    readonly threadId: string,
    readonly interrupts: readonly GraphWaitingInterrupt[],
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L115)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_GRAPH_INTERRUPTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L116)

### GraphWaitingInterrupt

**Signature**

```ts
declare const GraphWaitingInterrupt: GraphWaitingInterrupt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L9)

### GraphWaitingResponseError (class)

No pending request is available to form a graph interruption response.

**Signature**

```ts
declare class GraphWaitingResponseError
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L17)

### graphWaitingResponse

Combines pending graph responses for synchronous runtime callers.

**Throws**

TypeError when no request is pending.

**Example**

```ts
const response = graphWaitingResponse([{ node: "review", response: true }]);
```

**Signature**

```ts
declare const graphWaitingResponse: (interrupts: readonly GraphWaitingInterrupt[]) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L63)

### graphWaitingResponseEffect

Combines pending graph responses into one JSON schema.

**Example**

```ts
const response = Effect.runSync(graphWaitingResponseEffect([{ node: "review", response: true }]));
```

**Signature**

```ts
declare const graphWaitingResponseEffect: (
  interrupts: ReadonlyArray<GraphWaitingInterrupt>,
) => Effect.Effect<JsonValue, GraphWaitingResponseError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L30)

### isGraphInterruptedError

Recognizes graph interruption errors for synchronous callers.

**Example**

```ts
if (isGraphInterruptedError(error)) console.log(error.threadId);
```

**Signature**

```ts
declare const isGraphInterruptedError: (value: unknown) => value is GraphInterruptedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L151)

### isGraphInterruptedErrorEffect

Recognizes the internal graph interruption control result.

**Example**

```ts
const interrupted = Effect.runSync(isGraphInterruptedErrorEffect(error));
```

**Signature**

```ts
declare const isGraphInterruptedErrorEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L135)

### publicWaitingRequests

Returns public waiting requests for synchronous runtime callers.

**Example**

```ts
const requests = publicWaitingRequests(interrupts);
```

**Signature**

```ts
declare const publicWaitingRequests: (
  interrupts: readonly GraphWaitingInterrupt[],
) => readonly AgentWaitingRequest[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L103)

### publicWaitingRequestsEffect

Removes internal identifiers while retaining public waiting request order.

**Example**

```ts
const requests = Effect.runSync(publicWaitingRequestsEffect(interrupts));
```

**Signature**

```ts
declare const publicWaitingRequestsEffect: (
  interrupts: ReadonlyArray<GraphWaitingInterrupt>,
) => Effect.Effect<Array<{ response: JsonValue; value?: {} | null; node: string }>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.ts#L83)

## `graph-interruption.types.ts`

Converts native graph interrupt observations into RELKIT continuation data while preserving the interrupt identifiers needed for resume. This companion preserves the native input and output types without starting runtime work.

### GraphWaitingInterrupt (interface)

Pending graph interruption and its public response schema.
The optional ID is internal and omitted from published waiting requests.

**Example**

```ts
const interrupt: GraphWaitingInterrupt = { node: "review", response: true };
```

**Signature**

```ts
export interface GraphWaitingInterrupt {
  readonly id?: string;
  readonly node: string;
  readonly value?: unknown;
  readonly response: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-interruption.types.ts#L12)

## `graph-node-schema-validation.ts`

Validates native node input, output and optional resume schemas in authoring order before handler or identity construction; schema failures retain their existing graph-node boundary.

### validateGraphNodeSchemasEffect

Validates each authored schema without invoking the user's node handler.

**Signature**

```ts
declare const validateGraphNodeSchemasEffect: (
  options: Pick<GraphNodeAny, "input" | "output" | "resume">,
) => Effect.Effect<void, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-schema-validation.ts#L12)

## `graph-node-symbol.ts`

Private brand identifying a validated RELKIT graph node.

### RELKIT_GRAPH_NODE

Private brand identifying a validated RELKIT graph node.

**Signature**

```ts
declare const RELKIT_GRAPH_NODE: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-symbol.ts#L2)

## `graph-node-validation-error.ts`

Defines authoring failures for native graph nodes and retains the invalid field for focused descriptor diagnostics.

### GraphNodeValidationFailure (class)

Tagged graph node validation failure.

**Signature**

```ts
declare class GraphNodeValidationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-error.ts#L6)

### graphNodeValidationFailure

Preserves a graph node validation error for Effect callers.

**Example**

```ts
graphNodeValidationFailure(new TypeError("invalid"));
```

**Signature**

```ts
declare const graphNodeValidationFailure: (cause: unknown) => GraphNodeValidationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-error.ts#L16)

## `graph-node-validation-value.ts`

Checks graph node authoring values and callable shapes before construction, keeping runtime callbacks untouched after validation.

### commandUpdate

Converts a native command update for existing synchronous callers.

**Throws**

TypeError for malformed entry lists.

**Example**

```ts
commandUpdate([["count", 1]]);
```

**Signature**

```ts
declare const commandUpdate: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L75)

### commandUpdateEffect

Converts a native command update entry list into an object.

**Example**

```ts
Effect.runSync(commandUpdateEffect([["count", 1]]));
```

**Signature**

```ts
declare const commandUpdateEffect: (
  value: unknown,
) => Effect.Effect<unknown, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L63)

### validateDestinations

Checks native command destinations for existing synchronous callers.

**Throws**

TypeError for invalid or undeclared destinations.

**Example**

```ts
validateDestinations(["next"], "next");
```

**Signature**

```ts
declare const validateDestinations: (ends: readonly string[], value: unknown) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L31)

### validateDestinationsEffect

Checks that native command destinations were declared by the node.

**Example**

```ts
Effect.runSync(validateDestinationsEffect(["next"], "next"));
```

**Signature**

```ts
declare const validateDestinationsEffect: (
  ends: ReadonlyArray<string>,
  value: unknown,
) => Effect.Effect<void, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L15)

### validatedUpdate

Validates a node output for existing Promise callers.

**Throws**

The original schema or record error.

**Example**

```ts
await validatedUpdate(schema, output);
```

**Signature**

```ts
declare const validatedUpdate: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
) => Promise<Extract<InferOutput<Schema>, Record<string, unknown>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L121)

### validatedUpdateEffect

Validates a graph node output as a record.

**Example**

```ts
await Effect.runPromise(validatedUpdateEffect(schema, output));
```

**Signature**

```ts
declare const validatedUpdateEffect: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
) => Effect.Effect<
  Extract<InferOutput<Schema>, Record<string, unknown>>,
  GraphNodeValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L101)

### validatedValue

Validates a node value for existing Promise callers.

**Throws**

The original schema validation error.

**Example**

```ts
await validatedValue(schema, input, "input");
```

**Signature**

```ts
declare const validatedValue: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
  phase: "input" | "output",
) => Promise<InferOutput<Schema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L165)

### validatedValueEffect

Validates a graph node input or output through its Standard Schema.

**Example**

```ts
await Effect.runPromise(validatedValueEffect(schema, input, "input"));
```

**Signature**

```ts
declare const validatedValueEffect: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
  phase: "input" | "output",
) => Effect.Effect<InferOutput<Schema>, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation-value.ts#L139)

## `graph-node-validation.ts`

Validates native graph node contracts and execution configuration before the node descriptor is published to graph assembly.

### assertGraphNodeDestinations

Checks destinations for existing synchronous graph callers.

**Throws**

The original unknown destination error.

**Example**

```ts
assertGraphNodeDestinations(node, ids);
```

**Signature**

```ts
declare const assertGraphNodeDestinations: (
  node: Pick<GraphNodeAny, "id" | "ends">,
  registeredNodeIds: ReadonlySet<string> | readonly string[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L52)

### assertGraphNodeDestinationsEffect

Checks that every declared node destination exists in the graph.

**Example**

```ts
Effect.runSync(assertGraphNodeDestinationsEffect(node, ids));
```

**Signature**

```ts
declare const assertGraphNodeDestinationsEffect: (
  node: Pick<GraphNodeAny, "id" | "ends">,
  registeredNodeIds: ReadonlyArray<string> | ReadonlySet<string>,
) => Effect.Effect<void, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L23)

### copyGraphNodeEnds

Copies destinations for existing synchronous graph callers.

**Throws**

The original invalid or duplicate destination error.

**Example**

```ts
const ends = copyGraphNodeEnds([END]);
```

**Signature**

```ts
declare const copyGraphNodeEnds: (value: readonly string[] | undefined) => readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L93)

### copyGraphNodeEndsEffect

Validates and freezes a node's static destination list.

**Example**

```ts
Effect.runSync(copyGraphNodeEndsEffect([END]));
```

**Signature**

```ts
declare const copyGraphNodeEndsEffect: (
  value: ReadonlyArray<string> | undefined,
) => Effect.Effect<ReadonlyArray<string>, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L68)

### validateGraphNodeResult

Validates a node result for existing Promise graph callers.

**Throws**

The original schema, update, or destination error.

**Example**

```ts
await validateGraphNodeResult(schema, [], value);
```

**Signature**

```ts
declare const validateGraphNodeResult: <
  OutputSchema extends StandardSchemaV1,
  Ends extends readonly string[],
>(
  output: OutputSchema,
  ends: Ends,
  result: unknown,
) => Promise<GraphNodeResult<OutputSchema, Ends>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L135)

### validateGraphNodeResultEffect

Validates a node result and any native command update.

**Example**

```ts
Effect.runPromise(validateGraphNodeResultEffect(schema, [], value));
```

**Signature**

```ts
declare const validateGraphNodeResultEffect: <
  OutputSchema extends StandardSchemaV1,
  Ends extends readonly string[],
>(
  output: OutputSchema,
  ends: Ends,
  result: unknown,
) => Effect.Effect<GraphNodeResult<OutputSchema, Ends>, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L108)

### validatedGraphNodeInput

Validates graph node input for existing Promise graph callers.

**Throws**

The original schema validation error.

**Example**

```ts
await validatedGraphNodeInput(schema, value);
```

**Signature**

```ts
declare const validatedGraphNodeInput: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
) => Promise<InferOutput<Schema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L165)

### validatedGraphNodeInputEffect

Validates graph node input against its standard schema.

**Example**

```ts
Effect.runPromise(validatedGraphNodeInputEffect(schema, value));
```

**Signature**

```ts
declare const validatedGraphNodeInputEffect: <Schema extends StandardSchemaV1>(
  schema: Schema,
  value: unknown,
) => Effect.Effect<InferOutput<Schema>, GraphNodeValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-node-validation.ts#L152)

## `graph-persistence-release.ts`

Releases native graph persistence resources through their supported close protocol after graph work has settled.

### releaseAgentPersistence

Releases persistence resources for existing Promise callers.

**Throws**

The first release error in descriptor order.

**Example**

```ts
await releaseAgentPersistence([agent]);
```

**Signature**

```ts
declare const releaseAgentPersistence: (descriptors: readonly unknown[]) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence-release.ts#L45)

### releaseAgentPersistenceEffect

Releases declared persistence resources with bounded concurrency.

**Example**

```ts
Effect.runPromise(releaseAgentPersistenceEffect([agent]));
```

**Signature**

```ts
declare const releaseAgentPersistenceEffect: (
  descriptors: ReadonlyArray<unknown>,
) => Effect.Effect<undefined, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence-release.ts#L15)

## `graph-persistence.ts`

Acquires native graph checkpointer and store configuration for invocation and supplies the release action to the owning graph scope.

### AgentPersistenceDeclaration

**Signature**

```ts
declare const AgentPersistenceDeclaration: AgentPersistenceDeclaration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L17)

### ResolvedGraphPersistence

**Signature**

```ts
declare const ResolvedGraphPersistence: ResolvedGraphPersistence;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L18)

### releaseAgentPersistence

**Signature**

```ts
declare const releaseAgentPersistence: (descriptors: readonly unknown[]) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L21)

### releaseAgentPersistenceEffect

**Signature**

```ts
declare const releaseAgentPersistenceEffect: (
  descriptors: ReadonlyArray<unknown>,
) => Effect.Effect<undefined, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L22)

### resolveAgentPersistence

Resolves agent persistence for existing Promise callers.

**Throws**

The original factory or protocol error.

**Example**

```ts
await resolveAgentPersistence(agent, {});
```

**Signature**

```ts
declare const resolveAgentPersistence: (
  descriptor: AgentPersistenceDeclaration,
  env: Readonly<Record<string, unknown>>,
  signal?: AbortSignal,
) => Promise<ResolvedGraphPersistence>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L89)

### resolveAgentPersistenceEffect

Resolves an agent's declared persistence handles.

**Example**

```ts
Effect.runPromise(resolveAgentPersistenceEffect(agent, {}));
```

**Signature**

```ts
declare const resolveAgentPersistenceEffect: (
  descriptor: AgentPersistenceDeclaration,
  env: Readonly<Record<string, unknown>>,
) => Effect.Effect<ResolvedGraphPersistence, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L73)

### resolveGraphPersistence

Resolves graph persistence for existing Promise callers.

**Throws**

The original factory or protocol error.

**Example**

```ts
await resolveGraphPersistence(graph, {});
```

**Signature**

```ts
declare const resolveGraphPersistence: (
  descriptor: GraphDescriptor,
  env: Readonly<Record<string, unknown>>,
  signal?: AbortSignal,
) => Promise<ResolvedGraphPersistence>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L53)

### resolveGraphPersistenceEffect

Resolves a graph's declared persistence handles.

**Example**

```ts
Effect.runPromise(resolveGraphPersistenceEffect(graph, {}));
```

**Signature**

```ts
declare const resolveGraphPersistenceEffect: (
  descriptor: GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  env: Readonly<Record<string, unknown>>,
) => Effect.Effect<ResolvedGraphPersistence, AgentPersistenceFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.ts#L34)

## `graph-persistence.types.ts`

Acquires native graph checkpointer and store configuration for invocation and supplies the release action to the owning graph scope. This companion preserves the native input and output types without starting runtime work.

### AgentPersistenceDeclaration (interface)

Optional checkpointer and store declarations on an agent.

**Signature**

```ts
export interface AgentPersistenceDeclaration {
  readonly checkpointer?: unknown;
  readonly store?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.types.ts#L13)

### AnyPersistenceResource (type alias)

A persistence descriptor being resolved for one invocation.

**Signature**

```ts
type AnyPersistenceResource = PersistenceResource<"checkpointer" | "memory", unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.types.ts#L19)

### ResolutionState (interface)

Pending and committed resolution state for one shared resource.

**Signature**

```ts
export interface ResolutionState {
  pending: number;
  committed: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.types.ts#L22)

### ResolvedGraphPersistence (interface)

Resolved handles passed to a compiled graph.

**Signature**

```ts
export interface ResolvedGraphPersistence {
  readonly checkpointer?: BaseCheckpointSaver;
  readonly store?: BaseStore;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-persistence.types.ts#L7)

## `graph-runtime-error.ts`

Translates native graph execution failures into the RELKIT graph error boundary while preserving their original causes.

### GraphInvocationFailure (class)

Tagged graph invocation failure with the original runtime cause.

**Signature**

```ts
declare class GraphInvocationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-error.ts#L6)

### graphInvocationFailure

Preserves a graph invocation failure for Effect callers.

**Example**

```ts
graphInvocationFailure(new Error("graph failed"));
```

**Signature**

```ts
declare const graphInvocationFailure: (cause: unknown) => GraphInvocationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-error.ts#L16)

## `graph-runtime-execution.ts`

Runs a compiled graph within the invocation context, coordinating input, continuation and persistence before projecting final output.

### runCompiledGraph

Runs a compiled graph for existing Promise callers.

**Throws**

The original graph, persistence, output, or cancellation error.

**Example**

```ts
await runCompiledGraph(options, input, signal, id, trace, 1024);
```

**Signature**

```ts
declare const runCompiledGraph: (
  options: GraphRuntimeOptions,
  input: unknown,
  signal: AbortSignal,
  invocationId: string,
  traceId: string,
  maxOutputBytes: number,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-execution.ts#L88)

### runCompiledGraphEffect

Runs one compiled graph with persistence and a linked invocation scope.

**Example**

```ts
await Effect.runPromise(runCompiledGraphEffect(options, input, signal, id, trace, 1024));
```

**Signature**

```ts
declare const runCompiledGraphEffect: (
  options: GraphRuntimeOptions,
  input: unknown,
  signal: AbortSignal,
  invocationId: string,
  traceId: string,
  maxOutputBytes: number,
) => Effect.Effect<JsonValue, GraphInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-execution.ts#L26)

## `graph-runtime-identity.ts`

Derives graph invocation, thread and checkpoint identity used consistently by native execution and persisted continuation lookup.

### GraphInvocationIdentity (class)

Substitutable random source for graph invocation IDs.

**Example**

```ts
Effect.provide(invokeGraphEffect(options), GraphInvocationIdentityLive);
```

**Signature**

```ts
declare class GraphInvocationIdentity
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-identity.ts#L9)

### GraphInvocationIdentityLive

Live graph invocation identity source.

**Example**

```ts
Effect.runPromise(Effect.provide(invokeGraphEffect(options), GraphInvocationIdentityLive));
```

**Signature**

```ts
declare const GraphInvocationIdentityLive: Layer.Layer<GraphInvocationIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-identity.ts#L17)

## `graph-runtime-identity.types.ts`

Random identity source used by graph invocation Effects.

### GraphInvocationIdentityService (interface)

Random identity source used by graph invocation Effects.

**Signature**

```ts
export interface GraphInvocationIdentityService {
  readonly randomUUID: () => string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-identity.types.ts#L2)

## `graph-runtime-stream-state.ts`

Collects graph state, waiting requests and validated output from an already
acquired native stream. Its caller retains stream abort/finalization ownership.

### collectCompiledGraphStateEffect

Collects the original native events before settling public graph state.

**Signature**

```ts
declare const collectCompiledGraphStateEffect: (
  context: CompiledGraphStreamContext,
) => Effect.Effect<JsonValue, GraphInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-stream-state.ts#L25)

## `graph-runtime-stream.ts`

Consumes native graph streams and publishes RELKIT execution events, finalizing the native iterator before settling the invocation.

### streamCompiledGraphEffect

Streams one compiled graph and validates its final public output.

**Example**

```ts
await Effect.runPromise(streamCompiledGraphEffect(options, graph, config, input, signal, 1024));
```

**Signature**

```ts
declare const streamCompiledGraphEffect: (
  options: GraphRuntimeOptions,
  graph: any,
  config: GraphConfig,
  input: unknown,
  signal: AbortSignal,
  maxOutputBytes: number,
) => Effect.Effect<JsonValue, GraphInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-stream.ts#L33)

## `graph-runtime-stream.types.ts`

Acquired native stream and public sinks retained by one graph invocation.

### CompiledGraphStreamContext (interface)

**Signature**

```ts
export interface CompiledGraphStreamContext {
  readonly options: GraphRuntimeOptions;
  readonly graph: ReturnType<typeof compileGraph>;
  readonly config: GraphConfig;
  readonly signal: AbortSignal;
  readonly maxOutputBytes: number;
  readonly run: Awaited<ReturnType<ReturnType<typeof compileGraph>["streamEvents"]>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime-stream.types.ts#L5)

## `graph-runtime.ts`

Composes graph compilation, scoped persistence and execution into the native invocation entrypoint, retaining stream and continuation behavior.

### GraphInvocationFailure

**Signature**

```ts
declare const GraphInvocationFailure: typeof GraphInvocationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L17)

### GraphInvocationIdentity

**Signature**

```ts
declare const GraphInvocationIdentity: typeof GraphInvocationIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L18)

### GraphInvocationIdentityLive

**Signature**

```ts
declare const GraphInvocationIdentityLive: Layer<GraphInvocationIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L18)

### GraphRuntimeOptions

**Signature**

```ts
declare const GraphRuntimeOptions: GraphRuntimeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L16)

### invokeGraph

Invokes a graph for existing Promise runtime callers.

**Throws**

The original graph, provider, validation, or cancellation error.

**Example**

```ts
await invokeGraph(options);
```

**Signature**

```ts
declare const invokeGraph: (options: GraphRuntimeOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L84)

### invokeGraphEffect

Invokes a graph with scoped signal cleanup and linked Effect cancellation.

**Example**

```ts
Effect.runPromise(Effect.provide(invokeGraphEffect(options), GraphInvocationIdentityLive));
```

**Signature**

```ts
declare const invokeGraphEffect: (
  options: GraphRuntimeOptions,
) => Effect.Effect<unknown, GraphInvocationFailure, GraphInvocationIdentity>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.ts#L25)

## `graph-runtime.types.ts`

Composes graph compilation, scoped persistence and execution into the native invocation entrypoint, retaining stream and continuation behavior. This companion preserves the native input and output types without starting runtime work.

### GraphRuntimeOptions (type alias)

Runtime options for invoking a compiled graph descriptor.

**Signature**

```ts
type GraphRuntimeOptions = AgentRuntimeOptions &
  AgentInvocationOptions & { readonly agent: GraphDescriptor };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-runtime.types.ts#L7)

## `graph-state-schema.ts`

Adapts authored state schemas to the native graph state contract and preserves the reducers and validated channel shapes required by compilation.

### GraphStateSelectionError (class)

Expected graph state projection failure in the Effect error channel.

**Signature**

```ts
declare class GraphStateSelectionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-state-schema.ts#L13)

### selectGraphState

Projects graph state for existing synchronous graph definition callers.

**Throws**

AgentRuntimeError when the selection or one of its fields is unavailable.

**Example**

```ts
const projected = selectGraphState(state, z.object({ answer: z.string() }));
```

**Signature**

```ts
declare const selectGraphState: (
  state: AnyStateSchema,
  selection: StandardSchemaV1,
) => AnyStateSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-state-schema.ts#L71)

### selectGraphStateEffect

Projects a graph state to the fields declared by a client selection schema.

**Throws**

A defect if LangGraph rejects an otherwise valid StateSchema construction.

**Example**

```ts
const projected = Effect.runSync(selectGraphStateEffect(state, z.object({ answer: z.string() })));
```

**Signature**

```ts
declare const selectGraphStateEffect: (
  state: AnyStateSchema,
  selection: StandardSchemaV1<unknown, unknown>,
) => Effect.Effect<StateSchema<Record<string, any>>, GraphStateSelectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-state-schema.ts#L28)

## `graph-subgraph-symbol.ts`

Marker for a graph embedded as a native node.

### RELKIT_SUBGRAPH

Hidden reference to the embedded graph descriptor.

**Signature**

```ts
declare const RELKIT_SUBGRAPH: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph-symbol.ts#L5)

### RELKIT_SUBGRAPH_NODE

Marker for a graph embedded as a native node.

**Signature**

```ts
declare const RELKIT_SUBGRAPH_NODE: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph-symbol.ts#L2)

## `graph-subgraph.ts`

Creates nested graph descriptors with their native execution metadata so parent compilation can retain subgraph state and interruption semantics.

### "./graph-subgraph.types.js" (namespace export)

Re-exports all named exports from the "./graph-subgraph.types.js" module.

**Signature**

```ts
export * from "./graph-subgraph.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L14)

### createSubgraphNode

Creates an embedded graph node for existing synchronous callers.

**Throws**

The original invalid options or destination error.

**Example**

```ts
const node = createSubgraphNode(graph, { id: "nested" });
```

**Signature**

```ts
declare const createSubgraphNode: <
  const Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
>(
  graph: GraphDescriptor<string, InputSchema, OutputSchema>,
  options?: GraphAsNodeOptions<Id>,
) => SubgraphNodeDescriptor<Id, InputSchema, OutputSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L62)

### createSubgraphNodeEffect

Creates a native node backed by another graph.

**Example**

```ts
Effect.runSync(createSubgraphNodeEffect(graph, { id: "nested" }));
```

**Signature**

```ts
declare const createSubgraphNodeEffect: <
  const Id extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
>(
  graph: GraphDescriptor<
    string,
    InputSchema,
    OutputSchema,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  options?: GraphAsNodeOptions<Id> | undefined,
) => Effect.Effect<
  SubgraphNodeDescriptor<Id, InputSchema, OutputSchema>,
  GraphNodeValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L22)

### isSubgraphNode

Checks embedded graph nodes for existing synchronous callers.

**Example**

```ts
if (isSubgraphNode(value)) subgraphForNode(value);
```

**Signature**

```ts
declare const isSubgraphNode: (value: unknown) => value is SubgraphNodeDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L102)

### isSubgraphNodeEffect

Checks whether a value is an embedded graph node.

**Example**

```ts
Effect.runSync(isSubgraphNodeEffect(value));
```

**Signature**

```ts
declare const isSubgraphNodeEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L82)

### subgraphForNode

Reads the source graph for existing synchronous callers.

**Example**

```ts
const nested = subgraphForNode(node);
```

**Signature**

```ts
declare const subgraphForNode: (value: SubgraphNodeDescriptor) => GraphDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L121)

### subgraphForNodeEffect

Reads the source graph from a subgraph node.

**Example**

```ts
Effect.runSync(subgraphForNodeEffect(node));
```

**Signature**

```ts
declare const subgraphForNodeEffect: (
  value: SubgraphNodeDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>
  >,
) => Effect.Effect<
  GraphDescriptor<
    string,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    AnyStateSchema,
    ReadonlyArray<GraphNodeLike>
  >,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.ts#L111)

## `graph-subgraph.types.ts`

Creates nested graph descriptors with their native execution metadata so parent compilation can retain subgraph state and interruption semantics. This companion preserves the native input and output types without starting runtime work.

### GraphAsNodeOptions (interface)

Authoring options for a graph embedded as a node.

**Signature**

```ts
export interface GraphAsNodeOptions<Id extends string = string> {
  readonly id?: Id;
  readonly ends?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.types.ts#L8)

### SubgraphNodeDescriptor (interface)

Native graph node whose action is another graph.

**Signature**

```ts
export interface SubgraphNodeDescriptor<
  Id extends string = string,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  OutputSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly [RELKIT_SUBGRAPH_NODE]: true;
  readonly kind: "subgraph-node";
  readonly id: Id;
  readonly input: InputSchema;
  readonly output: OutputSchema;
  readonly ends: readonly string[];
  readonly [RELKIT_SUBGRAPH]: GraphDescriptor;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-subgraph.types.ts#L14)

## `graph-workflow-error.ts`

Defines graph workflow failures at the RELKIT execution boundary, preserving graph identity and the native failure cause.

### GraphWorkflowFailure (class)

Tagged graph workflow projection failure.

**Signature**

```ts
declare class GraphWorkflowFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow-error.ts#L6)

### graphWorkflowFailure

Preserves a graph workflow projection error.

**Example**

```ts
graphWorkflowFailure(new TypeError("invalid node"));
```

**Signature**

```ts
declare const graphWorkflowFailure: (cause: unknown) => GraphWorkflowFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow-error.ts#L16)

## `graph-workflow.ts`

Adapts native graph execution to the RELKIT workflow contract, carrying invocation context and scoped persistence through completion.

### "./graph-workflow.types.js" (namespace export)

Re-exports all named exports from the "./graph-workflow.types.js" module.

**Signature**

```ts
export * from "./graph-workflow.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.ts#L19)

### graphWorkflow

Projects a workflow for existing synchronous graph callers.

**Throws**

The original node or schema projection error.

**Example**

```ts
graphWorkflow(nodes, edges);
```

**Signature**

```ts
declare const graphWorkflow: <Id extends string, State>(
  nodes: readonly (GraphNodeAny | FunctionGraphNodeDescriptor | SubgraphNodeDescriptor)[],
  edges: readonly GraphEdgeOperation<Id, State>[],
) => GraphWorkflow;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.ts#L53)

### graphWorkflowEffect

Projects a frozen serializable graph workflow from authoring nodes and edges.

**Example**

```ts
Effect.runSync(graphWorkflowEffect(nodes, edges));
```

**Signature**

```ts
declare const graphWorkflowEffect: <Id extends string, State>(
  nodes: ReadonlyArray<
    | GraphNodeAny
    | SubgraphNodeDescriptor<
        string,
        StandardSchemaV1<unknown, unknown>,
        StandardSchemaV1<unknown, unknown>
      >
    | FunctionGraphNodeDescriptor<
        string,
        string,
        unknown,
        unknown,
        ReadonlyArray<ErrorDescriptorAny>,
        StandardSchemaV1<unknown, unknown>,
        StandardSchemaV1<unknown, unknown>,
        FunctionDependencies
      >
  >,
  edges: ReadonlyArray<GraphEdgeOperation<Id, State>>,
) => Effect.Effect<GraphWorkflow, GraphWorkflowFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.ts#L27)

### graphWorkflowRequiresPersistence

Checks persistence needs for existing synchronous graph callers.

**Example**

```ts
graphWorkflowRequiresPersistence(workflow);
```

**Signature**

```ts
declare const graphWorkflowRequiresPersistence: (workflow: GraphWorkflow) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.ts#L79)

### graphWorkflowRequiresPersistenceEffect

Checks whether any graph node has a resumable continuation.

**Example**

```ts
Effect.runSync(graphWorkflowRequiresPersistenceEffect(workflow));
```

**Signature**

```ts
declare const graphWorkflowRequiresPersistenceEffect: (
  workflow: GraphWorkflow,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.ts#L69)

## `graph-workflow.types.ts`

Adapts native graph execution to the RELKIT workflow contract, carrying invocation context and scoped persistence through completion. This companion preserves the native input and output types without starting runtime work.

### GraphWorkflow (interface)

Immutable serializable graph topology for runtime and clients.

**Signature**

```ts
export interface GraphWorkflow {
  readonly version: 1;
  readonly start: typeof START;
  readonly end: typeof END;
  readonly nodes: readonly GraphWorkflowNode[];
  readonly edges: readonly GraphWorkflowEdge[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.types.ts#L30)

### GraphWorkflowEdge (type alias)

Serializable static, join, or conditional graph edge.

**Signature**

```ts
type GraphWorkflowEdge =
  | { readonly kind: "edge"; readonly from: string; readonly to: string }
  | { readonly kind: "join"; readonly from: readonly string[]; readonly to: string }
  | {
      readonly kind: "conditional";
      readonly from: string;
      readonly routes: readonly { readonly label: string; readonly to: string }[];
      readonly dynamic: boolean;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.types.ts#L19)

### GraphWorkflowNode (interface)

Serializable node entry in an agent graph workflow.

**Signature**

```ts
export interface GraphWorkflowNode {
  readonly id: string;
  readonly kind: "node" | "function" | "subgraph";
  readonly input: JsonValue;
  readonly output: JsonValue;
  readonly resume?: JsonValue;
  readonly ends: readonly string[];
  readonly targetFunctionId?: string;
  readonly workflow?: GraphWorkflow;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/graph-workflow.types.ts#L7)

## `index.ts`

Publishes the explicit LangChain integration authoring and execution surface; generic application imports remain owned by the SDK-free agents package.

### "./define-agent.js" (namespace export)

Re-exports all named exports from the "./define-agent.js" module.

**Signature**

```ts
export * from "./define-agent.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L3)

### "./define-graph-node.js" (namespace export)

Re-exports all named exports from the "./define-graph-node.js" module.

**Signature**

```ts
export * from "./define-graph-node.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L4)

### "./define-graph.js" (namespace export)

Re-exports all named exports from the "./define-graph.js" module.

**Signature**

```ts
export * from "./define-graph.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L5)

### "./define-persistence.js" (namespace export)

Re-exports all named exports from the "./define-persistence.js" module.

**Signature**

```ts
export * from "./define-persistence.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L6)

### "./graph-edges.js" (namespace export)

Re-exports all named exports from the "./graph-edges.js" module.

**Signature**

```ts
export * from "./graph-edges.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L7)

### "./graph-interruption.js" (namespace export)

Re-exports all named exports from the "./graph-interruption.js" module.

**Signature**

```ts
export * from "./graph-interruption.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L14)

### "./graph-persistence.js" (namespace export)

Re-exports all named exports from the "./graph-persistence.js" module.

**Signature**

```ts
export * from "./graph-persistence.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L12)

### "./graph-runtime.js" (namespace export)

Re-exports all named exports from the "./graph-runtime.js" module.

**Signature**

```ts
export * from "./graph-runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L9)

### "./graph-subgraph.js" (namespace export)

Re-exports all named exports from the "./graph-subgraph.js" module.

**Signature**

```ts
export * from "./graph-subgraph.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L13)

### "./graph-workflow.js" (namespace export)

Re-exports all named exports from the "./graph-workflow.js" module.

**Signature**

```ts
export * from "./graph-workflow.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L8)

### "./runtime-service.js" (namespace export)

Re-exports all named exports from the "./runtime-service.js" module.

**Signature**

```ts
export * from "./runtime-service.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L21)

### "./runtime.js" (namespace export)

Re-exports all named exports from the "./runtime.js" module.

**Signature**

```ts
export * from "./runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L20)

### "@relkit/agents/internal/agent-client" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/agent-client" module.

**Signature**

```ts
export * from "@relkit/agents/internal/agent-client";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L15)

### "@relkit/agents/internal/agent-telemetry" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/agent-telemetry" module.

**Signature**

```ts
export * from "@relkit/agents/internal/agent-telemetry";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L25)

### "@relkit/agents/internal/approval" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/approval" module.

**Signature**

```ts
export * from "@relkit/agents/internal/approval";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L17)

### "@relkit/agents/internal/client-events" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/client-events" module.

**Signature**

```ts
export * from "@relkit/agents/internal/client-events";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L16)

### "@relkit/agents/internal/generated-function" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/generated-function" module.

**Signature**

```ts
export * from "@relkit/agents/internal/generated-function";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L18)

### "@relkit/agents/internal/model-selection" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/model-selection" module.

**Signature**

```ts
export * from "@relkit/agents/internal/model-selection";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L26)

### "@relkit/agents/internal/observability" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/observability" module.

**Signature**

```ts
export * from "@relkit/agents/internal/observability";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L24)

### "@relkit/agents/internal/runtime-events" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/runtime-events" module.

**Signature**

```ts
export * from "@relkit/agents/internal/runtime-events";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L23)

### "@relkit/agents/internal/state-control-requests.types" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/state-control-requests.types" module.

**Signature**

```ts
export * from "@relkit/agents/internal/state-control-requests.types";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L27)

### "@relkit/agents/internal/state-provider.types" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/state-provider.types" module.

**Signature**

```ts
export * from "@relkit/agents/internal/state-provider.types";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L28)

### "@relkit/agents/internal/state-receipts.types" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/state-receipts.types" module.

**Signature**

```ts
export * from "@relkit/agents/internal/state-receipts.types";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L29)

### "@relkit/agents/internal/state-thread-requests.types" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/state-thread-requests.types" module.

**Signature**

```ts
export * from "@relkit/agents/internal/state-thread-requests.types";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L30)

### "@relkit/agents/internal/state.types" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/state.types" module.

**Signature**

```ts
export * from "@relkit/agents/internal/state.types";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L31)

### "@relkit/agents/internal/thread-transition" (namespace export)

Re-exports all named exports from the "@relkit/agents/internal/thread-transition" module.

**Signature**

```ts
export * from "@relkit/agents/internal/thread-transition";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L32)

### assertAgentRuntimeDependencies

**Signature**

```ts
declare const assertAgentRuntimeDependencies: (
  agents: readonly AgentDescriptor<string, unknown, unknown>[],
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L22)

### createGeneratedAgentFunction

**Signature**

```ts
declare const createGeneratedAgentFunction: (
  agentId: unknown,
  executor?: GeneratedAgentExecutor,
) => GeneratedAgentFunction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L19)

### validateGraphResumeInput

**Signature**

```ts
declare const validateGraphResumeInput: (
  descriptor: GraphDescriptor,
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L10)

### validateNativeAgentResumeInput

**Signature**

```ts
declare const validateNativeAgentResumeInput: (
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/index.ts#L11)

## `native-agent-interruption-error.ts`

Defines failures for native agent interrupt handling so malformed interruption data stays distinct from normal approval suspension.

### NativeAgentInterruptionFailure (class)

Tagged native agent continuation or state failure.

**Signature**

```ts
declare class NativeAgentInterruptionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-error.ts#L6)

### nativeAgentInterruptionFailure

Wraps a native continuation failure for Effect callers.

**Example**

```ts
nativeAgentInterruptionFailure(new TypeError("invalid reply"));
```

**Signature**

```ts
declare const nativeAgentInterruptionFailure: (cause: unknown) => NativeAgentInterruptionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-error.ts#L16)

## `native-agent-interruption-schema.ts`

Declares executable schemas for native interruption payloads before they cross the durable RELKIT continuation boundary.

### "./native-agent-interruption-schema.types.js" (namespace export)

Re-exports all named exports from the "./native-agent-interruption-schema.types.js" module.

**Signature**

```ts
export * from "./native-agent-interruption-schema.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L12)

### hitlResponseSchema

Constructs the response schema for existing synchronous callers.

**Example**

```ts
const schema = hitlResponseSchema(configs);
```

**Signature**

```ts
declare const hitlResponseSchema: (configs: readonly ReviewConfig[]) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L47)

### hitlResponseSchemaEffect

Constructs the exact response schema for pending reviews.

**Example**

```ts
Effect.runSync(hitlResponseSchemaEffect(configs));
```

**Signature**

```ts
declare const hitlResponseSchemaEffect: (
  configs: ReadonlyArray<ReviewConfig>,
) => Effect.Effect<JsonValue, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L19)

### isDecision

Checks a decision label for existing synchronous callers.

**Example**

```ts
if (isDecision(value)) useDecision(value);
```

**Signature**

```ts
declare const isDecision: (value: unknown) => value is DecisionType;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L132)

### isDecisionEffect

Checks one native human decision label.

**Example**

```ts
Effect.runSync(isDecisionEffect("approve"));
```

**Signature**

```ts
declare const isDecisionEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L122)

### isHitlRequest

Checks a native human review request for existing synchronous callers.

**Example**

```ts
if (isHitlRequest(value)) handle(value);
```

**Signature**

```ts
declare const isHitlRequest: (value: unknown) => value is HitlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L82)

### isHitlRequestEffect

Validates the native human review request shape.

**Example**

```ts
Effect.runSync(isHitlRequestEffect(value));
```

**Signature**

```ts
declare const isHitlRequestEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L56)

### isRecord

Checks a record for existing synchronous callers.

**Example**

```ts
if (isRecord(value)) read(value.name);
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L155)

### isRecordEffect

Checks a non-null, non-array record.

**Example**

```ts
Effect.runSync(isRecordEffect({ name: "tool" }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L145)

### publicHitlRequest

Projects a review request for existing synchronous callers.

**Example**

```ts
const request = publicHitlRequest(nativeRequest);
```

**Signature**

```ts
declare const publicHitlRequest: (value: HitlRequest) => HitlRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L113)

### publicHitlRequestEffect

Projects a review request to public action fields.

**Example**

```ts
Effect.runSync(publicHitlRequestEffect(request));
```

**Signature**

```ts
declare const publicHitlRequestEffect: (
  value: HitlRequest,
) => Effect.Effect<HitlRequest, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.ts#L91)

## `native-agent-interruption-schema.types.ts`

Declares executable schemas for native interruption payloads before they cross the durable RELKIT continuation boundary. This companion preserves the native input and output types without starting runtime work.

### DecisionType (type alias)

Human review decision accepted by a native agent.

**Signature**

```ts
type DecisionType = "approve" | "edit" | "reject";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.types.ts#L6)

### HitlRequest (interface)

Public set of actions awaiting human review.

**Signature**

```ts
export interface HitlRequest {
  readonly actionRequests: readonly Record<string, unknown>[];
  readonly reviewConfigs: readonly ReviewConfig[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.types.ts#L16)

### ReviewConfig (interface)

Review policy for one pending action.

**Signature**

```ts
export interface ReviewConfig {
  readonly actionName: string;
  readonly allowedDecisions: readonly DecisionType[];
  readonly argsSchema?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-schema.types.ts#L9)

## `native-agent-interruption-validation.ts`

Decodes native agent interruption data and rejects invalid continuation payloads before approval or resume processing.

### snapshotInterrupts

Extracts public native interruptions from nested graph state.

**Example**

```ts
const requests = snapshotInterrupts(snapshot, []);
```

**Signature**

```ts
declare const snapshotInterrupts: (
  snapshot: unknown,
  path: readonly string[],
) => GraphWaitingInterrupt[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-validation.ts#L21)

### validateNativeAgentResumeInputCore

Validates one or more replies against pending native reviews.

**Throws**

TypeError for absent, mismatched, or invalid replies.

**Example**

```ts
const replies = validateNativeAgentResumeInputCore(requests, input);
```

**Signature**

```ts
declare const validateNativeAgentResumeInputCore: (
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption-validation.ts#L55)

## `native-agent-interruption.ts`

Projects native agent interruption state into RELKIT approval and continuation records without losing native interrupt identity.

### nativeAgentResumeCommand

Builds a native resume command for existing Promise callers.

**Throws**

The original state or validation error.

**Example**

```ts
await nativeAgentResumeCommand(agent, config, reply);
```

**Signature**

```ts
declare const nativeAgentResumeCommand: (
  agent: NativeAgent,
  config: NativeAgentConfig,
  value: unknown,
) => Promise<Command>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L51)

### nativeAgentResumeCommandEffect

Reads native pending requests and constructs a resume command.

**Example**

```ts
await Effect.runPromise(nativeAgentResumeCommandEffect(agent, config, reply));
```

**Signature**

```ts
declare const nativeAgentResumeCommandEffect: (
  agent: NativeAgent,
  config: RunnableConfig<Record<string, any>>,
  value: unknown,
) => Effect.Effect<
  Command<{ [k: string]: unknown }, Record<string, unknown>, string>,
  NativeAgentInterruptionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L21)

### nativeAgentWaitingInterrupts

Reads waiting native interruptions for existing Promise callers.

**Throws**

The original native state provider error.

**Example**

```ts
await nativeAgentWaitingInterrupts(agent, config);
```

**Signature**

```ts
declare const nativeAgentWaitingInterrupts: (
  agent: NativeAgent,
  config: NativeAgentConfig,
) => Promise<readonly import("./graph-interruption.js").GraphWaitingInterrupt[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L98)

### nativeAgentWaitingInterruptsEffect

Reads and projects waiting native interruptions.

**Example**

```ts
await Effect.runPromise(nativeAgentWaitingInterruptsEffect(agent, config));
```

**Signature**

```ts
declare const nativeAgentWaitingInterruptsEffect: (
  agent: NativeAgent,
  config: RunnableConfig<Record<string, any>>,
) => Effect.Effect<Array<GraphWaitingInterrupt>, NativeAgentInterruptionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L69)

### validateNativeAgentResumeInput

Validates native continuation replies for existing synchronous callers.

**Throws**

The original invalid continuation error.

**Example**

```ts
const reply = validateNativeAgentResumeInput(requests, value);
```

**Signature**

```ts
declare const validateNativeAgentResumeInput: (
  requests: readonly AgentWaitingRequest[],
  value: unknown,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L131)

### validateNativeAgentResumeInputEffect

Validates native continuation replies against pending requests.

**Example**

```ts
Effect.runSync(validateNativeAgentResumeInputEffect(requests, reply));
```

**Signature**

```ts
declare const validateNativeAgentResumeInputEffect: (
  requests: ReadonlyArray<AgentWaitingRequest>,
  value: unknown,
) => Effect.Effect<unknown, NativeAgentInterruptionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.ts#L115)

## `native-agent-interruption.types.ts`

Native LangGraph agent state access used by continuation operations.

### NativeAgent (type alias)

Native LangGraph agent state access used by continuation operations.

**Signature**

```ts
type NativeAgent = Pick<ReturnType<typeof import("langchain").createAgent>, "getState">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.types.ts#L2)

### NativeAgentConfig (type alias)

State lookup configuration accepted by a native agent.

**Signature**

```ts
type NativeAgentConfig = Parameters<NativeAgent["getState"]>[0];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/native-agent-interruption.types.ts#L5)

## `persistence-error.ts`

Defines typed failures for native persistence acquisition and release, retaining the selected resource and underlying cause.

### AgentPersistenceFailure (class)

A typed persistence acquire, validation, or release failure.

**Signature**

```ts
declare class AgentPersistenceFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/persistence-error.ts#L6)

### agentPersistenceFailure

Retains the original failure for compatibility callers.

**Example**

```ts
agentPersistenceFailure(new Error("store unavailable"));
```

**Signature**

```ts
declare const agentPersistenceFailure: (cause: unknown) => AgentPersistenceFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/persistence-error.ts#L16)

## `persistence-symbol.ts`

Shared marker used to recognize RELKIT persistence descriptors.

### RELKIT_PERSISTENCE

Shared marker used to recognize RELKIT persistence descriptors.

**Signature**

```ts
declare const RELKIT_PERSISTENCE: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/persistence-symbol.ts#L2)

## `runtime-approval-decision.ts`

Converts supported approval reply forms to the canonical record while keeping
approval policy, tracing and tool lifecycle in their existing owners.

### resolveApprovalDecisionEffect

Normalizes the supported reply forms without changing approval semantics.

**Signature**

```ts
declare const resolveApprovalDecisionEffect: (
  approval: PendingApproval,
  response: ApprovalDecision,
) => Effect.Effect<ApprovalRecord, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-approval-decision.ts#L19)

## `runtime-dependencies.ts`

Exposes dependency preflight without making optional DeepAgents declarations part of ordinary native authoring.

### assertAgentRuntimeDependencies

Checks selected native capabilities and preserves the original loader failure and lifecycle.

**Signature**

```ts
declare const assertAgentRuntimeDependencies: (
  agents: readonly AgentDescriptor<string, unknown, unknown>[],
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-dependencies.ts#L9)

## `runtime-effect-error.ts`

Normalizes Effect failures from native invocation adapters while retaining the original failure cause at the public runtime boundary.

### AgentInvocationFailure (class)

A typed Effect failure that retains the public invocation error as its cause.

**Signature**

```ts
declare class AgentInvocationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-effect-error.ts#L7)

### agentInvocationFailure

Captures an invocation failure without losing compatibility error details.

**Example**

```ts
agentInvocationFailure(new Error("model unavailable"));
```

**Signature**

```ts
declare const agentInvocationFailure: (cause: unknown) => AgentInvocationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-effect-error.ts#L17)

## `runtime-errors.ts`

Constructs invocation failures with agent identity and native causes, including selected dependency failures and execution errors.

### AgentRuntimeError (class)

Safe public failure fields; a non-enumerable native cause is private diagnostic data.

**Signature**

```ts
declare class AgentRuntimeError { constructor(
    readonly code: string,
    message: string,
    readonly issues?: readonly StandardIssue[],
    options?: ErrorOptions,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-errors.ts#L6)

## `runtime-failure-diagnostics.ts`

Records bounded failure categories at the invocation boundary; native causes remain private and are never logged raw.

### logAgentFailure

Logs one safe diagnostic before public failure mapping, without retrying execution.

**Signature**

```ts
declare const logAgentFailure: (
  failure: AgentInvocationFailure,
  options: AgentRuntimeOptions & AgentInvocationOptions,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-failure-diagnostics.ts#L45)

## `runtime-integration.ts`

Advertises native execution registrations to the existing verified integration
plan. Provider acquisition skips these execution-only capabilities.

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "langchain";
  registrations: ReadonlyArray<{ capability: string; adapterId: string; protocolVersion: number }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-integration.ts#L7)

## `runtime-invoke.ts`

Resolves model and invocation identities before acquiring the scoped native
signal; stream work inherits the same tracing and cancellation context.

### invokeNativeWithContextEffect

Runs native work inside the original scoped signal and trace boundary.

**Signature**

```ts
declare const invokeNativeWithContextEffect: (
  options: NativeAgentRuntimeOptions,
  service: AgentExecutionService,
  invocation: {
    capture: AgentCapturePolicy;
    invocationId: StableId;
    traceId: StableId;
    runtimeModel: ResolvedRuntimeModel;
  },
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-invoke.ts#L58)

### resolveNativeInvocationEffect

Resolves validated invocation identity, capture policy and native model.

**Signature**

```ts
declare const resolveNativeInvocationEffect: (
  options: NativeAgentRuntimeOptions,
  service: AgentExecutionService,
) => Effect.Effect<
  {
    capture: AgentCapturePolicy;
    invocationId: StableId;
    traceId: StableId;
    runtimeModel: ResolvedRuntimeModel;
  },
  AgentInvocationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-invoke.ts#L21)

## `runtime-loop-context.types.ts`

Carries one native loop's already acquired runnable, identity, state selection
and signal to stream/settlement helpers without allocating another lifetime.

### NativeAgentLoopContext (interface)

**Signature**

```ts
export interface NativeAgentLoopContext {
  readonly options: AgentLoopOptions;
  readonly native: Awaited<ReturnType<typeof createNativeAgent>>;
  readonly config: { readonly configurable?: { readonly thread_id: string } };
  readonly input: unknown;
  readonly signal: AbortSignal;
  readonly maxInputBytes: number;
  readonly maxOutputBytes: number;
  readonly observe: ReturnType<typeof createLoopTelemetry>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-context.types.ts#L9)

## `runtime-loop-execution.ts`

Executes one native agent stream while retaining model failure precedence.
Public wrappers own Effect interruption; state helpers use the same signal.

### runAgentLoopCore

**Signature**

```ts
declare const runAgentLoopCore: (
  options: AgentLoopOptions,
  model: NativeModel,
  modelId: string,
  signal: AbortSignal,
  input: unknown,
  maxInputBytes: number,
  maxOutputBytes: number,
  invocationId: string,
  traceId: string,
  capture: AgentCapturePolicy,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-execution.ts#L17)

## `runtime-loop-state.ts`

Streams one already acquired native runnable and settles its public output or
interruption using the same checkpoint identity, byte limits and content sink.

### settleNativeAgentLoop

Publishes waiting state or validated output without changing persistence identity.

**Signature**

```ts
declare const settleNativeAgentLoop: (
  context: NativeAgentLoopContext,
  state: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-state.ts#L65)

### streamNativeAgentLoop

Collects the native stream under its caller's existing trace and signal.

**Signature**

```ts
declare const streamNativeAgentLoop: (context: NativeAgentLoopContext) => Promise<any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-state.ts#L25)

## `runtime-loop-telemetry.ts`

Publishes native invocation loop observations to RELKIT telemetry using the current execution context and stable agent identifiers.

### createLoopTelemetry

**Signature**

```ts
declare const createLoopTelemetry: (
  runtime: AgentRuntimeOptions,
  modelId: string,
) => (event: ProtocolEvent) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-telemetry.ts#L10)

## `runtime-loop-values.ts`

Extracts validated loop input and output values for native execution, keeping schema failure handling at the invocation boundary.

### nativeMessages

Builds native messages for existing synchronous callers.

**Throws**

The original input JSON or byte limit error.

**Example**

```ts
nativeMessages(options, input, 1024);
```

**Signature**

```ts
declare const nativeMessages: (
  options: AgentLoopOptions,
  input: unknown,
  maxInputBytes: number,
) => Array<{ role: "user" | "assistant"; content: string }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L39)

### nativeMessagesEffect

Builds the native message list from prior turns and validated input.

**Example**

```ts
Effect.runSync(nativeMessagesEffect(options, input, 1024));
```

**Signature**

```ts
declare const nativeMessagesEffect: (
  options: AgentLoopOptions,
  input: unknown,
  maxInputBytes: number,
) => Effect.Effect<
  Array<{ role: "user" | "assistant"; content: string }>,
  AgentInvocationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L17)

### responseValue

Extracts structured output for existing synchronous callers.

**Throws**

AgentRuntimeError when structured output is absent.

**Example**

```ts
responseValue(state);
```

**Signature**

```ts
declare const responseValue: (state: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L79)

### responseValueEffect

Extracts the structured model output value.

**Example**

```ts
Effect.runSync(responseValueEffect(state));
```

**Signature**

```ts
declare const responseValueEffect: (
  state: unknown,
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L52)

### unwrapNativeCause

Unwraps native causes for existing synchronous callers.

**Example**

```ts
unwrapNativeCause(error);
```

**Signature**

```ts
declare const unwrapNativeCause: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L111)

### unwrapNativeCauseEffect

Unwraps nested native provider causes without looping on cyclic causes.

**Example**

```ts
Effect.runSync(unwrapNativeCauseEffect(error));
```

**Signature**

```ts
declare const unwrapNativeCauseEffect: (value: unknown) => Effect.Effect<unknown, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop-values.ts#L92)

## `runtime-loop.ts`

Exposes native loop execution as an observed Effect and Promise facade.
Cancellation remains linked to the caller and the native stream owner.

### AgentLoopOptions

**Signature**

```ts
declare const AgentLoopOptions: AgentLoopOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.ts#L12)

### NativeModel

**Signature**

```ts
declare const NativeModel: NativeModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.ts#L12)

### runAgentLoop

Runs the native model loop for existing Promise callers.

**Throws**

The original model, tool, validation, or cancellation error.

**Example**

```ts
await runAgentLoop(options, model, id, signal, input, 1024, 1024, invocation, trace, capture);
```

**Signature**

```ts
declare const runAgentLoop: (
  options: AgentLoopOptions,
  model: NativeModel,
  modelId: string,
  signal: AbortSignal,
  input: unknown,
  maxInputBytes: number,
  maxOutputBytes: number,
  invocationId: string,
  traceId: string,
  capture: AgentCapturePolicy,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.ts#L75)

### runAgentLoopEffect

Runs one native model loop with linked Effect cancellation.

**Example**

```ts
await Effect.runPromise(
  runAgentLoopEffect(options, model, id, signal, input, 1024, 1024, invocation, trace, capture),
);
```

**Signature**

```ts
declare const runAgentLoopEffect: (
  options: AgentLoopOptions,
  model: NativeModel,
  modelId: string,
  signal: AbortSignal,
  input: unknown,
  maxInputBytes: number,
  maxOutputBytes: number,
  invocationId: string,
  traceId: string,
  capture: AgentCapturePolicy,
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.ts#L28)

## `runtime-loop.types.ts`

Coordinates native invocation steps, output validation and settlement while retaining tool, interruption and stream finalization order. This companion preserves the native input and output types without starting runtime work.

### AgentLoopOptions (type alias)

Runtime and invocation options consumed by the native model loop.

**Signature**

```ts
type AgentLoopOptions = AgentRuntimeOptions & AgentInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.types.ts#L7)

### NativeModel (type alias)

Resolved native model or provider selector.

**Signature**

```ts
type NativeModel = string | LanguageModelLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-loop.types.ts#L10)

## `runtime-model-error.ts`

Defines model selection and initialization failures with the selected model identifier and underlying SDK cause.

### AgentModelResolutionFailure (class)

Tagged model resolution or content limit failure.

**Signature**

```ts
declare class AgentModelResolutionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model-error.ts#L6)

### agentModelResolutionFailure

Preserves a model provider or limit error for Effect callers.

**Example**

```ts
agentModelResolutionFailure(new Error("unavailable"));
```

**Signature**

```ts
declare const agentModelResolutionFailure: (cause: unknown) => AgentModelResolutionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model-error.ts#L16)

## `runtime-model.ts`

Resolves authored model selectors or native model instances for an invocation without replacing the caller's model resource identity.

### AgentContentLimits

**Signature**

```ts
declare const AgentContentLimits: AgentContentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L16)

### ResolvedRuntimeModel

**Signature**

```ts
declare const ResolvedRuntimeModel: ResolvedRuntimeModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L17)

### RuntimeModelOptions

**Signature**

```ts
declare const RuntimeModelOptions: RuntimeModelOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L18)

### resolveAgentContentLimits

Validates content byte limits for existing synchronous runtime callers.

**Throws**

The original AgentRuntimeError for invalid limits.

**Example**

```ts
resolveAgentContentLimits({ maxInputBytes: 1024 });
```

**Signature**

```ts
declare const resolveAgentContentLimits: (
  options: Pick<RuntimeModelOptions, "maxInputBytes" | "maxOutputBytes">,
) => AgentContentLimits;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L112)

### resolveAgentContentLimitsEffect

Validates content byte limits against fixed package maximums.

**Example**

```ts
Effect.runSync(resolveAgentContentLimitsEffect({ maxInputBytes: 1024 }));
```

**Signature**

```ts
declare const resolveAgentContentLimitsEffect: (
  options: Pick<RuntimeModelOptions, "maxOutputBytes" | "maxInputBytes">,
) => Effect.Effect<AgentContentLimits, AgentModelResolutionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L94)

### resolveRuntimeModel

Resolves a model for existing Promise runtime callers.

**Throws**

The original provider or AgentRuntimeError cause.

**Example**

```ts
await resolveRuntimeModel({ model: "test", registry: null, environment: {} });
```

**Signature**

```ts
declare const resolveRuntimeModel: (options: RuntimeModelOptions) => Promise<ResolvedRuntimeModel>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L81)

### resolveRuntimeModelEffect

Resolves a model factory, native model, registry selection, or string selector.

**Example**

```ts
Effect.runPromise(resolveRuntimeModelEffect({ model: "test", registry: null, environment: {} }));
```

**Signature**

```ts
declare const resolveRuntimeModelEffect: (
  options: RuntimeModelOptions,
) => Effect.Effect<ResolvedRuntimeModel, AgentModelResolutionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.ts#L29)

## `runtime-model.types.ts`

Resolves authored model selectors or native model instances for an invocation without replacing the caller's model resource identity. This companion preserves the native input and output types without starting runtime work.

### AgentContentLimits (interface)

Validated maximum byte counts for agent input and output.

**Signature**

```ts
export interface AgentContentLimits {
  readonly maxInputBytes: number;
  readonly maxOutputBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.types.ts#L16)

### ResolvedRuntimeModel (interface)

Selected native model and validated content limits.

**Signature**

```ts
export interface ResolvedRuntimeModel extends AgentContentLimits {
  readonly id: string;
  readonly model: string | LanguageModelLike;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.types.ts#L22)

### RuntimeModelOptions (interface)

Inputs used to select a native model and content limits.

**Signature**

```ts
export interface RuntimeModelOptions {
  readonly model?: AgentModel;
  readonly registry: unknown;
  readonly environment: Readonly<Record<string, unknown>>;
  readonly maxInputBytes?: number;
  readonly maxOutputBytes?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-model.types.ts#L7)

## `runtime-native-agent-build.ts`

Constructs the native agent from resolved model, tools, middleware and optional DeepAgents configuration immediately before invocation.

### childModelEffect

Resolves a child model or inherits its parent model.

**Example**

```ts
await Effect.runPromise(childModelEffect(child, model, runtime));
```

**Signature**

```ts
declare const childModelEffect: (
  child: AgentDescriptor<
    string,
    unknown,
    unknown,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    ReadonlyArray<AgentMiddleware>,
    ReadonlyArray<AgentTool>
  >,
  inherited: string | LanguageModelLike,
  runtime: NativeAgentRuntimeOptions,
) => Effect.Effect<string | LanguageModelLike, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent-build.ts#L52)

### createSubagentsEffect

Builds child and nested DeepAgents declarations in authored order.

**Example**

```ts
await Effect.runPromise(
  createSubagentsEffect(children, model, backend, runtime, options, groups, deepagents, limits),
);
```

**Signature**

```ts
declare const createSubagentsEffect: (
  children: ReadonlyArray<
    AgentDescriptor<
      string,
      unknown,
      unknown,
      StandardSchemaV1<unknown, unknown>,
      StandardSchemaV1<unknown, unknown>,
      ReadonlyArray<AgentMiddleware>,
      ReadonlyArray<AgentTool>
    >
  >,
  inheritedModel: string | LanguageModelLike,
  inheritedBackend: unknown,
  runtime: NativeAgentRuntimeOptions,
  options: CreateNativeAgentOptions,
  groups: Array<NativeTools>,
  deepagents: typeof import("deepagents"),
  limitMiddleware: AnyAgentMiddleware,
) => Effect.Effect<Array<unknown>, AgentInvocationFailure, NativeToolIdentity>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent-build.ts#L81)

### createToolsForAgentEffect

Materializes tools for a root or child agent.

**Example**

```ts
Effect.runSync(createToolsForAgentEffect(runtime, options, child));
```

**Signature**

```ts
declare const createToolsForAgentEffect: (
  runtime: NativeAgentRuntimeOptions,
  options: CreateNativeAgentOptions,
  agent: AgentDescriptor<
    string,
    unknown,
    unknown,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    ReadonlyArray<AgentMiddleware>,
    ReadonlyArray<AgentTool>
  >,
) => Effect.Effect<NativeTools, AgentInvocationFailure, NativeToolIdentity>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent-build.ts#L29)

### responseFormatEffect

**Signature**

```ts
declare const responseFormatEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  model?: NativeModel | undefined,
) => Effect.Effect<
  ProviderStrategy<Record<string, unknown>> | TypedToolStrategy<Record<string, unknown>>,
  AgentInvocationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent-build.ts#L161)

## `runtime-native-agent.ts`

Owns native agent construction and invocation adaptation, retaining the authored SDK configuration and selected persistence context.

### CreateNativeAgentOptions

**Signature**

```ts
declare const CreateNativeAgentOptions: CreateNativeAgentOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.ts#L27)

### NativeAgent

**Signature**

```ts
declare const NativeAgent: ReactAgent<
  AgentTypeConfig<
    Record<string, any>,
    StateDefinitionInit | undefined,
    InteropZodObject | AnyAnnotationRoot,
    ReadonlyArray<AnyAgentMiddleware>,
    ReadonlyArray<ClientTool | ServerTool>,
    ReadonlyArray<() => StreamTransformer<any>>
  >
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.ts#L27)

### StructuredOutputParsingError

**Signature**

```ts
declare const StructuredOutputParsingError: typeof StructuredOutputParsingError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.ts#L26)

### createNativeAgent

Builds a native agent for existing Promise callers.

**Throws**

The original model, schema, persistence, or dependency error.

**Example**

```ts
await createNativeAgent(options);
```

**Signature**

```ts
declare const createNativeAgent: (
  options: CreateNativeAgentOptions,
) => Promise<{ readonly agent: NativeAgent; readonly tools: NativeTools }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.ts#L90)

### createNativeAgentEffect

Builds a native LangChain or DeepAgents runnable for one invocation.

**Example**

```ts
await Effect.runPromise(
  Effect.provide(
    createNativeAgentEffect(options),
    Layer.merge(DeepAgentsLoaderLive, NativeToolIdentityLive),
  ),
);
```

**Signature**

```ts
declare const createNativeAgentEffect: (options: CreateNativeAgentOptions) => Effect.Effect<
  | {
      agent: ReactAgent<
        AgentTypeConfig<
          ResponseFormatUndefined,
          undefined,
          AnyAnnotationRoot,
          Array<AnyAgentMiddleware>,
          ReadonlyArray<
            | ClientTool
            | ServerTool
            | DynamicStructuredTool<
                InteropZodObject | JsonSchema7Type | InteropZodType<string>,
                unknown,
                unknown,
                unknown,
                unknown,
                string
              >
            | DynamicTool<unknown, unknown>
          >,
          readonly []
        >
      >;
      tools: NativeTools;
    }
  | {
      agent: ReactAgent<
        AgentTypeConfig<
          Record<string, any>,
          StateDefinitionInit | undefined,
          InteropZodObject | AnyAnnotationRoot,
          ReadonlyArray<AnyAgentMiddleware>,
          ReadonlyArray<ClientTool | ServerTool>,
          ReadonlyArray<() => StreamTransformer<any>>
        >
      >;
      tools: NativeTools;
    },
  AgentInvocationFailure,
  NativeToolIdentity | DeepAgentsLoader
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.ts#L34)

## `runtime-native-agent.types.ts`

Owns native agent construction and invocation adaptation, retaining the authored SDK configuration and selected persistence context. This companion preserves the native input and output types without starting runtime work.

### CreateNativeAgentOptions (interface)

Inputs required to build one native agent invocation.

**Signature**

```ts
export interface CreateNativeAgentOptions {
  readonly runtime: NativeAgentRuntimeOptions;
  readonly model: string | LanguageModelLike;
  readonly signal: AbortSignal;
  readonly maxOutputBytes: number;
  readonly invocationId: string;
  readonly traceId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.types.ts#L18)

### NativeAgent (type alias)

Native LangChain agent runnable.

**Signature**

```ts
type NativeAgent = ReturnType<typeof createAgent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.types.ts#L15)

### NativeAgentRuntimeOptions (type alias)

Runtime options narrowed to a native agent descriptor.

**Signature**

```ts
type NativeAgentRuntimeOptions = Omit<AgentRuntimeOptions, "agent"> &
  AgentInvocationOptions & {
    readonly agent: AgentDescriptor<string, unknown, unknown>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-agent.types.ts#L9)

## `runtime-native-event-tools.ts`

Projects native tool events into RELKIT tool lifecycle observations while preserving tool call identifiers and status order.

### emitToolEvent

Emits a native tool event for existing Promise callers.

**Throws**

The original sink or cancellation error.

**Example**

```ts
await emitToolEvent(event, sink, ids, names, calls, signal);
```

**Signature**

```ts
declare const emitToolEvent: (
  event: ProtocolEvent,
  sink: AgentContentSink | undefined,
  toolIds: ReadonlyMap<string, string>,
  relkitNames: ReadonlySet<string>,
  toolNames: Map<string, string>,
  signal: AbortSignal,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-event-tools.ts#L86)

### emitToolEventEffect

Emits public lifecycle updates for a native tool event.

**Example**

```ts
await Effect.runPromise(emitToolEventEffect(event, sink, ids, names, calls, signal));
```

**Signature**

```ts
declare const emitToolEventEffect: (
  event: ProtocolEvent,
  sink: AgentContentSink | undefined,
  toolIds: ReadonlyMap<string, string>,
  relkitNames: ReadonlySet<string>,
  toolNames: Map<string, string>,
  signal: AbortSignal,
) => Effect.Effect<void, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-event-tools.ts#L22)

## `runtime-native-events-helpers.ts`

Extracts native event identifiers and payload fragments shared by stream adapters, retaining the SDK's event identity conventions.

### executionContext

Resolves the nearest execution context for a nested event.

**Example**

```ts
executionContext(event, contexts);
```

**Signature**

```ts
declare const executionContext: (
  event: ProtocolEvent,
  contexts: ReadonlyMap<string, NativeExecutionContext>,
) => NativeExecutionContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events-helpers.ts#L46)

### isModelStart

Checks whether an event starts a model call.

**Example**

```ts
isModelStart(event);
```

**Signature**

```ts
declare const isModelStart: (event: ProtocolEvent) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events-helpers.ts#L66)

### isToolStart

Checks whether an event starts a tool call.

**Example**

```ts
isToolStart(event);
```

**Signature**

```ts
declare const isToolStart: (event: ProtocolEvent) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events-helpers.ts#L80)

### trackExecutionContext

Tracks agent and subagent identity from native protocol events.

**Example**

```ts
trackExecutionContext(event, contexts);
```

**Signature**

```ts
declare const trackExecutionContext: (
  event: ProtocolEvent,
  contexts: Map<string, NativeExecutionContext>,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events-helpers.ts#L12)

## `runtime-native-events.ts`

Maps the native event stream into RELKIT execution events and public observations in the order delivered by the native iterator.

### collectNativeEvents

Collects native events for existing Promise runtime callers.

**Throws**

The original stream, sink, validation, or cancellation error.

**Example**

```ts
await collectNativeEvents(
  events,
  sink,
  ids,
  names,
  signal,
  limits,
  schemas,
  failure,
  observe,
  abort,
);
```

**Signature**

```ts
declare const collectNativeEvents: (
  events: AsyncIterable<ProtocolEvent>,
  sink: AgentContentSink | undefined,
  toolIds: ReadonlyMap<string, string>,
  relkitNames: ReadonlySet<string>,
  signal: AbortSignal,
  limits: { readonly maxSteps: number; readonly maxToolCalls: number },
  stateSchemas: ReadonlyMap<string, StandardSchemaV1>,
  failure: () => unknown,
  observe: ((event: ProtocolEvent) => void) | undefined,
  abort: (reason: unknown) => void,
  eventSchemas?: Readonly<Record<string, StandardSchemaV1>>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events.ts#L95)

### collectNativeEventsEffect

Collects native events with linked Effect interruption.

**Example**

```ts
await Effect.runPromise(
  collectNativeEventsEffect(
    events,
    sink,
    ids,
    names,
    signal,
    limits,
    schemas,
    failure,
    observe,
    abort,
  ),
);
```

**Signature**

```ts
declare const collectNativeEventsEffect: (
  events: AsyncIterable<ProtocolEvent>,
  sink: AgentContentSink | undefined,
  toolIds: ReadonlyMap<string, string>,
  relkitNames: ReadonlySet<string>,
  signal: AbortSignal,
  limits: { readonly maxSteps: number; readonly maxToolCalls: number },
  stateSchemas: ReadonlyMap<string, StandardSchemaV1<unknown, unknown>>,
  failure: () => unknown,
  observe: ((event: ProtocolEvent) => void) | undefined,
  abort: (reason: unknown) => void,
  eventSchemas?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>> | undefined,
) => Effect.Effect<undefined, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-events.ts#L36)

## `runtime-native-limits.ts`

Applies authored step, tool-call and timeout limits at native invocation boundaries and reports the existing limit failures.

### createNativeLimitMiddleware

Creates native invocation guards for existing synchronous callers.

**Throws**

The original middleware creation error.

**Example**

```ts
createNativeLimitMiddleware(limits);
```

**Signature**

```ts
declare const createNativeLimitMiddleware: (limits: AgentLimits) => AnyAgentMiddleware;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-limits.ts#L62)

### createNativeLimitMiddlewareEffect

Creates per-invocation model and tool call guards.

**Example**

```ts
Effect.runSync(createNativeLimitMiddlewareEffect(limits));
```

**Signature**

```ts
declare const createNativeLimitMiddlewareEffect: (
  limits: AgentLimits,
) => Effect.Effect<AnyAgentMiddleware, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-limits.ts#L15)

## `runtime-native-messages.ts`

Converts invocation messages into native LangChain message shapes while preserving content, tool calls and reply correlation.

### NativeMessageAccumulator (class)

Per-invocation accumulator of streamed native assistant message parts.

**Example**

```ts
const messages = new NativeMessageAccumulator();
```

**Signature**

```ts
declare class NativeMessageAccumulator
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-messages.ts#L12)

### update (method)

Applies one event for existing synchronous callers.

**Example**

```ts
messages.update(event);
```

**Signature**

```ts
declare const update: (event: AgentExecutionEvent) => BrowserMessage | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-messages.ts#L30)

### updateCore (method)

**Signature**

```ts
declare const updateCore: (event: AgentExecutionEvent) => BrowserMessage | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-messages.ts#L34)

### updateEffect (property)

Applies one public event to the message accumulator.

**Example**

```ts
Effect.runSync(messages.updateEffect(event));
```

**Signature**

```ts
readonly updateEffect: (event: AgentExecutionEvent) => Effect.Effect<BrowserMessage | undefined, never, never>
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-messages.ts#L20)

## `runtime-native-messages.types.ts`

Mutable text parts for one native assistant message.

### MessageState (interface)

Mutable text parts for one native assistant message.

**Signature**

```ts
export interface MessageState {
  readonly messageId: string;
  readonly createdAt: string;
  readonly parts: Map<number, string>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-messages.types.ts#L2)

## `runtime-native-public-state.ts`

Projects permitted native state values for public client events using the agent's declared visibility policy.

### selectEffect

Validates selected fields from one state object with bounded concurrency.

**Example**

```ts
await Effect.runPromise(selectEffect(state, schemas));
```

**Signature**

```ts
declare const selectEffect: (
  value: Record<string, unknown>,
  schemas: ReadonlyMap<string, StandardSchemaV1<unknown, unknown>>,
) => Effect.Effect<{ [k: string]: unknown }, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public-state.ts#L49)

### selectedStateEffect

Projects selected state keys from direct or nested native updates.

**Example**

```ts
await Effect.runPromise(selectedStateEffect(update, schemas));
```

**Signature**

```ts
declare const selectedStateEffect: (
  value: unknown,
  schemas: ReadonlyMap<string, StandardSchemaV1<unknown, unknown>>,
) => Effect.Effect<{ [k: string]: unknown } | undefined, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public-state.ts#L14)

## `runtime-native-public-tools.ts`

Projects native tool activity into client-visible tool events after applying the declared public visibility contract.

### publicToolValue

Projects a native tool result for existing synchronous callers.

**Example**

```ts
publicToolValue(result);
```

**Signature**

```ts
declare const publicToolValue: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public-tools.ts#L21)

### publicToolValueEffect

Projects a native tool result to its public value.

**Example**

```ts
Effect.runSync(publicToolValueEffect(result));
```

**Signature**

```ts
declare const publicToolValueEffect: (value: unknown) => Effect.Effect<unknown, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public-tools.ts#L11)

## `runtime-native-public.ts`

Coordinates native state and tool projection for public execution sinks without exposing undeclared private state.

### NativeExecutionContext

**Signature**

```ts
declare const NativeExecutionContext: NativeExecutionContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.ts#L14)

### nativePublicEvent

Projects a native event for existing Promise callers.

**Throws**

The original schema or timestamp error.

**Example**

```ts
await nativePublicEvent(event, schemas);
```

**Signature**

```ts
declare const nativePublicEvent: (
  event: ProtocolEvent,
  stateSchemas: ReadonlyMap<string, StandardSchemaV1>,
  context?: NativeExecutionContext,
  eventSchemas?: Readonly<Record<string, StandardSchemaV1>>,
) => Promise<AgentExecutionEvent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.ts#L63)

### nativePublicEventEffect

Projects a native protocol event to its public, validated form.

**Example**

```ts
await Effect.runPromise(nativePublicEventEffect(event, schemas));
```

**Signature**

```ts
declare const nativePublicEventEffect: (
  event: ProtocolEvent,
  stateSchemas: ReadonlyMap<string, StandardSchemaV1<unknown, unknown>>,
  context?: NativeExecutionContext | undefined,
  eventSchemas?: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>> | undefined,
) => Effect.Effect<AgentExecutionEvent, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.ts#L25)

### publicToolValue

**Signature**

```ts
declare const publicToolValue: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.ts#L15)

### publicToolValueEffect

**Signature**

```ts
declare const publicToolValueEffect: (value: unknown) => Effect.Effect<unknown, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.ts#L15)

## `runtime-native-public.types.ts`

Coordinates native state and tool projection for public execution sinks without exposing undeclared private state. This companion preserves the native input and output types without starting runtime work.

### NativeExecutionContext (type alias)

Agent and parent context attached to a public native event.

**Signature**

```ts
type NativeExecutionContext = Pick<AgentExecutionEvent, "agent" | "parent">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-public.types.ts#L6)

## `runtime-native-response-format.ts`

Converts a validated RELKIT output schema to the native structured response
strategy, preserving schema failures and disabling native silent recovery.

### responseFormatEffect

Creates the native structured output strategy.

**Example**

```ts
Effect.runSync(responseFormatEffect(output));
```

**Signature**

```ts
declare const responseFormatEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  model?: NativeModel | undefined,
) => Effect.Effect<
  ProviderStrategy<Record<string, unknown>> | TypedToolStrategy<Record<string, unknown>>,
  AgentInvocationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-response-format.ts#L20)

## `runtime-native-subagents.ts`

Builds native child configurations and nested runnables after model, tools and
persistence have been resolved by the existing ordered subagent traversal.

### childAgentCommon

Projects an already resolved child's native runnable configuration.

**Signature**

```ts
declare const childAgentCommon: (
  child: AgentDescriptor<string, unknown, unknown>,
  model: string | LanguageModelLike,
  instructions: string,
  format: Effect.Success<ReturnType<typeof responseFormatEffect>>,
  childTools: NativeTools,
  limitMiddleware: AnyAgentMiddleware,
) => {
  name: string;
  model: string | LanguageModelLike;
  systemPrompt: string;
  tools: Array<
    | ClientTool
    | ServerTool
    | DynamicStructuredTool<
        InteropZodObject | JsonSchema7Type | InteropZodType<string>,
        unknown,
        unknown,
        unknown,
        unknown,
        string
      >
    | DynamicTool<unknown, unknown>
  >;
  middleware: Array<AnyAgentMiddleware>;
  responseFormat:
    ProviderStrategy<Record<string, unknown>> | TypedToolStrategy<Record<string, unknown>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-subagents.ts#L25)

### nestedChildAgentEffect

Constructs one nested runnable with the existing native exception boundary.

**Signature**

```ts
declare const nestedChildAgentEffect: (
  child: AgentDescriptor<
    string,
    unknown,
    unknown,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    ReadonlyArray<AgentMiddleware>,
    ReadonlyArray<AgentTool>
  >,
  common: {
    name: string;
    model: string | LanguageModelLike;
    systemPrompt: string;
    tools: Array<
      | ClientTool
      | ServerTool
      | DynamicStructuredTool<
          InteropZodObject | JsonSchema7Type | InteropZodType<string>,
          unknown,
          unknown,
          unknown,
          unknown,
          string
        >
      | DynamicTool<unknown, unknown>
    >;
    middleware: Array<AnyAgentMiddleware>;
    responseFormat:
      ProviderStrategy<Record<string, unknown>> | TypedToolStrategy<Record<string, unknown>>;
  },
  persistence: ResolvedGraphPersistence,
  nested: Array<unknown>,
  backend: unknown,
  deepagents: typeof import("deepagents"),
) => Effect.Effect<NativeNestedSubagent, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-subagents.ts#L55)

## `runtime-native-subagents.types.ts`

Native nested subagent declaration consumed by DeepAgents construction.

### NativeNestedSubagent (interface)

Native nested subagent declaration consumed by DeepAgents construction.

**Signature**

```ts
export interface NativeNestedSubagent {
  readonly name: string;
  readonly description: string;
  readonly runnable: ReturnType<typeof import("deepagents").createDeepAgent>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-subagents.types.ts#L2)

## `runtime-native-support.ts`

Resolves native execution support, including optional DeepAgents loading, preserving initialization and nested dependency errors as invocation causes.

### DeepAgentsLoader (class)

Substitutable loader for the optional DeepAgents dependency.

**Example**

```ts
Effect.provide(loadDeepAgentsEffect(), DeepAgentsLoaderLive);
```

**Signature**

```ts
declare class DeepAgentsLoader
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L16)

### DeepAgentsLoaderLive

Live dynamic import of the optional DeepAgents dependency.

**Example**

```ts
Effect.runPromise(Effect.provide(loadDeepAgentsEffect(), DeepAgentsLoaderLive));
```

**Signature**

```ts
declare const DeepAgentsLoaderLive: Layer.Layer<DeepAgentsLoader, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L23)

### DeepAgentsLoaderService

**Signature**

```ts
declare const DeepAgentsLoaderService: DeepAgentsLoaderService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L11)

### assertAgentRuntimeDependencies

Verifies optional runtime dependencies for existing Promise callers.

**Throws**

AgentRuntimeError for an unavailable dependency.

**Example**

```ts
await assertAgentRuntimeDependencies(agents);
```

**Signature**

```ts
declare const assertAgentRuntimeDependencies: (
  agents: readonly AgentDescriptor<string, unknown, unknown>[],
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L152)

### assertAgentRuntimeDependenciesEffect

Verifies optional runtime dependencies for authored agents.

**Example**

```ts
await Effect.runPromise(
  Effect.provide(assertAgentRuntimeDependenciesEffect(agents), DeepAgentsLoaderLive),
);
```

**Signature**

```ts
declare const assertAgentRuntimeDependenciesEffect: (
  agents: ReadonlyArray<
    AgentDescriptor<
      string,
      unknown,
      unknown,
      StandardSchemaV1<unknown, unknown>,
      StandardSchemaV1<unknown, unknown>,
      ReadonlyArray<AgentMiddleware>,
      ReadonlyArray<AgentTool>
    >
  >,
) => Effect.Effect<void, AgentInvocationFailure, DeepAgentsLoader>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L139)

### combineNativeTools

Combines tool groups for existing synchronous callers.

**Throws**

The original invalid group error.

**Example**

```ts
combineNativeTools(groups);
```

**Signature**

```ts
declare const combineNativeTools: (groups: readonly NativeTools[]) => NativeTools;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L64)

### combineNativeToolsEffect

Combines public IDs and failures from native tool groups.

**Example**

```ts
Effect.runSync(combineNativeToolsEffect(groups));
```

**Signature**

```ts
declare const combineNativeToolsEffect: (
  groups: ReadonlyArray<NativeTools>,
) => Effect.Effect<NativeTools, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L35)

### loadDeepAgents

Loads DeepAgents for existing Promise callers.

**Throws**

AgentRuntimeError when the module is unavailable.

**Example**

```ts
await loadDeepAgents();
```

**Signature**

```ts
declare const loadDeepAgents: () => Promise<typeof import("deepagents")>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L125)

### loadDeepAgentsEffect

Loads the optional DeepAgents module through a replaceable service.

**Example**

```ts
await Effect.runPromise(Effect.provide(loadDeepAgentsEffect(), DeepAgentsLoaderLive));
```

**Signature**

```ts
declare const loadDeepAgentsEffect: () => Effect.Effect<
  typeof import("deepagents"),
  AgentInvocationFailure,
  DeepAgentsLoader
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L109)

### nativeInstructions

Projects native instructions for existing synchronous callers.

**Throws**

The original invalid instructions error.

**Example**

```ts
nativeInstructions(agent);
```

**Signature**

```ts
declare const nativeInstructions: (agent: AgentDescriptor<string, unknown, unknown>) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L97)

### nativeInstructionsEffect

Projects authored instructions to native system prompt text.

**Example**

```ts
Effect.runSync(nativeInstructionsEffect(agent));
```

**Signature**

```ts
declare const nativeInstructionsEffect: (
  agent: AgentDescriptor<
    string,
    unknown,
    unknown,
    StandardSchemaV1<unknown, unknown>,
    StandardSchemaV1<unknown, unknown>,
    ReadonlyArray<AgentMiddleware>,
    ReadonlyArray<AgentTool>
  >,
) => Effect.Effect<string, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.ts#L77)

## `runtime-native-support.types.ts`

Replaceable loader for the optional DeepAgents runtime dependency.

### DeepAgentsLoaderService (interface)

Replaceable loader for the optional DeepAgents runtime dependency.

**Signature**

```ts
export interface DeepAgentsLoaderService {
  /** Loads the optional runtime module.
   * @returns The DeepAgents module.
   * @example await loader.load();
   */
  readonly load: () => Promise<typeof import("deepagents")>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-support.types.ts#L2)

## `runtime-native-tool-build.ts`

Converts one checked reference into a native tool while preserving common-engine
execution, trace context and the deferred approval failure reader.

### nativeToolEntry

Resolves one authored tool and records its public native mapping.

**Signature**

```ts
declare const nativeToolEntry: (
  entry: AgentTool,
  index: number,
  context: NativeToolBuildContext,
) => ClientTool | ServerTool | ReturnType<typeof tool>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tool-build.ts#L23)

## `runtime-native-tool-build.types.ts`

Invocation-owned tool identity maps and deferred native failure authority.

### NativeToolBuildContext (interface)

**Signature**

```ts
export interface NativeToolBuildContext {
  readonly options: NativeToolRuntimeOptions;
  readonly signal: AbortSignal;
  readonly maxOutputBytes: number;
  readonly invocationId: string;
  readonly traceId: string;
  readonly identity: NativeToolIdentityService;
  readonly publicIds: Map<string, string>;
  readonly relkitNames: Set<string>;
  readonly setFailure: (cause: unknown) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tool-build.types.ts#L6)

## `runtime-native-tools-identity.ts`

Derives stable native tool identities used by descriptor adaptation and runtime dispatch without cloning the SDK tool instances.

### NativeToolIdentity (class)

Substitutable native tool call identity source.

**Example**

```ts
Effect.provide(createNativeToolsEffect(options, signal, 1024, id, trace), NativeToolIdentityLive);
```

**Signature**

```ts
declare class NativeToolIdentity
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools-identity.ts#L9)

### NativeToolIdentityLive

Live UUID source for native tool calls.

**Example**

```ts
Effect.runSync(Effect.provide(effect, NativeToolIdentityLive));
```

**Signature**

```ts
declare const NativeToolIdentityLive: Layer.Layer<NativeToolIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools-identity.ts#L17)

## `runtime-native-tools.ts`

Combines authored native tools and RELKIT callable adapters for invocation, retaining input schemas and native dispatch identity.

### NativeToolIdentity

**Signature**

```ts
declare const NativeToolIdentity: typeof NativeToolIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.ts#L18)

### NativeToolIdentityLive

**Signature**

```ts
declare const NativeToolIdentityLive: Layer<NativeToolIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.ts#L18)

### NativeTools

**Signature**

```ts
declare const NativeTools: NativeTools;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.ts#L17)

### createNativeTools

Materializes native tools for existing synchronous callers.

**Throws**

The original unknown tool or schema error.

**Example**

```ts
createNativeTools(options, signal, 1024, id, trace);
```

**Signature**

```ts
declare const createNativeTools: (
  options: NativeToolRuntimeOptions,
  signal: AbortSignal,
  maxOutputBytes: number,
  invocationId: string,
  traceId: string,
) => NativeTools;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.ts#L77)

### createNativeToolsEffect

Materializes LangChain tools with public IDs and an invocation failure reader.

**Example**

```ts
Effect.runSync(
  Effect.provide(createNativeToolsEffect(options, signal, 1024, id, trace), NativeToolIdentityLive),
);
```

**Signature**

```ts
declare const createNativeToolsEffect: (
  options: NativeToolRuntimeOptions,
  signal: AbortSignal,
  maxOutputBytes: number,
  invocationId: string,
  traceId: string,
) => Effect.Effect<NativeTools, AgentInvocationFailure, NativeToolIdentity>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.ts#L29)

## `runtime-native-tools.types.ts`

Combines authored native tools and RELKIT callable adapters for invocation, retaining input schemas and native dispatch identity. This companion preserves the native input and output types without starting runtime work.

### NativeToolIdentityService (interface)

Replaceable identity source for native tool calls.

**Signature**

```ts
export interface NativeToolIdentityService {
  /** Creates a call identity when LangChain does not supply one.
   * @returns A UUID.
   * @example identity.randomUUID();
   */
  readonly randomUUID: () => string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.types.ts#L20)

### NativeToolRuntimeOptions (type alias)

Runtime context used to materialize native tools.

**Signature**

```ts
type NativeToolRuntimeOptions = AgentRuntimeOptions & AgentInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.types.ts#L17)

### NativeTools (interface)

Native tools and public identity mapping for one invocation.

**Signature**

```ts
export interface NativeTools {
  readonly values: readonly (
    ClientTool | ServerTool | ReturnType<typeof import("langchain").tool>
  )[];
  readonly publicIds: ReadonlyMap<string, string>;
  readonly relkitNames: ReadonlySet<string>;
  readonly failure: () => unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-native-tools.types.ts#L7)

## `runtime-service.ts`

Provides the Effect runtime service that composes native model resolution, tools and loop execution under the invocation owner.

### AgentExecution (class)

Injectable model, graph, loop, and identity boundary.

**Example**

```ts
Effect.provide(invokeAgentEffect(options), AgentExecutionLive);
```

**Signature**

```ts
declare class AgentExecution
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-service.ts#L14)

### AgentExecutionLive

Live agent integrations used by the Promise compatibility API.

**Example**

```ts
Effect.runPromise(Effect.provide(invokeAgentEffect(options), AgentExecutionLive));
```

**Signature**

```ts
declare const AgentExecutionLive: Layer.Layer<AgentExecution, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-service.ts#L21)

### AgentExecutionService

**Signature**

```ts
declare const AgentExecutionService: AgentExecutionService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-service.ts#L9)

## `runtime-service.types.ts`

Provides the Effect runtime service that composes native model resolution, tools and loop execution under the invocation owner. This companion preserves the native input and output types without starting runtime work.

### AgentExecutionService (interface)

Substitutable integrations used while invoking an agent.

**Signature**

```ts
export interface AgentExecutionService {
  readonly resolveModel: typeof resolveRuntimeModel;
  readonly runLoop: typeof runAgentLoop;
  readonly invokeGraph: typeof invokeGraph;
  readonly randomUUID: () => string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-service.types.ts#L8)

## `runtime-state-schemas.ts`

Decodes invocation state and output values at the native runtime boundary before persisted or public projections consume them.

### selectedStateSchemas

Resolves public state validators for existing synchronous callers.

**Throws**

TypeError for a selected key without a validator.

**Example**

```ts
selectedStateSchemas([state], ["answer"]);
```

**Signature**

```ts
declare const selectedStateSchemas: (
  sources: readonly unknown[],
  selected: readonly string[],
) => ReadonlyMap<string, StandardSchemaV1>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-state-schemas.ts#L30)

### selectedStateSchemasEffect

Resolves validators for selected public state keys.

**Example**

```ts
Effect.runSync(selectedStateSchemasEffect([state], ["answer"]));
```

**Signature**

```ts
declare const selectedStateSchemasEffect: (
  sources: ReadonlyArray<unknown>,
  selected: ReadonlyArray<string>,
) => Effect.Effect<
  ReadonlyMap<string, StandardSchemaV1<unknown, unknown>>,
  AgentInvocationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-state-schemas.ts#L14)

## `runtime-strict-response-schema.ts`

Selects the structural JSON-schema subset that can use provider enforcement without making optional fields required.

### strictResponseSchema

Closes declared objects for native generation; runtime validation still uses the authored schema.

**Signature**

```ts
declare const strictResponseSchema: (schema: JsonSchema, depth?: number) => JsonSchema | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-strict-response-schema.ts#L24)

## `runtime-tool-adapter.ts`

Adapts RELKIT callable tools to native SDK tools while preserving validated input, execution context and typed invocation failures.

### createAgentInvocationDispatcher

**Signature**

```ts
declare const createAgentInvocationDispatcher: (
  engine: ToolEngine,
  options: RuntimeToolOptions,
  invocationId: string,
  traceId: string | undefined,
  parentSpanId: string | undefined,
  signal: AbortSignal,
) => InvocationDispatcher;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-adapter.ts#L24)

### createAgentInvocationDispatcherEffect

**Signature**

```ts
declare const createAgentInvocationDispatcherEffect: (
  engine: ToolEngine,
  options: RuntimeToolOptions,
  invocationId: string,
  traceId: string | undefined,
  parentSpanId: string | undefined,
  signal: AbortSignal,
) => Effect.Effect<
  Readonly<{
    dispatch: <Input, Output, Context extends { readonly signal: AbortSignal }>(
      request: InvocationDispatchRequest<Input, Output, Context>,
    ) => Promise<Output>;
  }>,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-adapter.ts#L25)

### invokeAgentTool

Invokes an allowed tool for existing Promise callers.

**Throws**

The original validation, sink, approval, or tool error.

**Example**

```ts
await invokeAgentTool(engine, tool, turn, options, signal, id);
```

**Signature**

```ts
declare const invokeAgentTool: (
  engine: ToolEngine,
  tool: ToolDescriptor<string>,
  turn: AgentToolCall,
  options: RuntimeToolOptions,
  signal: AbortSignal,
  invocationId: string,
  traceId?: string,
  parentSpanId?: string,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-adapter.ts#L104)

### invokeAgentToolEffect

Invokes an allowed tool with validated input and public lifecycle events.

**Example**

```ts
await Effect.runPromise(invokeAgentToolEffect(engine, tool, turn, options, signal, id));
```

**Signature**

```ts
declare const invokeAgentToolEffect: (
  engine: ToolEngine,
  tool: ToolDescriptor<string>,
  turn: AgentToolCall,
  options: RuntimeToolOptions,
  signal: AbortSignal,
  invocationId: string,
  traceId?: string | undefined,
  parentSpanId?: string | undefined,
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-adapter.ts#L40)

## `runtime-tool-dispatcher.ts`

Dispatches native tool calls to the selected RELKIT tool target and carries approval and execution failures back to the native loop.

### createAgentInvocationDispatcher

Creates a nested function dispatcher for existing synchronous callers.

**Example**

```ts
createAgentInvocationDispatcher(engine, options, id, trace, span, signal);
```

**Signature**

```ts
declare const createAgentInvocationDispatcher: (
  engine: ToolEngine,
  options: RuntimeToolOptions,
  invocationId: string,
  traceId: string | undefined,
  parentSpanId: string | undefined,
  signal: AbortSignal,
) => InvocationDispatcher;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-dispatcher.ts#L89)

### createAgentInvocationDispatcherEffect

Creates a nested function dispatcher with stable agent parent context.

**Example**

```ts
Effect.runSync(createAgentInvocationDispatcherEffect(engine, options, id, trace, span, signal));
```

**Signature**

```ts
declare const createAgentInvocationDispatcherEffect: (
  engine: ToolEngine,
  options: RuntimeToolOptions,
  invocationId: string,
  traceId: string | undefined,
  parentSpanId: string | undefined,
  signal: AbortSignal,
) => Effect.Effect<
  Readonly<{
    dispatch: <Input, Output, Context extends { readonly signal: AbortSignal }>(
      request: InvocationDispatchRequest<Input, Output, Context>,
    ) => Promise<Output>;
  }>,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-dispatcher.ts#L24)

## `runtime-tool-events.ts`

Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering.

### emitTool

Emits a tool transition for existing Promise callers.

**Throws**

The original sink or cancellation error.

**Example**

```ts
await emitTool(options, turn, "running", undefined, signal);
```

**Signature**

```ts
declare const emitTool: (
  options: RuntimeToolOptions,
  turn: Pick<AgentToolCall, "callId" | "toolId">,
  state: ToolPartState,
  value: unknown,
  signal: AbortSignal,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-events.ts#L70)

### emitToolEffect

Emits a public tool transition with linked Effect cancellation.

**Example**

```ts
await Effect.runPromise(emitToolEffect(options, turn, "running", undefined, signal));
```

**Signature**

```ts
declare const emitToolEffect: (
  options: RuntimeToolOptions,
  turn: Pick<AgentToolCall, "callId" | "toolId">,
  state: ToolPartState,
  value: unknown,
  signal: AbortSignal,
) => Effect.Effect<undefined, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-events.ts#L29)

### resolveAgentApproval

Resolves approval for existing Promise callers.

**Throws**

The original approval, sink, or cancellation error.

**Example**

```ts
await resolveAgentApproval(options, request, callId, id, signal);
```

**Signature**

```ts
declare const resolveAgentApproval: (
  options: RuntimeToolOptions,
  request: ToolApprovalRequest,
  toolCallId: string,
  invocationId: string,
  signal: AbortSignal,
) => Promise<true>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-events.ts#L163)

### resolveAgentApprovalEffect

Resolves tool approval and emits its lifecycle transitions.

**Example**

```ts
await Effect.runPromise(resolveAgentApprovalEffect(options, request, callId, id, signal));
```

**Signature**

```ts
declare const resolveAgentApprovalEffect: (
  options: RuntimeToolOptions,
  request: FunctionToolApprovalRequest,
  toolCallId: string,
  invocationId: string,
  signal: AbortSignal,
) => Effect.Effect<true, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-events.ts#L94)

## `runtime-tool-events.types.ts`

Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering. This companion preserves the native input and output types without starting runtime work.

### RuntimeToolOptions (type alias)

Runtime integrations needed to emit tool events and resolve approval.
The invocation options supply the approval callback and content sink.

**Example**

```ts
const options: RuntimeToolOptions = { ...runtime, input };
```

**Signature**

```ts
type RuntimeToolOptions = AgentRuntimeOptions & AgentInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-events.types.ts#L9)

## `runtime-tool-invocation.ts`

Executes a validated tool in the original invocation scope and emits terminal
lifecycle records without changing approval or progress routing.

### invokeRegisteredAgentToolEffect

Dispatches a checked tool inside its existing call scope.

**Signature**

```ts
declare const invokeRegisteredAgentToolEffect: (
  engine: ToolEngine,
  tool: ToolDescriptor<string>,
  turn: AgentToolCall,
  options: RuntimeToolOptions,
  signal: AbortSignal,
  invocationId: string,
  traceId: string | undefined,
  parentSpanId: string | undefined,
  progressSink: ProgressSink | undefined,
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-invocation.ts#L32)

## `runtime-tool-lookup.ts`

Resolves authored RELKIT tool references against the invocation tool registry before native tool construction.

### findModelTool

Finds a native tool for existing synchronous callers.

**Example**

```ts
findModelTool(tools, refs, "math_add_0");
```

**Signature**

```ts
declare const findModelTool: (
  source: ToolSource,
  refs: readonly { readonly ref: { readonly id: string } }[],
  name: string,
) => ToolDescriptor<string> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L57)

### findModelToolEffect

Finds a native tool by direct or model-facing name.

**Example**

```ts
Effect.runSync(findModelToolEffect(tools, refs, "math_add_0"));
```

**Signature**

```ts
declare const findModelToolEffect: (
  source: ToolSource,
  refs: ReadonlyArray<{ readonly ref: { readonly id: string } }>,
  name: string,
) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L39)

### findTool

Finds a tool for existing synchronous callers.

**Example**

```ts
findTool(tools, "math.add");
```

**Signature**

```ts
declare const findTool: (source: ToolSource, id: string) => ToolDescriptor<string> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L82)

### findToolEffect

Finds a registered tool by map key or descriptor ID.

**Example**

```ts
Effect.runSync(findToolEffect(tools, "math.add"));
```

**Signature**

```ts
declare const findToolEffect: (
  source: ToolSource,
  id: string,
) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L71)

### modelToolName

Produces a native tool name for existing synchronous callers.

**Example**

```ts
modelToolName("math.add", 0);
```

**Signature**

```ts
declare const modelToolName: (id: string, index: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L28)

### modelToolNameEffect

Produces a bounded model-facing name for one tool ID.

**Example**

```ts
Effect.runSync(modelToolNameEffect("math.add", 0));
```

**Signature**

```ts
declare const modelToolNameEffect: (
  id: string,
  index: number,
) => Effect.Effect<string, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tool-lookup.ts#L13)

## `runtime-tools.ts`

Builds invocation tool bindings from the selected RELKIT registry and native tool descriptors, keeping execution ownership with the caller.

### AgentToolCall

**Signature**

```ts
declare const AgentToolCall: AgentToolCall;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L17)

### findModelTool

**Signature**

```ts
declare const findModelTool: (
  source: ToolSource,
  refs: readonly { readonly ref: { readonly id: string } }[],
  name: string,
) => ToolDescriptor<string> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L19)

### findModelToolEffect

**Signature**

```ts
declare const findModelToolEffect: (
  source: ToolSource,
  refs: ReadonlyArray<{ readonly ref: { readonly id: string } }>,
  name: string,
) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L20)

### findTool

**Signature**

```ts
declare const findTool: (source: ToolSource, id: string) => ToolDescriptor<string> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L21)

### findToolEffect

**Signature**

```ts
declare const findToolEffect: (
  source: ToolSource,
  id: string,
) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L22)

### modelToolName

**Signature**

```ts
declare const modelToolName: (id: string, index: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L23)

### modelToolNameEffect

**Signature**

```ts
declare const modelToolNameEffect: (
  id: string,
  index: number,
) => Effect.Effect<string, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L24)

### runTool

Executes a tool for existing Promise callers.

**Throws**

ApprovalRequiredError or AgentRuntimeError for cancellation.

**Example**

```ts
await runTool(options, turn, signal, 1024, id);
```

**Signature**

```ts
declare const runTool: (
  options: AgentRuntimeOptions & AgentInvocationOptions,
  turn: AgentToolCall,
  signal: AbortSignal,
  maxOutputBytes: number,
  invocationId: string,
  traceId?: string,
  parentSpanId?: string,
) => Promise<JsonValue>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L99)

### runToolEffect

Executes an allowed RELKIT tool with safe public error projection.

**Example**

```ts
await Effect.runPromise(runToolEffect(options, turn, signal, 1024, id));
```

**Signature**

```ts
declare const runToolEffect: (
  options: AgentRuntimeBaseOptions & { readonly modelRegistry?: unknown } & AgentInvocationOptions,
  turn: AgentToolCall,
  signal: AbortSignal,
  maxOutputBytes: number,
  invocationId: string,
  traceId?: string | undefined,
  parentSpanId?: string | undefined,
) => Effect.Effect<JsonValue, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.ts#L38)

## `runtime-tools.types.ts`

One model requested RELKIT tool call.

### AgentToolCall (interface)

One model requested RELKIT tool call.

**Signature**

```ts
export interface AgentToolCall {
  readonly callId: string;
  readonly toolId: string;
  readonly input: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-tools.types.ts#L2)

## `runtime-utils.ts`

Normalizes native invocation utility values shared by runtime adapters without changing the owning request's execution context.

### createExecutionSignal

**Signature**

```ts
declare const createExecutionSignal: (options: ExecutionSignalOptions) => ExecutionSignalHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L10)

### jsonValue

Produces bounded JSON for existing synchronous callers.

**Throws**

AgentRuntimeError for invalid JSON or byte limits.

**Example**

```ts
jsonValue({ ok: true }, 1024, "output");
```

**Signature**

```ts
declare const jsonValue: (value: unknown, maxBytes: number, label: string) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L95)

### jsonValueEffect

Produces bounded, canonical JSON from a runtime value.

**Example**

```ts
Effect.runSync(jsonValueEffect({ ok: true }, 1024, "output"));
```

**Signature**

```ts
declare const jsonValueEffect: (
  value: unknown,
  maxBytes: number,
  label: string,
) => Effect.Effect<JsonValue, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L78)

### modelFailure

Classifies a model failure for existing synchronous callers.

**Example**

```ts
modelFailure(error, signal);
```

**Signature**

```ts
declare const modelFailure: (cause: unknown, signal: AbortSignal) => AgentRuntimeError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L132)

### modelFailureEffect

Classifies a model failure without exposing provider details.

**Example**

```ts
Effect.runSync(modelFailureEffect(error, signal));
```

**Signature**

```ts
declare const modelFailureEffect: (
  cause: unknown,
  signal: AbortSignal,
) => Effect.Effect<AgentRuntimeError, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L121)

### signalFailure

**Signature**

```ts
declare const signalFailure: (signal: AbortSignal) => AgentRuntimeError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L10)

### validateValue

Validates an invocation value for existing Promise callers.

**Throws**

AgentRuntimeError for invalid values.

**Example**

```ts
await validateValue(schema, input, "input");
```

**Signature**

```ts
declare const validateValue: (
  schema: StandardSchemaV1,
  value: unknown,
  phase: "input" | "output",
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L36)

### validateValueEffect

Validates an invocation value through a Standard Schema.

**Example**

```ts
await Effect.runPromise(validateValueEffect(schema, input, "input"));
```

**Signature**

```ts
declare const validateValueEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  value: unknown,
  phase: "input" | "output",
) => Effect.Effect<unknown, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L19)

### withSignal

**Signature**

```ts
declare const withSignal: <T>(work: MaybePromise<T>, signal: AbortSignal) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime-utils.ts#L10)

## `runtime.ts`

Exposes generated and direct native invocation entrypoints plus dependency and persistence lifecycle operations for the selected integration.

### "./runtime.types.js" (namespace export)

Re-exports all named exports from the "./runtime.types.js" module.

**Signature**

```ts
export * from "./runtime.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L19)

### AgentInvocationFailure

**Signature**

```ts
declare const AgentInvocationFailure: typeof AgentInvocationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L26)

### AgentRuntimeError

**Signature**

```ts
declare const AgentRuntimeError: typeof AgentRuntimeError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L25)

### assertAgentRuntimeDependencies

**Signature**

```ts
declare const assertAgentRuntimeDependencies: (
  agents: readonly AgentDescriptor<string, unknown, unknown>[],
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L23)

### createAgentRuntime

Binds one agent catalog for existing synchronous callers.

**Example**

```ts
const runtime = createAgentRuntime(options);
```

**Signature**

```ts
declare const createAgentRuntime: (options: AgentRuntimeOptions) => AgentRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L116)

### createAgentRuntimeEffect

Creates a reusable runtime through an observable Effect.

**Example**

```ts
Effect.runSync(createAgentRuntimeEffect(options));
```

**Signature**

```ts
declare const createAgentRuntimeEffect: (
  options: AgentRuntimeOptions,
) => Effect.Effect<AgentRuntime, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L99)

### createGeneratedAgentFunction

**Signature**

```ts
declare const createGeneratedAgentFunction: (
  agentId: unknown,
  executor?: GeneratedAgentExecutor,
) => GeneratedAgentFunction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L21)

### invokeAgent

Runs an agent through the live Effect Layer for existing Promise callers.

**Throws**

The original validation, provider, cancellation, or runtime error.

**Example**

```ts
await invokeAgent({ ...options, input: { message: "hi" } });
```

**Signature**

```ts
declare const invokeAgent: (
  options: AgentRuntimeOptions & AgentInvocationOptions,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L64)

### invokeAgentEffect

Invokes an agent with typed failures and interruption linked to its work.

**Example**

```ts
Effect.runPromise(Effect.provide(invokeAgentEffect(options), AgentExecutionLive));
```

**Signature**

```ts
declare const invokeAgentEffect: (
  options: AgentRuntimeBaseOptions & { readonly modelRegistry?: unknown } & AgentInvocationOptions,
) => Effect.Effect<unknown, AgentInvocationFailure, AgentExecution>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L33)

### invokeAgentFunction

Runs an agent once for generated function actions, retaining output failure identity.

**Example**

```ts
await invokeAgentFunction(options);
```

**Signature**

```ts
declare const invokeAgentFunction: (
  options: AgentRuntimeOptions & AgentInvocationOptions,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L82)

### releaseAgentPersistence

**Signature**

```ts
declare const releaseAgentPersistence: (descriptors: readonly unknown[]) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L22)

### runAgent

**Signature**

```ts
declare const runAgent: (options: AgentRuntimeOptions & AgentInvocationOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L120)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "langchain";
  registrations: ReadonlyArray<{ capability: string; adapterId: string; protocolVersion: number }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.ts#L20)

## `runtime.types.ts`

Exposes generated and direct native invocation entrypoints plus dependency and persistence lifecycle operations for the selected integration. This companion preserves the native input and output types without starting runtime work.

### AgentApprovalHandler (type alias)

Resolves a pending tool approval for an invocation.

**Signature**

```ts
type AgentApprovalHandler = (
  approval: import("@relkit/agents/internal/approval").PendingApproval,
) => MaybePromise<ApprovalDecision>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L13)

### AgentContentSink (interface)

Sends agent output and events to the surrounding runtime.

**Signature**

```ts
export interface AgentContentSink {
  readonly emitOutput: (value: unknown, signal: AbortSignal) => MaybePromise<void>;
  readonly finishOutput?: (signal: AbortSignal) => MaybePromise<void>;
  readonly progressSinkForTool?: (tool: {
    readonly toolCallId: string;
    readonly toolId: string;
  }) => import("@relkit/invocation").ProgressSink;
  readonly emitTool?: (
    value: {
      readonly toolCallId: string;
      readonly toolId: string;
      readonly state: import("@relkit/agents/internal/state.types").ToolPartState;
      readonly value?: unknown;
    },
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitEvent?: (
    value: import("@relkit/agents/internal/runtime-events").AgentExecutionEvent,
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitMessage?: (
    value: import("@relkit/contracts").BrowserMessage,
    signal: AbortSignal,
  ) => MaybePromise<void>;
  readonly emitWaiting?: (
    value: Omit<
      import("@relkit/agents/internal/state.types").AgentWaitingState,
      "revision" | "runId"
    >,
    signal: AbortSignal,
  ) => MaybePromise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L29)

### AgentConversationMessage (interface)

One user or assistant message in a native agent conversation.

**Signature**

```ts
export interface AgentConversationMessage {
  readonly role: "user" | "assistant";
  readonly content: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L23)

### AgentInvocationOptions (interface)

Per-call identity, input, cancellation, and control options.

**Signature**

```ts
export interface AgentInvocationOptions {
  readonly input: unknown;
  readonly invocationId?: string;
  readonly signal?: AbortSignal;
  readonly deadlineMs?: number;
  readonly timeoutMs?: number;
  readonly approval?: AgentApprovalHandler;
  readonly traceId?: string;
  readonly parentSpanId?: string;
  readonly hooks?: AgentRuntimeHooks;
  readonly capture?: AgentCapturePolicy;
  readonly threadId?: string;
  readonly resume?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L85)

### AgentRuntime (interface)

Reusable invocation API bound to one agent catalog.

**Signature**

```ts
export interface AgentRuntime {
  readonly invoke: (
    input: unknown,
    options?: Omit<AgentInvocationOptions, "input">,
  ) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L101)

### AgentRuntimeBaseOptions (interface)

Common authoring and execution dependencies for an agent runtime.

**Signature**

```ts
export interface AgentRuntimeBaseOptions {
  readonly agent: AgentAny;
  readonly tools: import("@relkit/tools").ToolSource;
  readonly bucketBackend?: import("./deepagent-bucket-client.types.js").DeepAgentBucketClient;
  readonly engine: import("@relkit/tools").ToolEngine;
  readonly maxInputBytes?: number;
  readonly maxOutputBytes?: number;
  readonly approval?: AgentApprovalHandler;
  readonly messages?: readonly AgentConversationMessage[];
  readonly steering?: AgentSteeringSource;
  readonly contentSink?: AgentContentSink;
  readonly hooks?: AgentRuntimeHooks;
  readonly capture?: AgentCapturePolicy;
  readonly environment?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L63)

### AgentRuntimeOptions (type alias)

Long-lived dependencies shared by agent invocations.

**Signature**

```ts
type AgentRuntimeOptions = AgentRuntimeBaseOptions & {
  readonly modelRegistry?: unknown;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L80)

### AgentSteeringSource (interface)

Supplies queued steering messages to a running agent.

**Signature**

```ts
export interface AgentSteeringSource {
  readonly drain: () => MaybePromise<readonly string[]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/runtime.types.ts#L18)

## `signal-deadline.ts`

Resolves the earliest authored deadline before the signal owner installs its
timer. Invalid timeout/deadline values preserve the existing public diagnostic.

### executionDeadline

Selects the earliest finite invocation deadline.

**Signature**

```ts
declare const executionDeadline: (options: ExecutionSignalOptions, now: number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal-deadline.ts#L13)

## `signal.ts`

Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity.

### "./signal.types.js" (namespace export)

Re-exports all named exports from the "./signal.types.js" module.

**Signature**

```ts
export * from "./signal.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L15)

### ExecutionSignalClock (class)

Replaceable clock and timer boundary for execution deadlines.

**Example**

```ts
Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive);
```

**Signature**

```ts
declare class ExecutionSignalClock
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L20)

### ExecutionSignalClockLive

Live wall clock and timer implementation.

**Example**

```ts
Effect.runSync(Effect.provide(createExecutionSignalEffect(options), ExecutionSignalClockLive));
```

**Signature**

```ts
declare const ExecutionSignalClockLive: Layer.Layer<ExecutionSignalClock, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L28)

### acquireExecutionSignalEffect

Acquires an execution signal whose owner closes it with its Effect scope.

**Example**

```ts
Effect.scoped(
  Effect.gen(function* () {
    const active = yield* acquireExecutionSignalEffect(options);
  }),
);
```

**Signature**

```ts
declare const acquireExecutionSignalEffect: (
  options: ExecutionSignalOptions,
) => Effect.Effect<ExecutionSignalHandle, AgentInvocationFailure, ExecutionSignalClock | Scope>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L113)

### createExecutionSignal

Creates a live signal for existing callers that own and close the handle.

**Throws**

The original invalid deadline error.

**Example**

```ts
const active = createExecutionSignal(options);
try {
  await work(active.signal);
} finally {
  active.close();
}
```

**Signature**

```ts
declare const createExecutionSignal: (options: ExecutionSignalOptions) => ExecutionSignalHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L127)

### createExecutionSignalEffect

Creates a live execution signal with an owned timer and caller listener.

**Example**

```ts
Effect.runSync(Effect.provide(createExecutionSignalEffect(options), testClock));
```

**Signature**

```ts
declare const createExecutionSignalEffect: (
  options: ExecutionSignalOptions,
) => Effect.Effect<ExecutionSignalHandle, AgentInvocationFailure, ExecutionSignalClock>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L66)

### signalFailure

Converts an abort reason for existing synchronous callers.

**Example**

```ts
signalFailure(signal);
```

**Signature**

```ts
declare const signalFailure: (signal: AbortSignal) => AgentRuntimeError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L57)

### signalFailureEffect

Converts an abort reason to a safe invocation error.

**Example**

```ts
Effect.runSync(signalFailureEffect(signal));
```

**Signature**

```ts
declare const signalFailureEffect: (
  signal: AbortSignal,
) => Effect.Effect<AgentRuntimeError, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L42)

### withSignal

Races work with a caller signal for existing Promise callers.

**Throws**

The original work error or AgentRuntimeError on cancellation.

**Example**

```ts
await withSignal(fetchData(), signal);
```

**Signature**

```ts
declare const withSignal: <T>(work: MaybePromise<T>, signal: AbortSignal) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L160)

### withSignalEffect

Races Promise work with caller and Effect cancellation.

**Example**

```ts
await Effect.runPromise(withSignalEffect(work, signal));
```

**Signature**

```ts
declare const withSignalEffect: <T>(
  work: MaybePromise<T>,
  signal: AbortSignal,
  linkEffectSignal?: boolean | undefined,
) => Effect.Effect<T, AgentInvocationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.ts#L143)

## `signal.types.ts`

Builds and validates RELKIT signal descriptors used by native agent execution while retaining their payload schema and stable identity. This companion preserves the native input and output types without starting runtime work.

### ExecutionSignalClockService (interface)

Replaceable deadline timer and current time boundary.

**Signature**

```ts
export interface ExecutionSignalClockService {
  /** Reads the current wall time in milliseconds.
   * @returns Epoch milliseconds.
   * @example clock.now();
   */
  readonly now: () => number;
  /** Schedules a deadline callback.
   * @param callback - Deadline action.
   * @param delayMs - Nonnegative delay.
   * @returns Opaque timer handle.
   * @example clock.setTimeout(onDeadline, 1000);
   */
  readonly setTimeout: (callback: () => void, delayMs: number) => unknown;
  /** Cancels a scheduled callback.
   * @param handle - Opaque timer handle.
   * @returns Nothing.
   * @example clock.clearTimeout(handle);
   */
  readonly clearTimeout: (handle: unknown) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.types.ts#L19)

### ExecutionSignalHandle (interface)

Live execution signal whose owner must call close once finished.

**Signature**

```ts
export interface ExecutionSignalHandle {
  readonly signal: AbortSignal;
  /** Clears the deadline timer and caller signal listener.
   * @returns Nothing; repeated calls are safe.
   * @example handle.close();
   */
  readonly close: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.types.ts#L9)

### ExecutionSignalOptions (type alias)

Options whose limits and caller signal determine an execution deadline.

**Signature**

```ts
type ExecutionSignalOptions = AgentRuntimeOptions & AgentInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/signal.types.ts#L6)

## `agent-approvals.ts`

Owns native pending decisions and cancellation listeners for one test agent.
Settlement removes its listener before completing the same deferred decision.

### createAgentApprovalState

Creates isolated native approval controls.

**Signature**

```ts
declare const createAgentApprovalState: (
  choice: TestAgentApproval | undefined,
) => AgentApprovalState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-approvals.ts#L14)

## `agent-approvals.types.ts`

Exercises native agent approval continuations through the harness's scoped model and execution owner, retaining resume identity and cleanup. This companion preserves the native input and output types without starting runtime work.

### AgentApprovalOwnedState (interface)

Native callback state retained by one test approval owner.

**Signature**

```ts
export interface AgentApprovalOwnedState {
  readonly pending: Map<string, import("../index.js").PendingApproval>;
  readonly decisions: Map<string, PendingAgentDecision>;
  readonly signals: Map<string, AbortSignal>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-approvals.types.ts#L23)

### AgentApprovalState (interface)

Synchronous controls over owned native approval decisions and cancellation.

**Signature**

```ts
export interface AgentApprovalState extends TestAgentApprovals {
  readonly handler?: AgentApprovalHandler;
  readonly reset: () => void;
  readonly registerSignal: (id: string, signal: AbortSignal) => void;
  readonly releaseSignal: (id: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-approvals.types.ts#L15)

### PendingAgentDecision (interface)

Deferred decision authority and its native cancellation listener.

**Signature**

```ts
export interface PendingAgentDecision {
  readonly done: Deferred.Deferred<"approved" | "denied">;
  readonly signal?: AbortSignal;
  readonly abort: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-approvals.types.ts#L8)

## `agent-harness.types.ts`

Defines the native test harness execution and lifecycle contract shared by model, tool and approval helpers. This companion preserves the native input and output types without starting runtime work.

### AgentHarnessDependencies (type alias)

Acquired native model, state and observer dependencies for one harness owner.

**Signature**

```ts
type AgentHarnessDependencies = Effect.Success<ReturnType<typeof acquireAgentHarness>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-harness.types.ts#L10)

### AgentHarnessService (interface)

Native state facade and Effect-owned invocation/shutdown workflows.

**Signature**

```ts
export interface AgentHarnessService {
  readonly close: Effect.Effect<void, unknown>;
  readonly value: Omit<TestAgent, "invoke">;
  readonly invoke: (
    input: unknown,
    invocation?: TestAgentInvocationOptions,
  ) => Effect.Effect<unknown, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-harness.types.ts#L24)

### AgentOwnedState (interface)

Trace ledgers and native work belong to the same agent owner.

**Signature**

```ts
export interface AgentOwnedState {
  closed: boolean;
  invocationSequence: number;
  readonly spans: ReturnType<typeof spanSnapshot>[];
  readonly edges: AgentObservedEdge[];
  readonly active: Set<AbortController>;
  readonly pending: Set<Promise<unknown>>;
  closing?: Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-harness.types.ts#L13)

## `agent-state-invocation.ts`

Runs native invocations under the harness-owned span and cancellation lifetime.

### invokeAgentHarness

**Signature**

```ts
declare const invokeAgentHarness: <Agent extends TestAgentDescriptor>(
  options: TestAgentOptions<Agent>,
  harness: AgentHarnessDependencies,
  input: import("@relkit/schema").InferInput<Agent["input"]>,
  invocation?: TestAgentInvocationOptions,
) => Promise<import("@relkit/schema").InferOutput<Agent["output"]>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-state-invocation.ts#L13)

## `agent-state-lifecycle.ts`

Stops admission before aborting and joining every native invocation and model owner.

### agentHarnessClose

**Signature**

```ts
declare const agentHarnessClose: (
  context: Context.Context<never>,
  harness: AgentHarnessDependencies,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-state-lifecycle.ts#L6)

### resetAgentHarness

**Signature**

```ts
declare const resetAgentHarness: (harness: AgentHarnessDependencies) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-state-lifecycle.ts#L38)

## `agent-state-setup.ts`

Acquires one native test model and its trace, approval and cancellation state.

### acquireAgentHarness

**Signature**

```ts
declare const acquireAgentHarness: (
  options: TestAgentOptions<TestAgentDescriptor>,
) => Effect.Effect<
  {
    failures: TestFailureControls;
    model: RuntimeTestAgentModel;
    state: Ref.Ref<AgentOwnedState>;
    approvals: AgentApprovalState;
    trace: TestAgentTrace;
    hooks: AgentRuntimeHooks;
    spanRuntime: SpanRuntime;
    engine: {
      invoke: (
        request: Parameters<(options: ToolEngineInvocation) => Promise<unknown>>[0],
      ) => Promise<unknown>;
    };
  },
  never,
  Scope
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-state-setup.ts#L11)

## `agent-state.ts`

Builds an isolated native test facade whose work is joined before release.

### createAgentState

Creates a network-free test owner retaining descriptor schema inference.

**Signature**

```ts
declare const createAgentState: <Agent extends TestAgentDescriptor>(
  options: TestAgentOptions<Agent>,
) => Effect.Effect<
  { value: TestAgent<Agent>; close: Effect.Effect<void, unknown, never> },
  never,
  Scope
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agent-state.ts#L13)

## `agents-model-native.ts`

Implements the scripted native chat-model adapter used by agent tests, preserving tool-call correlation and queued response ordering.

### ScriptedChatModel (class)

Native LangChain model transport; script and cancellation remain owned by TestModelScript.

**Signature**

```ts
declare class ScriptedChatModel { constructor(
    private readonly turn: (
      request: TestAgentModelCall["request"],
      signal?: AbortSignal,
    ) => Promise<TestModelTurn>,
    private readonly provider: string,
    private readonly modelId: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-native.ts#L15)

### \_llmType (method)

**Signature**

```ts
declare const _llmType: () => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-native.ts#L36)

### bindTools (method)

Records native presented tools for script-to-tool name matching.

**Signature**

```ts
declare const bindTools: (tools: BindToolsInput[]) => this;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-native.ts#L45)

### \_generate (method)

Consumes one owned scripted turn using the native invocation signal.

**Signature**

```ts
declare const _generate: (
  messages: BaseMessage[],
  _options?: this["ParsedCallOptions"],
  _runManager?: CallbackManagerForLLMRun,
) => Promise<ChatResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-native.ts#L57)

## `agents-model-operations.ts`

Applies scripted native turns under the test model owner's cancellation state.
Reset, replacement and detached evidence retain their existing ordering.

### modelScriptReplaceEffect

Replaces scripted decisions after resetting active work.

**Signature**

```ts
declare const modelScriptReplaceEffect: (
  state: Ref.Ref<ModelScriptOwnedState>,
  reset: Effect.Effect<void>,
  turns: readonly TestModelTurn[],
) => Effect.Effect<undefined, TypeError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-operations.ts#L35)

### modelScriptResetEffect

Cancels active requests and clears this model's script position/evidence.

**Signature**

```ts
declare const modelScriptResetEffect: (
  state: Ref.Ref<ModelScriptOwnedState>,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-operations.ts#L15)

### modelScriptTurnEffect

Executes a turn through the original observed native cancellation boundary.

**Signature**

```ts
declare const modelScriptTurnEffect: (
  state: Ref.Ref<ModelScriptOwnedState>,
  options: TestAgentModelOptions,
  request: TestAgentModelCall["request"],
  signal?: AbortSignal,
) => Effect.Effect<TestModelTurn, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model-operations.ts#L59)

## `agents-model.ts`

Constructs deterministic native test models from scripted steps and exposes their observed calls for invocation assertions.

### TestModelScript (class)

Stateful scripted turns and cancellation belong to one model owner.

**Signature**

```ts
declare class TestModelScript
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.ts#L66)

### createTestModel

Creates an isolated scripted native language model without network access.

**See**

- tests/fixtures/checked-examples.ts ownedHelpersExample for checked script ownership.

**Signature**

```ts
declare const createTestModel: (
  options?: TestAgentModelOptions & { readonly script?: readonly TestModelTurn[] },
) => RuntimeTestAgentModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.ts#L28)

### modelScriptLayer

Builds a network-free script service with cooperative native cancellation.

**Signature**

```ts
declare const modelScriptLayer: (
  options?: TestAgentModelOptions,
) => Layer.Layer<TestModelScript, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.ts#L75)

## `agents-model.types.ts`

Constructs deterministic native test models from scripted steps and exposes their observed calls for invocation assertions. This companion preserves the native input and output types without starting runtime work.

### ModelScriptOwnedState (interface)

Script index, detached evidence and cancellation owners for one model.

**Signature**

```ts
export interface ModelScriptOwnedState {
  turns: readonly TestModelTurn[];
  next: number;
  readonly calls: TestAgentModelCall[];
  readonly active: Set<AbortController>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.types.ts#L25)

### ModelScriptService (interface)

Effect script state, detached call capture and cancellable native turn decisions.

**Signature**

```ts
export interface ModelScriptService {
  readonly turn: (
    request: TestAgentModelCall["request"],
    signal?: AbortSignal,
  ) => Effect.Effect<TestModelTurn, unknown>;
  readonly script: (turns: readonly TestModelTurn[]) => Effect.Effect<void, unknown>;
  readonly reset: Effect.Effect<void>;
  readonly calls: Effect.Effect<readonly TestAgentModelCall[]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.types.ts#L9)

### RuntimeTestAgentModel (interface)

Native LangChain-compatible scripted model with owned release.

**Signature**

```ts
export interface RuntimeTestAgentModel extends TestAgentModel {
  readonly languageModel: BaseChatModel;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-model.types.ts#L20)

## `agents-types.ts`

Preserved compatibility entrypoint for the canonical domain type companion.

### "./agents.types.js" (namespace export)

Re-exports all named exports from the "./agents.types.js" module.

**Signature**

```ts
export * from "./agents.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-types.ts#L2)

## `agents-utils.ts`

Normalizes scripted native test values and observations for the agent harness without starting a separate execution owner.

### assertAgentTrace

Asserts selected native agent trace fields in their observed order.

**Signature**

```ts
declare const assertAgentTrace: (
  trace: TestAgentTraceSnapshot,
  expected: TestAgentTraceExpectation,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-utils.ts#L17)

### captureHooks

Records observed agent edges while forwarding the caller's native hooks.

**Signature**

```ts
declare const captureHooks: (
  hooks: AgentRuntimeHooks | undefined,
  edges: AgentObservedEdge[],
) => AgentRuntimeHooks;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-utils.ts#L83)

### createTrace

Creates isolated trace capture and the existing assertion facade.

**Signature**

```ts
declare const createTrace: (
  spans: ReturnType<typeof spanSnapshot>[],
  edges: AgentObservedEdge[],
) => TestAgentTrace;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents-utils.ts#L56)

## `agents.ts`

Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries.

### TestAgent

**Signature**

```ts
declare const TestAgent: TestAgent<Agent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L27)

### TestAgentApproval

**Signature**

```ts
declare const TestAgentApproval: TestAgentApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L28)

### TestAgentApprovalMode

**Signature**

```ts
declare const TestAgentApprovalMode: TestAgentApprovalMode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L29)

### TestAgentApprovals

**Signature**

```ts
declare const TestAgentApprovals: TestAgentApprovals;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L30)

### TestAgentDescriptor

**Signature**

```ts
declare const TestAgentDescriptor: TestAgentDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L31)

### TestAgentHarness (class)

Agent decisions, approval ownership and scripted invocation share one service.

**Signature**

```ts
declare class TestAgentHarness
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L46)

### TestAgentInvocationOptions

**Signature**

```ts
declare const TestAgentInvocationOptions: TestAgentInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L32)

### TestAgentModel

**Signature**

```ts
declare const TestAgentModel: TestAgentModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L33)

### TestAgentModelCall

**Signature**

```ts
declare const TestAgentModelCall: TestAgentModelCall;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L34)

### TestAgentModelOptions

**Signature**

```ts
declare const TestAgentModelOptions: TestAgentModelOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L35)

### TestAgentOptions

**Signature**

```ts
declare const TestAgentOptions: TestAgentOptions<Agent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L36)

### TestAgentTrace

**Signature**

```ts
declare const TestAgentTrace: TestAgentTrace;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L37)

### TestAgentTraceExpectation

**Signature**

```ts
declare const TestAgentTraceExpectation: TestAgentTraceExpectation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L38)

### TestAgentTraceSnapshot

**Signature**

```ts
declare const TestAgentTraceSnapshot: TestAgentTraceSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L39)

### TestModelTurn

**Signature**

```ts
declare const TestModelTurn: TestModelTurn;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L40)

### assertAgentTrace

**Signature**

```ts
declare const assertAgentTrace: (
  trace: TestAgentTraceSnapshot,
  expected: TestAgentTraceExpectation,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L42)

### createTestAgent

Creates isolated agent state with native model cancellation and owned approvals.

**Signature**

```ts
declare const createTestAgent: <Agent extends TestAgentDescriptor>(
  options: TestAgentOptions<Agent>,
) => TestAgent<Agent>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L101)

### createTestModel

**Signature**

```ts
declare const createTestModel: (
  options?: TestAgentModelOptions & { readonly script?: readonly TestModelTurn[] },
) => RuntimeTestAgentModel;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L43)

### testAgentLayer

Acquires the network-free harness behind the public synchronous factory.

**Signature**

```ts
declare const testAgentLayer: <Agent extends TestAgentDescriptor>(
  options: TestAgentOptions<Agent>,
) => Layer.Layer<TestAgentHarness, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.ts#L56)

## `agents.types.ts`

Publishes the native agent test harness helpers from the explicit integration while sharing RELKIT testing ownership and clock boundaries. This companion preserves the native input and output types without starting runtime work.

### TestAgent (interface)

Owned native agent facade preserving schema inference, approvals and trace evidence.

**Signature**

```ts
export interface TestAgent<Agent extends TestAgentDescriptor = TestAgentDescriptor> {
  readonly model: TestAgentModel;
  readonly failures: TestFailureControls;
  readonly approvals: TestAgentApprovals;
  readonly pending: () => readonly PendingApproval[];
  readonly trace: TestAgentTrace;
  readonly script: (turns: readonly TestModelTurn[]) => void;
  readonly invoke: (
    input: InferInput<Agent["input"]>,
    options?: TestAgentInvocationOptions,
  ) => Promise<InferOutput<Agent["output"]>>;
  readonly reset: () => void;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L127)

### TestAgentApproval (type alias)

Fixed, pending or caller-native approval decision authority.

**Signature**

```ts
type TestAgentApproval = TestAgentApprovalMode | AgentApprovalHandler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L25)

### TestAgentApprovalMode (type alias)

Fixed or pending native approval policy vocabulary.

**Signature**

```ts
type TestAgentApprovalMode = "approved" | "denied" | "pending";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L22)

### TestAgentApprovals (interface)

Synchronous selection controls over owned pending native decisions.

**Signature**

```ts
export interface TestAgentApprovals {
  readonly pending: () => readonly PendingApproval[];
  readonly approve: (toolCallId?: string) => void;
  readonly deny: (toolCallId?: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L117)

### TestAgentDescriptor (type alias)

Native agent descriptor vocabulary retained by public test inference.

**Signature**

```ts
type TestAgentDescriptor = AgentDescriptor<string, unknown, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L19)

### TestAgentInvocationOptions (type alias)

Invocation-only native overrides excluding owned model and engine dependencies.

**Signature**

```ts
type TestAgentInvocationOptions = Omit<AgentInvocationOptions, "input" | "approval" | "hooks">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L91)

### TestAgentModel (interface)

Public model facade owning script mutation, capture and release.

**Signature**

```ts
export interface TestAgentModel {
  readonly provider: string;
  readonly modelId: string;
  readonly calls: readonly TestAgentModelCall[];
  readonly script: (turns: readonly TestModelTurn[]) => void;
  readonly reset: () => void;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L60)

### TestAgentModelCall (interface)

Detached native request and scripted turn evidence captured in order.

**Signature**

```ts
export interface TestAgentModelCall {
  readonly index: number;
  readonly request: {
    readonly messages: readonly unknown[];
    readonly tools: readonly unknown[];
  };
  readonly turn: TestModelTurn;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L50)

### TestAgentModelOptions (interface)

Network-free model identity, hanging behavior and explicit logging policy.

**Signature**

```ts
export interface TestAgentModelOptions {
  readonly logger?: NonNullable<
    Parameters<typeof import("@relkit/testing/internal/testing-owner").testingLoggerLayer>[0]
  >;
  readonly provider?: string;
  readonly modelId?: string;
  readonly hang?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L40)

### TestAgentOptions (interface)

Native agent, tool engine, model script and capture dependencies.

**Signature**

```ts
export interface TestAgentOptions<Agent extends TestAgentDescriptor = TestAgentDescriptor> {
  readonly logger?: NonNullable<
    Parameters<typeof import("@relkit/testing/internal/testing-owner").testingLoggerLayer>[0]
  >;
  readonly agent: Agent;
  readonly tools: AgentRuntimeOptions["tools"];
  readonly engine: AgentRuntimeOptions["engine"];
  readonly script?: readonly TestModelTurn[];
  readonly model?: TestAgentModelOptions;
  readonly maxInputBytes?: number;
  readonly maxOutputBytes?: number;
  readonly approval?: TestAgentApproval;
  readonly failures?: TestFailureControls;
  readonly hooks?: AgentRuntimeHooks;
  readonly capture?: AgentCapturePolicy;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L73)

### TestAgentTrace (interface)

Owned trace evidence with explicit read, clear and assertion operations.

**Signature**

```ts
export interface TestAgentTrace extends TestAgentTraceSnapshot {
  readonly read: () => TestAgentTraceSnapshot;
  readonly clear: () => void;
  readonly assert: (expected: TestAgentTraceExpectation) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L103)

### TestAgentTraceExpectation (interface)

Selected span, outcome and tool-edge evidence checked by trace assertions.

**Signature**

```ts
export interface TestAgentTraceExpectation {
  readonly spanKinds?: readonly ReturnType<typeof spanSnapshot>["kind"][];
  readonly names?: readonly string[];
  readonly edges?: readonly AgentObservedEdge[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L110)

### TestAgentTraceSnapshot (interface)

Detached observed span and edge evidence for a test invocation.

**Signature**

```ts
export interface TestAgentTraceSnapshot {
  readonly spans: readonly ReturnType<typeof spanSnapshot>[];
  readonly edges: readonly AgentObservedEdge[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L97)

### TestModelTurn (type alias)

Scripted native model outcome supporting final values, tool calls and failures.

**Signature**

```ts
type TestModelTurn =
  | {
      readonly type: "tool-call";
      readonly callId: string;
      readonly toolId: string;
      readonly input: JsonValue;
    }
  | { readonly type: "final"; readonly output: JsonValue }
  | { readonly type: "error"; readonly code: string; readonly message: string }
  | { readonly type: "cancelled"; readonly reason?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/src/testing/agents.types.ts#L28)

---

# Local API
Source: https://relkit.dev/docs/api/integrations/local

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [localEvent](/docs/api/integrations/local#localevent)
- [localJob](/docs/api/integrations/local#localjob)

For configuration and examples, read [integrations](/docs/modules/integrations), [local providers](/docs/modules/integrations/local-providers).

## Public imports

- `@relkit/local` — 64 exports
- `@relkit/local/runtime` — 48 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                               | Kind  | Import from             | Example                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------- | ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [acquireLocalProjectLease](/docs/api/integrations/local#acquirelocalprojectlease)                                 | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [AcquireLocalProjectLeaseOptions](/docs/api/integrations/local#acquirelocalprojectleaseoptions-interface)         | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [assertLocalServicePlanVersion](/docs/api/integrations/local#assertlocalserviceplanversion)                       | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertlocalserviceplanversion)                                          |
| [assertLocalServicePlanVersionEffect](/docs/api/integrations/local#assertlocalserviceplanversioneffect)           | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertlocalserviceplanversioneffect)                                    |
| [assertLocalServiceStateVersion](/docs/api/integrations/local#assertlocalservicestateversion)                     | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertlocalservicestateversion)                                         |
| [assertLocalServiceStateVersionEffect](/docs/api/integrations/local#assertlocalservicestateversioneffect)         | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertlocalservicestateversioneffect)                                   |
| [assertProviderOverrideStateVersion](/docs/api/integrations/local#assertprovideroverridestateversion)             | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertprovideroverridestateversion)                                     |
| [assertProviderOverrideStateVersionEffect](/docs/api/integrations/local#assertprovideroverridestateversioneffect) | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#assertprovideroverridestateversioneffect)                               |
| [CompositeLocalServiceRecipe](/docs/api/integrations/local#compositelocalservicerecipe-interface)                 | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#compositelocalservicerecipe-interface)                                  |
| [CompositeLocalServiceUnit](/docs/api/integrations/local#compositelocalserviceunit-interface)                     | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#compositelocalserviceunit-interface)                                    |
| [CompositeLocalServiceUnitKind](/docs/api/integrations/local#compositelocalserviceunitkind-type-alias)            | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#compositelocalserviceunitkind-type-alias)                               |
| [CompositeLocalServiceUnitVolume](/docs/api/integrations/local#compositelocalserviceunitvolume-interface)         | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#compositelocalserviceunitvolume-interface)                              |
| [CompositeLocalServiceVolume](/docs/api/integrations/local#compositelocalservicevolume-interface)                 | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#compositelocalservicevolume-interface)                                  |
| [createLocalProjectIdentity](/docs/api/integrations/local#createlocalprojectidentity)                             | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L34) |
| [createLocalServiceReconciler](/docs/api/integrations/local#createlocalservicereconciler)                         | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L46) |
| [ensureLocalStateDirectory](/docs/api/integrations/local#ensurelocalstatedirectory)                               | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [groupServiceInstances](/docs/api/integrations/local#groupserviceinstances-1)                                     | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_PROJECT_LEASE_VERSION](/docs/api/integrations/local#local_project_lease_version)                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_RESOURCE_LABEL](/docs/api/integrations/local#local_resource_label)                                         | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_SERVICE_PLAN_FILE](/docs/api/integrations/local#local_service_plan_file)                                   | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_SERVICE_PLAN_VERSION](/docs/api/integrations/local#local_service_plan_version)                             | Value | `@relkit/local`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/version-cohort.test.ts#L32)           |
| [LOCAL_SERVICE_PROTOCOL_VERSION](/docs/api/integrations/local#local_service_protocol_version)                     | Value | `@relkit/local`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/services/recipe-cache.test.ts#L15) |
| [LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION](/docs/api/integrations/local#local_service_recipe_protocol_version)       | Value | `@relkit/local`         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/local-service/tests/recipe.test.ts#L10)      |
| [LOCAL_SERVICE_SECRETS_FILE](/docs/api/integrations/local#local_service_secrets_file)                             | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_SERVICE_STATE_FILE](/docs/api/integrations/local#local_service_state_file)                                 | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [LOCAL_SERVICE_STATE_VERSION](/docs/api/integrations/local#local_service_state_version)                           | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [localAgentState](/docs/api/integrations/local#localagentstate)                                                   | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [LocalAgentStateAdapter](/docs/api/integrations/local#localagentstateadapter-type-alias)                          | Type  | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [localEndpointHash](/docs/api/integrations/local#localendpointhash)                                               | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [localEvent](/docs/api/integrations/local#localevent)                                                             | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localevent)                                                             |
| [LocalEventAdapter](/docs/api/integrations/local#localeventadapter-type-alias)                                    | Type  | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [localJob](/docs/api/integrations/local#localjob)                                                                 | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localjob)                                                               |
| [LocalJobAdapter](/docs/api/integrations/local#localjobadapter-type-alias)                                        | Type  | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectIdentity](/docs/api/integrations/local#localprojectidentity-interface)                               | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [localProjectLabels](/docs/api/integrations/local#localprojectlabels)                                             | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L35) |
| [LocalProjectLease](/docs/api/integrations/local#localprojectlease-interface)                                     | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectLeaseError](/docs/api/integrations/local#localprojectleaseerror-class)                               | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectLeaseErrorCode](/docs/api/integrations/local#localprojectleaseerrorcode-type-alias)                  | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectLeaseHandle](/docs/api/integrations/local#localprojectleasehandle-interface)                         | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectLeaseMode](/docs/api/integrations/local#localprojectleasemode-type-alias)                            | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProjectLeaseStatus](/docs/api/integrations/local#localprojectleasestatus-type-alias)                        | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalProviderOptions](/docs/api/integrations/local#localprovideroptions-interface)                               | Type  | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [localRealtime](/docs/api/integrations/local#localrealtime)                                                       | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [LocalRealtimeAdapter](/docs/api/integrations/local#localrealtimeadapter-type-alias)                              | Type  | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [localResourceLabels](/docs/api/integrations/local#localresourcelabels)                                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [localResourceName](/docs/api/integrations/local#localresourcename)                                               | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L38) |
| [LocalServiceBindingState](/docs/api/integrations/local#localservicebindingstate-interface)                       | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicebindingstate-interface)                                     |
| [LocalServiceBindMount](/docs/api/integrations/local#localservicebindmount-interface)                             | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicebindmount-interface)                                        |
| [LocalServiceGeneratedSecret](/docs/api/integrations/local#localservicegeneratedsecret-interface)                 | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicegeneratedsecret-interface)                                  |
| [LocalServiceHealthCheck](/docs/api/integrations/local#localservicehealthcheck-interface)                         | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicehealthcheck-interface)                                      |
| [LocalServiceInstance](/docs/api/integrations/local#localserviceinstance-interface)                               | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceinstance-interface)                                         |
| [LocalServiceLiteralEnvironment](/docs/api/integrations/local#localserviceliteralenvironment-interface)           | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceliteralenvironment-interface)                               |
| [LocalServiceMaterializerMetadata](/docs/api/integrations/local#localservicematerializermetadata-interface)       | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicematerializermetadata-interface)                             |
| [LocalServiceMaterializerRuntime](/docs/api/integrations/local#localservicematerializerruntime-interface)         | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicematerializerruntime-interface)                              |
| [LocalServiceOperation](/docs/api/integrations/local#localserviceoperation-type-alias)                            | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceoperation-type-alias)                                       |
| [LocalServicePhase](/docs/api/integrations/local#localservicephase-type-alias)                                    | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicephase-type-alias)                                           |
| [LocalServicePlan](/docs/api/integrations/local#localserviceplan-interface)                                       | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceplan-interface)                                             |
| [LocalServicePlanEntry](/docs/api/integrations/local#localserviceplanentry-interface)                             | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceplanentry-interface)                                        |
| [LocalServiceRecipe](/docs/api/integrations/local#localservicerecipe-interface)                                   | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicerecipe-interface)                                           |
| [LocalServiceRecipeInput](/docs/api/integrations/local#localservicerecipeinput-type-alias)                        | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicerecipeinput-type-alias)                                     |
| [LocalServiceRecipeMap](/docs/api/integrations/local#localservicerecipemap-type-alias)                            | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceRecipeOutputContext](/docs/api/integrations/local#localservicerecipeoutputcontext-interface)         | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicerecipeoutputcontext-interface)                              |
| [LocalServiceReconciler](/docs/api/integrations/local#localservicereconciler-interface)                           | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceReconcileRequest](/docs/api/integrations/local#localservicereconcilerequest-interface)               | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceReconcileResult](/docs/api/integrations/local#localservicereconcileresult-interface)                 | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceReconcilerOptions](/docs/api/integrations/local#localservicereconcileroptions-interface)             | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceSecretBinding](/docs/api/integrations/local#localservicesecretbinding-interface)                     | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceSecretEnvironment](/docs/api/integrations/local#localservicesecretenvironment-interface)             | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicesecretenvironment-interface)                                |
| [LocalServiceSecretState](/docs/api/integrations/local#localservicesecretstate-interface)                         | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalServiceStartRequest](/docs/api/integrations/local#localservicestartrequest-interface)                       | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicestartrequest-interface)                                     |
| [LocalServiceState](/docs/api/integrations/local#localservicestate-interface)                                     | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicestate-interface)                                            |
| [LocalServiceTelemetry](/docs/api/integrations/local#localservicetelemetry-class)                                 | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicetelemetry-class)                                            |
| [LocalServiceTelemetryLive](/docs/api/integrations/local#localservicetelemetrylive)                               | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicetelemetrylive)                                              |
| [LocalServiceTelemetryService](/docs/api/integrations/local#localservicetelemetryservice-interface)               | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicetelemetryservice-interface)                                 |
| [LocalServiceValidationFailure](/docs/api/integrations/local#localservicevalidationfailure-class)                 | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicevalidationfailure-class)                                    |
| [LocalServiceVersionError](/docs/api/integrations/local#localserviceversionerror-class)                           | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceversionerror-class)                                         |
| [LocalServiceVersionErrorCode](/docs/api/integrations/local#localserviceversionerrorcode-type-alias)              | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceversionerrorcode-type-alias)                                |
| [LocalServiceVersionFailure](/docs/api/integrations/local#localserviceversionfailure-class)                       | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceversionfailure-class)                                       |
| [LocalServiceVolume](/docs/api/integrations/local#localservicevolume-interface)                                   | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localservicevolume-interface)                                           |
| [LocalServiceWorkerArtifact](/docs/api/integrations/local#localserviceworkerartifact-interface)                   | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#localserviceworkerartifact-interface)                                   |
| [localStateDirectory](/docs/api/integrations/local#localstatedirectory)                                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalStateError](/docs/api/integrations/local#localstateerror-class)                                             | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [LocalStateFileName](/docs/api/integrations/local#localstatefilename-type-alias)                                  | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [NormalizedLocalServiceRecipe](/docs/api/integrations/local#normalizedlocalservicerecipe-interface)               | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#normalizedlocalservicerecipe-interface)                                 |
| [NormalizedLocalServiceUnit](/docs/api/integrations/local#normalizedlocalserviceunit-interface)                   | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#normalizedlocalserviceunit-interface)                                   |
| [normalizeLocalServiceRecipe](/docs/api/integrations/local#normalizelocalservicerecipe)                           | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#normalizelocalservicerecipe)                                            |
| [normalizeLocalServiceRecipeEffect](/docs/api/integrations/local#normalizelocalservicerecipeeffect)               | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#normalizelocalservicerecipeeffect)                                      |
| [PROVIDER_OVERRIDE_STATE_FILE](/docs/api/integrations/local#provider_override_state_file)                         | Value | `@relkit/local`         | [Module example](/docs/modules/integrations)                                                                       |
| [PROVIDER_OVERRIDE_STATE_VERSION](/docs/api/integrations/local#provider_override_state_version)                   | Value | `@relkit/local`         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/version-cohort.test.ts#L33)           |
| [ProviderOverrideBinding](/docs/api/integrations/local#provideroverridebinding-interface)                         | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#provideroverridebinding-interface)                                      |
| [providerOverrideBindingValues](/docs/api/integrations/local#provideroverridebindingvalues)                       | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#provideroverridebindingvalues)                                          |
| [providerOverrideBindingValuesEffect](/docs/api/integrations/local#provideroverridebindingvalueseffect)           | Value | `@relkit/local`         | [API example](/docs/api/integrations/local#provideroverridebindingvalueseffect)                                    |
| [ProviderOverrideError](/docs/api/integrations/local#provideroverrideerror-class)                                 | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [ProviderOverrideExpectation](/docs/api/integrations/local#provideroverrideexpectation-interface)                 | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#provideroverrideexpectation-interface)                                  |
| [ProviderOverrideState](/docs/api/integrations/local#provideroverridestate-interface)                             | Type  | `@relkit/local`         | [API example](/docs/api/integrations/local#provideroverridestate-interface)                                        |
| [ProviderOverrideSummary](/docs/api/integrations/local#provideroverridesummary-interface)                         | Type  | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [readLocalProjectLease](/docs/api/integrations/local#readlocalprojectlease)                                       | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [readLocalServiceSecrets](/docs/api/integrations/local#readlocalservicesecrets)                                   | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L77) |
| [readLocalServiceState](/docs/api/integrations/local#readlocalservicestate)                                       | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L133) |
| [readLocalStateText](/docs/api/integrations/local#readlocalstatetext)                                             | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [readProviderOverrides](/docs/api/integrations/local#readprovideroverrides)                                       | Value | `@relkit/local/runtime` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-composite.test.ts#L68) |
| [removeLocalServiceState](/docs/api/integrations/local#removelocalservicestate)                                   | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [removeLocalStateFile](/docs/api/integrations/local#removelocalstatefile)                                         | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [removeProviderOverrides](/docs/api/integrations/local#removeprovideroverrides)                                   | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [runtimeIntegration](/docs/api/integrations/local#runtimeintegration)                                             | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [serviceInstanceIds](/docs/api/integrations/local#serviceinstanceids-1)                                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [summarizeProviderOverrides](/docs/api/integrations/local#summarizeprovideroverrides)                             | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [upsertLocalServiceSecrets](/docs/api/integrations/local#upsertlocalservicesecrets)                               | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [withLocalStateTemporaryFile](/docs/api/integrations/local#withlocalstatetemporaryfile)                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [writeLocalServiceState](/docs/api/integrations/local#writelocalservicestate)                                     | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [writeLocalStateText](/docs/api/integrations/local#writelocalstatetext)                                           | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |
| [writeProviderOverrides](/docs/api/integrations/local#writeprovideroverrides)                                     | Value | `@relkit/local/runtime` | [Module example](/docs/modules/integrations)                                                                       |

## `index.ts`

### "./providers.js" (namespace export)

Re-exports all named exports from the "./providers.js" module.

**Signature**

```ts
export * from "./providers.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/index.ts#L2)

### "@relkit/local-service" (namespace export)

Re-exports all named exports from the "@relkit/local-service" module.

**Signature**

```ts
export * from "@relkit/local-service";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/index.ts#L1)

## `providers.ts`

### localEvent

Defines the durable filesystem event provider used by local development.

**Example**

```ts
import { localEvent } from "@relkit/local";
const events = localEvent();
```

**Signature**

```ts
declare const localEvent: (options?: LocalProviderOptions) => LocalEventAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L42)

Since v0.4.0

### localJob

Defines the durable filesystem queue provider for unscheduled local jobs.

**Example**

```ts
import { localJob } from "@relkit/local";
const jobs = localJob();
```

**Signature**

```ts
declare const localJob: (options?: LocalProviderOptions) => LocalJobAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L57)

Since v0.4.0

### LocalAgentStateAdapter (type alias)

**Signature**

```ts
type LocalAgentStateAdapter = ProviderAdapter<typeof agentState, "local-agent-state">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L29)

### LocalEventAdapter (type alias)

**Signature**

```ts
type LocalEventAdapter = ProviderAdapter<typeof event, "local-event">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L26)

### LocalJobAdapter (type alias)

**Signature**

```ts
type LocalJobAdapter = ProviderAdapter<typeof job, "local-job">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L27)

### LocalProviderOptions (interface)

**Signature**

```ts
export interface LocalProviderOptions {
  readonly root?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L22)

### LocalRealtimeAdapter (type alias)

**Signature**

```ts
type LocalRealtimeAdapter = ProviderAdapter<typeof realtime, "local-realtime">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L28)

### localAgentState

**Signature**

```ts
declare const localAgentState: (options?: LocalProviderOptions) => LocalAgentStateAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L65)

### localRealtime

**Signature**

```ts
declare const localRealtime: (options?: LocalProviderOptions) => LocalRealtimeAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/providers.ts#L61)

## `identity.ts`

### LOCAL_RESOURCE_LABEL

**Signature**

```ts
declare const LOCAL_RESOURCE_LABEL: Readonly<{
  readonly managed: "dev.relkit.managed";
  readonly applicationId: "dev.relkit.application-id";
  readonly localProjectId: "dev.relkit.local-project-id";
  readonly bindingId: "dev.relkit.binding-id";
  readonly environment: "dev.relkit.environment";
  readonly serviceGeneration: "dev.relkit.service-generation";
  readonly unitId: "dev.relkit.unit-id";
  readonly unitKind: "dev.relkit.unit-kind";
  readonly recipeId: "dev.relkit.recipe-id";
  readonly planHash: "dev.relkit.plan-hash";
  readonly endpointHash: "dev.relkit.endpoint-hash";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L5)

### LocalProjectIdentity (interface)

**Signature**

```ts
export interface LocalProjectIdentity {
  readonly applicationId: string;
  readonly projectRoot: string;
  readonly localProjectId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L19)

### createLocalProjectIdentity

**Signature**

```ts
declare const createLocalProjectIdentity: (
  requestedRoot: string,
  applicationId: string,
) => LocalProjectIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L38)

### localEndpointHash

**Signature**

```ts
declare const localEndpointHash: (
  endpoints: Readonly<Record<string, string>> | undefined,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L105)

### localProjectLabels

**Signature**

```ts
declare const localProjectLabels: (
  identity: LocalProjectIdentity,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L58)

### localResourceLabels

**Signature**

```ts
declare const localResourceLabels: (
  identity: LocalProjectIdentity,
  resource: LocalResourceIdentity,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L69)

### localResourceName

**Signature**

```ts
declare const localResourceName: (
  identity: LocalProjectIdentity,
  bindingId: string,
  suffix?: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/identity.ts#L113)

## `index.ts`

### "./identity.js" (namespace export)

Re-exports all named exports from the "./identity.js" module.

**Signature**

```ts
export * from "./identity.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L1)

### "./integration.js" (namespace export)

Re-exports all named exports from the "./integration.js" module.

**Signature**

```ts
export * from "./integration.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L2)

### "./lease.js" (namespace export)

Re-exports all named exports from the "./lease.js" module.

**Signature**

```ts
export * from "./lease.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L3)

### "./local-secrets.js" (namespace export)

Re-exports all named exports from the "./local-secrets.js" module.

**Signature**

```ts
export * from "./local-secrets.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L4)

### "./provider-overrides.js" (namespace export)

Re-exports all named exports from the "./provider-overrides.js" module.

**Signature**

```ts
export * from "./provider-overrides.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L5)

### "./reconciler.js" (namespace export)

Re-exports all named exports from the "./reconciler.js" module.

**Signature**

```ts
export * from "./reconciler.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L6)

### "./service-state.js" (namespace export)

Re-exports all named exports from the "./service-state.js" module.

**Signature**

```ts
export * from "./service-state.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L8)

### "./state-paths.js" (namespace export)

Re-exports all named exports from the "./state-paths.js" module.

**Signature**

```ts
export * from "./state-paths.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L9)

### groupServiceInstances

**Signature**

```ts
declare const groupServiceInstances: (
  instances: readonly LocalServiceInstance[],
) => readonly LocalServiceInstance[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L7)

### serviceInstanceIds

**Signature**

```ts
declare const serviceInstanceIds: (instance: LocalServiceInstance) => readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/index.ts#L7)

## `integration.ts`

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: RuntimeProviderIntegration<"local">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/integration.ts#L10)

## `lease-files.ts`

### LeasePaths (interface)

**Signature**

```ts
export interface LeasePaths {
  readonly directory: string;
  readonly lock: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L25)

### ensureLeaseDirectory

**Signature**

```ts
declare const ensureLeaseDirectory: (identity: LocalProjectIdentity) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L35)

### leasePaths

**Signature**

```ts
declare const leasePaths: (identity: LocalProjectIdentity) => LeasePaths;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L30)

### readLease

**Signature**

```ts
declare const readLease: (identity: LocalProjectIdentity) => LocalProjectLease | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L39)

### withLeaseLock

**Signature**

```ts
declare const withLeaseLock: <Value>(
  identity: LocalProjectIdentity,
  paths: LeasePaths,
  isProcessAlive: (pid: number) => boolean,
  operation: () => Value,
) => Value;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L68)

### writeLease

**Signature**

```ts
declare const writeLease: (identity: LocalProjectIdentity, lease: LocalProjectLease) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-files.ts#L64)

## `lease-types.ts`

### AcquireLocalProjectLeaseOptions (interface)

**Signature**

```ts
export interface AcquireLocalProjectLeaseOptions {
  readonly mode: LocalProjectLeaseMode;
  readonly sessionId: string;
  readonly pid?: number;
  readonly now?: () => Date;
  readonly isProcessAlive?: (pid: number) => boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L16)

### LOCAL_PROJECT_LEASE_VERSION

**Signature**

```ts
declare const LOCAL_PROJECT_LEASE_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L1)

### LocalProjectLease (interface)

**Signature**

```ts
export interface LocalProjectLease {
  readonly version: typeof LOCAL_PROJECT_LEASE_VERSION;
  readonly localProjectId: string;
  readonly mode: LocalProjectLeaseMode;
  readonly sessionId: string;
  readonly generationId: string;
  readonly createdAt: string;
  readonly ownerPid?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L6)

### LocalProjectLeaseError (class)

**Signature**

```ts
declare class LocalProjectLeaseError { constructor(
    readonly code: LocalProjectLeaseErrorCode,
    message: string,
    readonly owner?: LocalProjectLease,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L33)

### LocalProjectLeaseErrorCode (type alias)

**Signature**

```ts
type LocalProjectLeaseErrorCode =
  "RELKIT_LOCAL_LEASE_HELD" | "RELKIT_LOCAL_LEASE_BUSY" | "RELKIT_LOCAL_LEASE_INVALID";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L30)

### LocalProjectLeaseHandle (interface)

**Signature**

```ts
export interface LocalProjectLeaseHandle {
  readonly lease: LocalProjectLease;
  readonly status: LocalProjectLeaseStatus;
  readonly release: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L24)

### LocalProjectLeaseMode (type alias)

**Signature**

```ts
type LocalProjectLeaseMode = "attached" | "detached";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L3)

### LocalProjectLeaseStatus (type alias)

**Signature**

```ts
type LocalProjectLeaseStatus = "acquired" | "adopted" | "recovered";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease-types.ts#L4)

## `lease.ts`

### "./lease-types.js" (namespace export)

Re-exports all named exports from the "./lease-types.js" module.

**Signature**

```ts
export * from "./lease-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease.ts#L21)

### acquireLocalProjectLease

**Signature**

```ts
declare const acquireLocalProjectLease: (
  identity: LocalProjectIdentity,
  options: AcquireLocalProjectLeaseOptions,
) => LocalProjectLeaseHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease.ts#L23)

### readLocalProjectLease

**Signature**

```ts
declare const readLocalProjectLease: (
  identity: LocalProjectIdentity,
) => LocalProjectLease | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/lease.ts#L64)

## `local-secrets.ts`

### LOCAL_SERVICE_SECRETS_FILE

**Signature**

```ts
declare const LOCAL_SERVICE_SECRETS_FILE: "local-secrets.json";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/local-secrets.ts#L5)

### LocalServiceSecretBinding (interface)

**Signature**

```ts
export interface LocalServiceSecretBinding {
  readonly bindingId: string;
  readonly recipe: Readonly<{
    readonly integrationId: string;
    readonly recipeId: string;
    readonly recipeVersion: number;
  }>;
  readonly values: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/local-secrets.ts#L8)

### LocalServiceSecretState (interface)

**Signature**

```ts
export interface LocalServiceSecretState {
  readonly version: typeof LOCAL_SERVICE_SECRETS_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly bindings: readonly LocalServiceSecretBinding[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/local-secrets.ts#L18)

### readLocalServiceSecrets

**Signature**

```ts
declare const readLocalServiceSecrets: (
  identity: LocalProjectIdentity,
) => LocalServiceSecretState | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/local-secrets.ts#L25)

### upsertLocalServiceSecrets

**Signature**

```ts
declare const upsertLocalServiceSecrets: (
  identity: LocalProjectIdentity,
  current: LocalServiceSecretState | undefined,
  bindingId: string,
  recipe: LocalServiceSecretBinding["recipe"],
  values: Readonly<Record<string, string>>,
) => LocalServiceSecretState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/local-secrets.ts#L50)

## `provider-overrides.ts`

### ProviderOverrideError (class)

**Signature**

```ts
declare class ProviderOverrideError { constructor(readonly code: "RELKIT_LOCAL_OVERRIDE_INVALID" | "RELKIT_LOCAL_OVERRIDE_STALE") }
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L18)

### ProviderOverrideSummary (interface)

**Signature**

```ts
export interface ProviderOverrideSummary {
  readonly generationId: string;
  readonly planHash: string;
  readonly bindingIds: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L12)

### readProviderOverrides

**Signature**

```ts
declare const readProviderOverrides: (
  identity: LocalProjectIdentity,
  expectedPlanHash?: string,
) => ProviderOverrideState | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L48)

### removeProviderOverrides

**Signature**

```ts
declare const removeProviderOverrides: (identity: LocalProjectIdentity) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L80)

### summarizeProviderOverrides

**Signature**

```ts
declare const summarizeProviderOverrides: (state: ProviderOverrideState) => ProviderOverrideSummary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L76)

### writeProviderOverrides

**Signature**

```ts
declare const writeProviderOverrides: (
  identity: LocalProjectIdentity,
  planHash: string,
  bindings: readonly ProviderOverrideBinding[],
) => ProviderOverrideSummary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/provider-overrides.ts#L29)

## `reconciler-environment.ts`

### environmentFile

**Signature**

```ts
declare const environmentFile: (
  recipe: LocalServiceRecipeInput,
  secrets: Readonly<Record<string, string>>,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-environment.ts#L3)

### environmentFiles

**Signature**

```ts
declare const environmentFiles: (
  recipe: LocalServiceRecipeInput,
  secrets: Readonly<Record<string, string>>,
) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-environment.ts#L22)

## `reconciler-generation.ts`

### assertHotSwapSafe

Refuses an unsafe source-generation swap while an older service is owned.

**Signature**

```ts
declare const assertHotSwapSafe: (
  bindingId: string,
  instances: readonly LocalServiceInstance[],
  environment: string | undefined,
  serviceGeneration: string | undefined,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-generation.ts#L5)

## `reconciler-lifecycle.ts`

### aborted

**Signature**

```ts
declare const aborted: (signal: AbortSignal | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-lifecycle.ts#L140)

### frozenResult

**Signature**

```ts
declare const frozenResult: (
  overrides: ProviderOverrideSummary,
  state: LocalServiceState,
  reused: readonly string[],
  started: readonly string[],
  removed: readonly string[],
) => LocalServiceReconcileResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-lifecycle.ts#L144)

### startService

**Signature**

```ts
declare const startService: (
  options: LocalServiceReconcilerOptions,
  entry: LocalServicePlanEntry,
  recipe: LocalServiceRecipeInput,
  labels: Readonly<Record<string, string>>,
  secrets: Readonly<Record<string, string>>,
  signal?: AbortSignal,
  environmentVariables?: Readonly<Record<string, string>>,
  workerArtifact?: LocalServiceWorkerArtifact,
  environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>,
  portBindings?: Readonly<Record<string, Readonly<Record<string, number>>>>,
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-lifecycle.ts#L21)

### writeFailureState

**Signature**

```ts
declare const writeFailureState: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  active: LocalServicePlanEntry | undefined,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-lifecycle.ts#L117)

## `reconciler-operation-finalize.ts`

### finalizeReconcile

**Signature**

```ts
declare const finalizeReconcile: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  desired: readonly LocalServicePlanEntry[],
  previous: ProviderOverrideState | undefined,
  next: Map<string, TrackedService>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  bindings: { bindingId: string; values: Readonly<Record<string, JsonValue>> }[],
  reused: string[],
  started: string[],
  removed: string[],
) => Promise<LocalServiceReconcileResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation-finalize.ts#L14)

## `reconciler-operation-run.ts`

### runReconcileOperation

**Signature**

```ts
declare const runReconcileOperation: (
  options: LocalServiceReconcilerOptions,
  projectLabels: Readonly<Record<string, string>>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  isClosed: () => boolean,
  request: LocalServiceReconcileRequest,
) => Promise<LocalServiceReconcileResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation-run.ts#L34)

## `reconciler-operation-service.ts`

### ensureServiceInstance

**Signature**

```ts
declare const ensureServiceInstance: (
  options: LocalServiceReconcilerOptions,
  request: LocalServiceReconcileRequest,
  entry: LocalServicePlanEntry,
  recipe: LocalServiceRecipeInput,
  labels: Readonly<Record<string, string>>,
  secrets: Readonly<Record<string, string>>,
  candidates: readonly LocalServiceInstance[],
  existing: LocalServiceInstance | undefined,
  keepCandidates: boolean,
  startedIds: string[],
  started: string[],
  reused: string[],
  removed: string[],
) => Promise<LocalServiceInstance>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation-service.ts#L36)

### keepServiceCandidates

**Signature**

```ts
declare const keepServiceCandidates: (
  recipe: NormalizedLocalServiceRecipe,
  candidates: readonly LocalServiceInstance[],
  request: LocalServiceReconcileRequest,
  bindingId: string,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation-service.ts#L17)

## `reconciler-operation.ts`

### TrackedService (interface)

**Signature**

```ts
export interface TrackedService {
  readonly instance: LocalServiceInstance;
  readonly signature: string;
  readonly secrets: Readonly<Record<string, string>>;
  readonly owned: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation.ts#L8)

### createReconcileOperation

**Signature**

```ts
declare const createReconcileOperation: (
  options: LocalServiceReconcilerOptions,
  projectLabels: Readonly<Record<string, string>>,
  tracked: Map<string, TrackedService>,
  signatures: Map<string, string>,
  isClosed: () => boolean,
) => (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-operation.ts#L15)

## `reconciler-queue.ts`

### ReconcileQueue (interface)

**Signature**

```ts
export interface ReconcileQueue {
  readonly enqueue: (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>;
  readonly wait: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-queue.ts#L6)

### createReconcileQueue

**Signature**

```ts
declare const createReconcileQueue: (
  reconcile: (request: LocalServiceReconcileRequest) => Promise<LocalServiceReconcileResult>,
) => ReconcileQueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-queue.ts#L11)

## `reconciler-resource.ts`

### removeInstance

**Signature**

```ts
declare const removeInstance: (
  options: LocalServiceReconcilerOptions,
  instance: LocalServiceInstance,
  signal?: AbortSignal,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-resource.ts#L5)

## `reconciler-support-validation.ts`

### completeUnits

**Signature**

```ts
declare const completeUnits: (
  instance: LocalServiceInstance,
  expectedUnitIds: readonly string[],
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support-validation.ts#L4)

### hash

**Signature**

```ts
declare const hash: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support-validation.ts#L29)

### invalid

**Signature**

```ts
declare const invalid: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support-validation.ts#L33)

### sameBindings

**Signature**

```ts
declare const sameBindings: (
  previous: ProviderOverrideState | undefined,
  planHash: string,
  bindings: readonly {
    readonly bindingId: string;
    readonly values: Readonly<Record<string, JsonValue>>;
  }[],
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support-validation.ts#L16)

## `reconciler-support.ts`

### compatible

**Signature**

```ts
declare const compatible: (
  instance: LocalServiceInstance,
  expectedRecipe: string,
  planHash: string,
  priorSignature: string | undefined,
  signature: string,
  environment?: string,
  serviceGeneration?: string,
  expectedUnitIds?: readonly string[],
  endpointHash?: string,
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L176)

### createSecrets

**Signature**

```ts
declare const createSecrets: (recipe: LocalServiceRecipeInput) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L82)

### desiredServices

**Signature**

```ts
declare const desiredServices: (
  request: LocalServiceReconcileRequest,
) => readonly LocalServicePlanEntry[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L18)

### generatedSecrets

**Signature**

```ts
declare const generatedSecrets: (
  recipe: LocalServiceRecipeInput,
  previous: ProviderOverrideState | undefined,
  bindingId: string,
  retained?: Readonly<Record<string, string>>,
  persisted?: Readonly<Record<string, string>>,
) => Readonly<Record<string, string>> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L63)

### groupServiceInstances

**Signature**

```ts
declare const groupServiceInstances: (
  instances: readonly LocalServiceInstance[],
) => readonly LocalServiceInstance[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L124)

### outputPorts

**Signature**

```ts
declare const outputPorts: (
  recipe: LocalServiceRecipeInput,
  instance: LocalServiceInstance,
) => Readonly<Record<string, number>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L95)

### recipeFor

**Signature**

```ts
declare const recipeFor: (
  entry: LocalServicePlanEntry,
  recipes: Readonly<Record<string, LocalServiceRecipeInput>>,
  materializerId: string,
) => LocalServiceRecipeInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L34)

### sameBindings

**Signature**

```ts
declare const sameBindings: (
  previous: ProviderOverrideState | undefined,
  planHash: string,
  bindings: readonly {
    readonly bindingId: string;
    readonly values: Readonly<Record<string, JsonValue>>;
  }[],
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L16)

### serviceInstanceIds

**Signature**

```ts
declare const serviceInstanceIds: (instance: LocalServiceInstance) => readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L168)

### serviceSignature

**Signature**

```ts
declare const serviceSignature: (entry: LocalServicePlanEntry) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-support.ts#L55)

## `reconciler-types.ts`

### LocalServiceRecipeMap (type alias)

**Signature**

```ts
type LocalServiceRecipeMap = Readonly<Record<string, LocalServiceRecipeInput>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-types.ts#L11)

### LocalServiceReconcileRequest (interface)

**Signature**

```ts
export interface LocalServiceReconcileRequest {
  readonly plan: LocalServicePlan;
  readonly planHash: string;
  readonly recipes: LocalServiceRecipeMap;
  readonly scope: "required" | "all";
  readonly environment?: string;
  readonly serviceGeneration?: string;
  readonly serviceGenerations?: Readonly<Record<string, string>>;
  readonly endpoints?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly environmentOverrides?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly environmentOverridesByUnit?: Readonly<
    Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>
  >;
  readonly workerArtifacts?: Readonly<Record<string, LocalServiceWorkerArtifact>>;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-types.ts#L13)

### LocalServiceReconcileResult (interface)

**Signature**

```ts
export interface LocalServiceReconcileResult {
  readonly overrides: ProviderOverrideSummary;
  readonly state: LocalServiceState;
  readonly reused: readonly string[];
  readonly started: readonly string[];
  readonly removed: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-types.ts#L30)

### LocalServiceReconciler (interface)

**Signature**

```ts
export interface LocalServiceReconciler {
  readonly reconcile: (
    request: LocalServiceReconcileRequest,
  ) => Promise<LocalServiceReconcileResult>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-types.ts#L44)

### LocalServiceReconcilerOptions (interface)

**Signature**

```ts
export interface LocalServiceReconcilerOptions {
  readonly identity: LocalProjectIdentity;
  readonly materializer: LocalServiceMaterializerRuntime;
  readonly preserveOnClose?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-types.ts#L38)

## `reconciler-worker.ts`

### WorkerStartOptions (interface)

**Signature**

```ts
export interface WorkerStartOptions {
  readonly bindMounts?: Readonly<Record<string, readonly LocalServiceBindMount[]>>;
  readonly environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-worker.ts#L8)

### workerStartOptions

**Signature**

```ts
declare const workerStartOptions: (
  recipe: NormalizedLocalServiceRecipe,
  artifact: LocalServiceWorkerArtifact | undefined,
) => WorkerStartOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler-worker.ts#L13)

## `reconciler.ts`

### "./reconciler-types.js" (namespace export)

Re-exports all named exports from the "./reconciler-types.js" module.

**Signature**

```ts
export * from "./reconciler-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler.ts#L9)

### createLocalServiceReconciler

**Signature**

```ts
declare const createLocalServiceReconciler: (
  options: LocalServiceReconcilerOptions,
) => LocalServiceReconciler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/reconciler.ts#L11)

## `service-state.ts`

### readLocalServiceState

**Signature**

```ts
declare const readLocalServiceState: (
  identity: LocalProjectIdentity,
) => LocalServiceState | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/service-state.ts#L28)

### removeLocalServiceState

**Signature**

```ts
declare const removeLocalServiceState: (identity: LocalProjectIdentity) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/service-state.ts#L55)

### writeLocalServiceState

**Signature**

```ts
declare const writeLocalServiceState: (
  identity: LocalProjectIdentity,
  planHash: string,
  services: readonly LocalServiceBindingState[],
) => LocalServiceState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/service-state.ts#L11)

## `state-paths.ts`

### LocalStateError (class)

**Signature**

```ts
declare class LocalStateError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L26)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_LOCAL_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L27)

### LocalStateFileName (type alias)

**Signature**

```ts
type LocalStateFileName =
  | "lease.json"
  | "local-services.state.json"
  | "provider-overrides.json"
  | "worker-provider-overrides.json"
  | "local-secrets.json";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L19)

### ensureLocalStateDirectory

**Signature**

```ts
declare const ensureLocalStateDirectory: (identity: LocalProjectIdentity) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L48)

### localStateDirectory

**Signature**

```ts
declare const localStateDirectory: (identity: LocalProjectIdentity) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L35)

### readLocalStateText

**Signature**

```ts
declare const readLocalStateText: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L58)

### removeLocalStateFile

**Signature**

```ts
declare const removeLocalStateFile: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L100)

### withLocalStateTemporaryFile

**Signature**

```ts
declare const withLocalStateTemporaryFile: <Value>(
  identity: LocalProjectIdentity,
  value: string,
  operation: (path: string) => Promise<Value>,
) => Promise<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L113)

### writeLocalStateText

**Signature**

```ts
declare const writeLocalStateText: (
  identity: LocalProjectIdentity,
  name: LocalStateFileName,
  value: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/local/src/runtime/state-paths.ts#L72)

## `local-service-errors.ts`

### LocalServiceValidationFailure (class)

Expected validation failure in a local-service Effect operation.

**Example**

```ts
Effect.catchTag("LocalServiceValidationFailure", ({ message }) => Effect.logWarning(message));
```

**Signature**

```ts
declare class LocalServiceValidationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-errors.ts#L7)

### LocalServiceVersionError (class)

Legacy synchronous error for a stale local-service artifact.

**Example**

```ts
throw new LocalServiceVersionError(
  "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED",
  "Local-service plan",
  0,
  1,
  "relkit check",
);
```

**Signature**

```ts
declare class LocalServiceVersionError { constructor(
    readonly code: LocalServiceVersionErrorCode,
    label: string,
    version: unknown,
    expected: number,
    command: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-errors.ts#L33)

### LocalServiceVersionFailure (class)

Expected unsupported artifact version in a local-service Effect operation.

**Example**

```ts
Effect.catchTag("LocalServiceVersionFailure", ({ code }) => Effect.logWarning(code));
```

**Signature**

```ts
declare class LocalServiceVersionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-errors.ts#L15)

## `local-service-observability.ts`

### LocalServiceTelemetry (class)

Substitutable telemetry service for local-service operations.

**Example**

```ts
Effect.provide(normalizeLocalServiceRecipeEffect(recipe), LocalServiceTelemetryLive);
```

**Signature**

```ts
declare class LocalServiceTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.ts#L15)

### LocalServiceTelemetryLive

Live operation spans and metrics.

**Example**

```ts
Effect.runSync(
  Effect.provide(normalizeLocalServiceRecipeEffect(recipe), LocalServiceTelemetryLive),
);
```

**Signature**

```ts
declare const LocalServiceTelemetryLive: Layer.Layer<LocalServiceTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.ts#L23)

### observeLocalService

Observe one public operation using an injected or live telemetry service.

**Example**

```ts
observeLocalService("recipe.normalize", Effect.succeed(recipe));
```

**Signature**

```ts
declare const observeLocalService: <A, E, R>(
  operation: LocalServiceOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.ts#L39)

### runLocalService

Run a synchronous compatibility adapter and restore legacy errors.

**Throws**

TypeError or LocalServiceVersionError for expected failures; defects propagate.

**Example**

```ts
runLocalService(Effect.succeed("ready"));
```

**Signature**

```ts
declare const runLocalService: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.ts#L78)

## `local-service-observability.types.ts`

### LocalServiceOperation (type alias)

Fixed operation names keep metric dimensions bounded.

**Example**

```ts
const operation: LocalServiceOperation = "recipe.normalize";
```

**Signature**

```ts
type LocalServiceOperation =
  | "recipe.normalize"
  | "plan.assert-version"
  | "state.assert-version"
  | "override.assert-version"
  | "override.binding-values";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.types.ts#L6)

### LocalServiceTelemetryService (interface)

Injectable tracing and metric behavior for public operations.

**Example**

```ts
const telemetry: LocalServiceTelemetryService = { observe: (_operation, effect) => effect };
```

**Signature**

```ts
export interface LocalServiceTelemetryService {
  /** Observe an operation without changing its result.
   * @param operation - Fixed operation name.
   * @param effect - Operation to measure.
   * @returns The original Effect success and failure channels.
   * @example telemetry.observe("recipe.normalize", Effect.succeed(recipe));
   */
  readonly observe: <A, E, R>(
    operation: LocalServiceOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/local-service-observability.types.ts#L16)

## `protocol-version.ts`

### assertLocalServicePlanVersion

Assert a local-service plan version synchronously.

**Throws**

LocalServiceVersionError when the version differs.

**Example**

```ts
assertLocalServicePlanVersion({ version: 1 });
```

**Signature**

```ts
declare const assertLocalServicePlanVersion: (value: unknown) => asserts value is LocalServicePlan;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L108)

### assertLocalServicePlanVersionEffect

Check a local-service plan version in the Effect error channel.

**Example**

```ts
Effect.runSync(assertLocalServicePlanVersionEffect({ version: 1 }));
```

**Signature**

```ts
declare const assertLocalServicePlanVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L47)

### assertLocalServiceStateVersion

Assert a local-service state version synchronously.

**Throws**

LocalServiceVersionError when the version differs.

**Example**

```ts
assertLocalServiceStateVersion({ version: 1 });
```

**Signature**

```ts
declare const assertLocalServiceStateVersion: (
  value: unknown,
) => asserts value is LocalServiceState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L118)

### assertLocalServiceStateVersionEffect

Check a local-service state version in the Effect error channel.

**Example**

```ts
Effect.runSync(assertLocalServiceStateVersionEffect({ version: 1 }));
```

**Signature**

```ts
declare const assertLocalServiceStateVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L67)

### assertProviderOverrideStateVersion

Assert a provider override version synchronously.

**Throws**

LocalServiceVersionError when the version differs.

**Example**

```ts
assertProviderOverrideStateVersion({ version: 1 });
```

**Signature**

```ts
declare const assertProviderOverrideStateVersion: (
  value: unknown,
) => asserts value is ProviderOverrideState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L128)

### assertProviderOverrideStateVersionEffect

Check an override artifact version in the Effect error channel.

**Example**

```ts
Effect.runSync(assertProviderOverrideStateVersionEffect({ version: 1 }));
```

**Signature**

```ts
declare const assertProviderOverrideStateVersionEffect: (
  value: unknown,
) => Effect.Effect<void, LocalServiceVersionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L87)

### checkVersionEffect

Check one artifact version without starting a separate public operation span.

**Example**

```ts
Effect.runSync(
  checkVersionEffect(
    { version: 1 },
    1,
    "Local-service plan",
    "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED",
    "relkit check",
  ),
);
```

**Signature**

```ts
declare const checkVersionEffect: (
  value: unknown,
  expected: number,
  label: string,
  code: LocalServiceVersionErrorCode,
  command: string,
) => Effect.Effect<undefined, LocalServiceVersionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol-version.ts#L25)

## `protocol.ts`

Version and artifact names for the local-service protocol.

### LOCAL_SERVICE_PLAN_FILE

**Signature**

```ts
declare const LOCAL_SERVICE_PLAN_FILE: "local-services.plan.json";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L4)

### LOCAL_SERVICE_PLAN_VERSION

**Signature**

```ts
declare const LOCAL_SERVICE_PLAN_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L3)

### LOCAL_SERVICE_PROTOCOL_VERSION

Version and artifact names for the local-service protocol.

**Signature**

```ts
declare const LOCAL_SERVICE_PROTOCOL_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L2)

### LOCAL_SERVICE_STATE_FILE

**Signature**

```ts
declare const LOCAL_SERVICE_STATE_FILE: "local-services.state.json";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L6)

### LOCAL_SERVICE_STATE_VERSION

**Signature**

```ts
declare const LOCAL_SERVICE_STATE_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L5)

### PROVIDER_OVERRIDE_STATE_FILE

**Signature**

```ts
declare const PROVIDER_OVERRIDE_STATE_FILE: "provider-overrides.json";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L8)

### PROVIDER_OVERRIDE_STATE_VERSION

**Signature**

```ts
declare const PROVIDER_OVERRIDE_STATE_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.ts#L7)

## `protocol.types.ts`

### LocalServiceBindingState (interface)

Observed state of one local binding.

**Example**

```ts
const phase: LocalServicePhase = binding.phase;
```

**Signature**

```ts
export interface LocalServiceBindingState {
  readonly bindingId: string;
  readonly recipe: ProviderLocalRecipeReference;
  readonly phase: LocalServicePhase;
  readonly environment?: string;
  readonly serviceGeneration?: string;
  readonly units?: readonly string[];
  readonly message?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L49)

### LocalServiceMaterializerMetadata (interface)

Identity of a local materializer integration.

**Example**

```ts
const metadata: LocalServiceMaterializerMetadata = {
  kind: "local-service-materializer",
  protocolVersion: 1,
  integrationId: "docker",
};
```

**Signature**

```ts
export interface LocalServiceMaterializerMetadata<IntegrationId extends string = string> {
  readonly kind: "local-service-materializer";
  readonly protocolVersion: typeof LOCAL_SERVICE_PROTOCOL_VERSION;
  readonly integrationId: IntegrationId;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L13)

### LocalServicePhase (type alias)

Runtime lifecycle phase for one local binding.

**Example**

```ts
const phase: LocalServicePhase = "healthy";
```

**Signature**

```ts
type LocalServicePhase = "pending" | "starting" | "healthy" | "unhealthy" | "stopped";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L44)

### LocalServicePlan (interface)

Versioned local service plan.

**Example**

```ts
const entries: readonly LocalServicePlanEntry[] = plan.services;
```

**Signature**

```ts
export interface LocalServicePlan {
  readonly version: typeof LOCAL_SERVICE_PLAN_VERSION;
  readonly graphHash: string;
  readonly services: readonly LocalServicePlanEntry[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L35)

### LocalServicePlanEntry (interface)

Planned local binding and its provider recipe.

**Example**

```ts
const entry = plan.services[0] as LocalServicePlanEntry;
```

**Signature**

```ts
export interface LocalServicePlanEntry {
  readonly bindingId: string;
  readonly capability: string;
  readonly profile: string;
  readonly materializerId: string;
  readonly recipe: ProviderLocalRecipeReference;
  readonly configuration: JsonValue;
  readonly requiredBy: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L22)

### LocalServiceState (interface)

Versioned state for all local bindings.

**Example**

```ts
const bindings: readonly LocalServiceBindingState[] = state.services;
```

**Signature**

```ts
export interface LocalServiceState {
  readonly version: typeof LOCAL_SERVICE_STATE_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly planHash: string;
  readonly services: readonly LocalServiceBindingState[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L62)

### LocalServiceVersionErrorCode (type alias)

Stable error codes for unsupported artifact versions.

**Example**

```ts
const code: LocalServiceVersionErrorCode = "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED";
```

**Signature**

```ts
type LocalServiceVersionErrorCode =
  | "RELKIT_LOCAL_SERVICE_PLAN_VERSION_UNSUPPORTED"
  | "RELKIT_LOCAL_SERVICE_STATE_VERSION_UNSUPPORTED"
  | "RELKIT_PROVIDER_OVERRIDE_STATE_VERSION_UNSUPPORTED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L102)

### ProviderOverrideBinding (interface)

Resolved override values for one provider binding.

**Example**

```ts
const url = binding.values.url;
```

**Signature**

```ts
export interface ProviderOverrideBinding {
  readonly bindingId: string;
  readonly values: Readonly<Record<string, JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L73)

### ProviderOverrideExpectation (interface)

Expected activation identity for provider override lookup.

**Example**

```ts
const expected: ProviderOverrideExpectation = {
  applicationId: "demo",
  planHash,
  generationId: "generation-1",
};
```

**Signature**

```ts
export interface ProviderOverrideExpectation {
  readonly applicationId: string;
  readonly planHash: string;
  readonly generationId: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L93)

### ProviderOverrideState (interface)

Versioned override state bound to one activation.

**Example**

```ts
const bindings: readonly ProviderOverrideBinding[] = overrides.bindings;
```

**Signature**

```ts
export interface ProviderOverrideState {
  readonly version: typeof PROVIDER_OVERRIDE_STATE_VERSION;
  readonly applicationId: string;
  readonly localProjectId: string;
  readonly planHash: string;
  readonly generationId: string;
  readonly bindings: readonly ProviderOverrideBinding[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/protocol.types.ts#L81)

## `provider-overrides.ts`

### providerOverrideBindingValues

Resolve provider overrides synchronously for existing callers.

**Throws**

LocalServiceVersionError or TypeError for an invalid artifact.

**Example**

```ts
providerOverrideBindingValues(artifact, expected);
```

**Signature**

```ts
declare const providerOverrideBindingValues: (
  value: unknown,
  expected: ProviderOverrideExpectation,
) => Readonly<Record<string, Readonly<Record<string, JsonValue>>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/provider-overrides.ts#L82)

### providerOverrideBindingValuesEffect

Resolve only the overrides belonging to one activation.

**Example**

```ts
Effect.runSync(providerOverrideBindingValuesEffect(artifact, expected));
```

**Signature**

```ts
declare const providerOverrideBindingValuesEffect: (
  value: unknown,
  expected: ProviderOverrideExpectation,
) => Effect.Effect<
  Record<string, Readonly<Record<string, JsonValue>>>,
  LocalServiceVersionFailure | LocalServiceValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/provider-overrides.ts#L22)

## `recipe-normalize.ts`

### NormalizedLocalServiceRecipe

**Signature**

```ts
declare const NormalizedLocalServiceRecipe: NormalizedLocalServiceRecipe;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.ts#L24)

### NormalizedLocalServiceUnit

**Signature**

```ts
declare const NormalizedLocalServiceUnit: NormalizedLocalServiceUnit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.ts#L25)

### normalizeLocalServiceRecipe

Normalize a recipe synchronously for existing callers.

**Throws**

TypeError when a recipe field or dependency is invalid.

**Example**

```ts
normalizeLocalServiceRecipe(recipe);
```

**Signature**

```ts
declare const normalizeLocalServiceRecipe: (
  recipe: LocalServiceRecipeInput,
) => NormalizedLocalServiceRecipe;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.ts#L43)

### normalizeLocalServiceRecipeEffect

Normalize a supported recipe in the Effect error channel.

**Example**

```ts
Effect.runSync(normalizeLocalServiceRecipeEffect(recipe));
```

**Signature**

```ts
declare const normalizeLocalServiceRecipeEffect: (recipe: LocalServiceRecipeInput) => Effect.Effect<
  | Readonly<{
      initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
      kind: "local-service-recipe";
      protocolVersion: 1;
      integrationId: string;
      recipeId: string;
      recipeVersion: 1;
      materializerId: "docker";
      units: ReadonlyArray<NormalizedLocalServiceUnit>;
      volumes: Readonly<{ data?: never } | { data: { mountPath: string } }>;
      generatedSecrets: Readonly<{ [x: string]: LocalServiceGeneratedSecret }>;
      environment: Readonly<{ [x: string]: LocalServiceSecretEnvironment }>;
      ownership: Readonly<{ scope: "binding"; retainVolumes: true }>;
      outputs: (context: LocalServiceRecipeOutputContext) => Readonly<Record<string, JsonValue>>;
    }>
  | Readonly<{
      initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
      ownership: Readonly<{ scope: "binding" | "project"; retainVolumes: boolean }>;
      outputs: (context: LocalServiceRecipeOutputContext) => Readonly<Record<string, JsonValue>>;
      network?: Readonly<{ readonly internal?: boolean }>;
      kind: "local-service-recipe";
      protocolVersion: 2;
      integrationId: string;
      recipeId: string;
      recipeVersion: 2;
      materializerId: "docker";
      units: ReadonlyArray<NormalizedLocalServiceUnit>;
      volumes: Readonly<{ [x: string]: CompositeLocalServiceVolume }>;
      generatedSecrets: Readonly<{ [x: string]: LocalServiceGeneratedSecret }>;
      environment: Readonly<{
        [x: string]: LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment;
      }>;
    }>,
  LocalServiceValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.ts#L32)

## `recipe-normalize.types.ts`

### NormalizedLocalServiceRecipe (interface)

Canonical recipe used by local materializers.
Units are ordered by dependency and ID and the root collections are frozen.

**Example**

```ts
const normalized: NormalizedLocalServiceRecipe = normalizeLocalServiceRecipe(recipe);
```

**Signature**

```ts
export interface NormalizedLocalServiceRecipe {
  readonly kind: "local-service-recipe";
  readonly protocolVersion: 1 | typeof LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION;
  readonly integrationId: string;
  readonly recipeId: string;
  readonly recipeVersion: number;
  readonly materializerId: "docker";
  readonly units: readonly NormalizedLocalServiceUnit[];
  readonly volumes: Readonly<Record<string, CompositeLocalServiceVolume>>;
  readonly generatedSecrets: Readonly<Record<string, LocalServiceGeneratedSecret>>;
  readonly environment: Readonly<
    Record<string, LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment>
  >;
  readonly network?: Readonly<{ readonly internal?: boolean }>;
  readonly ownership: Readonly<{
    readonly scope: "project" | "binding";
    readonly retainVolumes: boolean;
  }>;
  readonly outputs: (
    context: LocalServiceRecipeOutputContext,
  ) => Readonly<Record<string, JsonValue>>;
  readonly initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.types.ts#L27)

### NormalizedLocalServiceUnit (interface)

Validated unit with required frozen collections.

**Example**

```ts
const ids = recipe.units.map((unit: NormalizedLocalServiceUnit) => unit.id);
```

**Signature**

```ts
export interface NormalizedLocalServiceUnit extends CompositeLocalServiceUnit {
  readonly dependsOn: readonly string[];
  readonly ports: Readonly<Record<string, number>>;
  readonly volumes: readonly { readonly name: string; readonly mountPath: string }[];
  readonly health?: LocalServiceHealthCheck;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-normalize.types.ts#L16)

## `recipe-runtime.types.ts`

### LocalServiceInstance (interface)

Observed materializer instance, possibly containing child units.

**Example**

```ts
const healthy = instance.health === "healthy";
```

**Signature**

```ts
export interface LocalServiceInstance {
  readonly id: string;
  readonly name: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly state: string;
  readonly health?: "starting" | "healthy" | "unhealthy";
  readonly ports: Readonly<Record<string, number>>;
  readonly unitId?: string;
  readonly units?: readonly LocalServiceInstance[];
  readonly networkName?: string;
  readonly environment?: string;
  readonly serviceGeneration?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-runtime.types.ts#L11)

### LocalServiceMaterializerRuntime (interface)

External materializer operations that own local containers and volumes.
Implementations must release their acquired resources through stop, remove, and removeVolumes.

**Example**

```ts
const services = await materializer.list({ application: "demo" });
```

**Signature**

```ts
export interface LocalServiceMaterializerRuntime {
  readonly kind: "local-service-materializer-runtime";
  readonly protocolVersion: typeof LOCAL_SERVICE_PROTOCOL_VERSION;
  readonly integrationId: string;
  /** List matching services.
   * @param labels - Bounded identity labels used for lookup.
   * @param signal - Optional cancellation signal.
   * @returns Matching instances or a rejected provider promise.
   * @example await materializer.list({ application: "demo" });
   */
  readonly list: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<readonly LocalServiceInstance[]>;
  /** Start one requested service and return its live instance.
   * @param request - Recipe and runtime bindings.
   * @returns A live instance or a rejected provider promise.
   * @example await materializer.start(request);
   */
  readonly start: (request: LocalServiceStartRequest) => Promise<LocalServiceInstance>;
  /** Stop a live service without deleting it.
   * @param id - Materializer instance ID.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.stop?.(instance.id);
   */
  readonly stop?: (id: string, signal?: AbortSignal) => Promise<void>;
  /** Remove a stopped service.
   * @param id - Materializer instance ID.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.remove(instance.id);
   */
  readonly remove: (id: string, signal?: AbortSignal) => Promise<void>;
  /** Remove volumes owned by matching services.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.removeVolumes({ application: "demo" });
   */
  readonly removeVolumes: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<void>;
  /** List matching volumes when the materializer supports it.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Named volumes or a rejected provider promise.
   * @example await materializer.listVolumes?.({ application: "demo" });
   */
  readonly listVolumes?: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<
    readonly { readonly name: string; readonly labels: Readonly<Record<string, string>> }[]
  >;
  /** Remove networks owned by matching services.
   * @param labels - Ownership labels.
   * @param signal - Optional cancellation signal.
   * @returns Completion or a rejected provider promise.
   * @example await materializer.removeNetworks?.({ application: "demo" });
   */
  readonly removeNetworks?: (
    labels: Readonly<Record<string, string>>,
    signal?: AbortSignal,
  ) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-runtime.types.ts#L51)

### LocalServiceStartRequest (interface)

Parameters for starting one materialized local service.
The caller owns cancellation through `signal` and materializer cleanup after start.

**Example**

```ts
await materializer.start(request);
```

**Signature**

```ts
export interface LocalServiceStartRequest {
  readonly name: string;
  readonly volumeName?: string;
  readonly labels: Readonly<Record<string, string>>;
  readonly recipe: LocalServiceRecipeInput;
  readonly environmentFile?: string;
  readonly environmentFiles?: Readonly<Record<string, string>>;
  readonly environmentVariables?: Readonly<Record<string, string>>;
  readonly volumeNames?: Readonly<Record<string, string>>;
  readonly networkName?: string;
  readonly serviceGeneration?: string;
  readonly workerArtifact?: LocalServiceWorkerArtifact;
  readonly bindMounts?: Readonly<Record<string, readonly LocalServiceBindMount[]>>;
  readonly environmentVariablesByUnit?: Readonly<Record<string, Readonly<Record<string, string>>>>;
  readonly portBindings?: Readonly<Record<string, Readonly<Record<string, number>>>>;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe-runtime.types.ts#L29)

## `recipe.ts`

Version used by composite recipes; single-container recipes remain on v1.

### "./recipe-runtime.types.js" (namespace export)

Re-exports all named exports from the "./recipe-runtime.types.js" module.

**Signature**

```ts
export * from "./recipe-runtime.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.ts#L5)

### "./recipe.types.js" (namespace export)

Re-exports all named exports from the "./recipe.types.js" module.

**Signature**

```ts
export * from "./recipe.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.ts#L4)

### LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION

Version used by composite recipes; single-container recipes remain on v1.

**Signature**

```ts
declare const LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION: 2;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.ts#L2)

## `recipe.types.ts`

### CompositeLocalServiceRecipe (interface)

Version 2 recipe with ordered units and optional shared resources.
Supply either a flat `units` list or the grouped container, init, and worker fields.

**Example**

```ts
normalizeLocalServiceRecipe(recipe as CompositeLocalServiceRecipe);
```

**Signature**

```ts
export interface CompositeLocalServiceRecipe<IntegrationId extends string = string> {
  readonly kind: "local-service-recipe";
  readonly protocolVersion: typeof LOCAL_SERVICE_RECIPE_PROTOCOL_VERSION;
  readonly integrationId: IntegrationId;
  readonly recipeId: string;
  readonly recipeVersion: 2;
  readonly materializerId: "docker";
  /** A flat unit list is preferred; grouped fields keep recipes readable. */
  readonly units?: readonly CompositeLocalServiceUnit[];
  readonly containers?: readonly Omit<CompositeLocalServiceUnit, "kind">[];
  readonly init?: readonly Omit<CompositeLocalServiceUnit, "kind">[];
  readonly workers?: readonly Omit<CompositeLocalServiceUnit, "kind">[];
  readonly volumes: Readonly<Record<string, CompositeLocalServiceVolume>>;
  readonly generatedSecrets?: Readonly<Record<string, LocalServiceGeneratedSecret>>;
  readonly environment?: Readonly<
    Record<string, LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment>
  >;
  readonly network?: Readonly<{ readonly internal?: boolean }>;
  readonly ownership?: Readonly<{
    readonly scope: "project" | "binding";
    readonly retainVolumes?: boolean;
  }>;
  readonly outputs: (
    context: LocalServiceRecipeOutputContext,
  ) => Readonly<Record<string, JsonValue>>;
  readonly initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L121)

### CompositeLocalServiceUnit (interface)

Container, initializer, or worker declaration.
Dependencies refer to other unit IDs in the same composite recipe.

**Example**

```ts
const unit: CompositeLocalServiceUnit = { id: "api", kind: "container", image: "api" };
```

**Signature**

```ts
export interface CompositeLocalServiceUnit {
  readonly id: string;
  readonly kind: CompositeLocalServiceUnitKind;
  readonly image: string;
  readonly command?: readonly string[];
  readonly dependsOn?: readonly string[];
  readonly ports?: Readonly<Record<string, number>>;
  readonly volumes?: readonly CompositeLocalServiceUnitVolume[];
  readonly environment?: Readonly<
    Record<string, LocalServiceSecretEnvironment | LocalServiceLiteralEnvironment>
  >;
  readonly health?: LocalServiceHealthCheck;
  readonly networkAliases?: readonly string[];
  readonly hostAliases?: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L101)

### CompositeLocalServiceUnitKind (type alias)

Supported unit roles in a composite recipe.

**Example**

```ts
const kind: CompositeLocalServiceUnitKind = "worker";
```

**Signature**

```ts
type CompositeLocalServiceUnitKind = "container" | "init" | "worker";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L95)

### CompositeLocalServiceUnitVolume (interface)

Mount of one named composite volume into a unit.

**Example**

```ts
const mount: CompositeLocalServiceUnitVolume = { name: "data", mountPath: "/data" };
```

**Signature**

```ts
export interface CompositeLocalServiceUnitVolume {
  readonly name: string;
  readonly mountPath: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L68)

### CompositeLocalServiceVolume (interface)

Named composite volume and persistence policy.

**Example**

```ts
const volume: CompositeLocalServiceVolume = { mountPath: "/data", persistent: true };
```

**Signature**

```ts
export interface CompositeLocalServiceVolume {
  readonly mountPath: string;
  readonly persistent?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L60)

### LocalServiceBindMount (interface)

Host path mounted into a local-service unit.

**Example**

```ts
const mount: LocalServiceBindMount = { source: "/tmp/data", target: "/data", readOnly: true };
```

**Signature**

```ts
export interface LocalServiceBindMount {
  readonly source: string;
  readonly target: string;
  readonly readOnly?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L76)

### LocalServiceGeneratedSecret (interface)

Generated secret byte length and encoding.

**Example**

```ts
const secret: LocalServiceGeneratedSecret = { bytes: 32, encoding: "hex" };
```

**Signature**

```ts
export interface LocalServiceGeneratedSecret {
  readonly bytes: number;
  readonly encoding?: "base64url" | "hex";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L36)

### LocalServiceHealthCheck (interface)

Container health command and positive retry timing.

**Example**

```ts
const check: LocalServiceHealthCheck = {
  command: ["true"],
  intervalMs: 1000,
  timeoutMs: 500,
  retries: 3,
};
```

**Signature**

```ts
export interface LocalServiceHealthCheck {
  readonly command: readonly string[];
  readonly intervalMs: number;
  readonly timeoutMs: number;
  readonly retries: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L19)

### LocalServiceLiteralEnvironment (interface)

Literal environment value without a secret reference.

**Example**

```ts
const level: LocalServiceLiteralEnvironment = { value: "debug" };
```

**Signature**

```ts
export interface LocalServiceLiteralEnvironment {
  readonly value: string;
  readonly secret?: never;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L52)

### LocalServiceRecipe (interface)

Version 1 single-container recipe kept for compatibility.
Its output and initialization callbacks run in the materializer, not during normalization.

**Example**

```ts
normalizeLocalServiceRecipe(recipe as LocalServiceRecipe);
```

**Signature**

```ts
export interface LocalServiceRecipe<IntegrationId extends string = string> {
  readonly kind: "local-service-recipe";
  readonly protocolVersion: typeof LOCAL_SERVICE_PROTOCOL_VERSION;
  readonly integrationId: IntegrationId;
  readonly recipeId: string;
  readonly recipeVersion: number;
  readonly materializerId: "docker";
  readonly image: string;
  readonly command?: readonly string[];
  readonly ports: Readonly<Record<string, number>>;
  readonly volume?: LocalServiceVolume;
  readonly health: LocalServiceHealthCheck;
  readonly generatedSecrets?: Readonly<Record<string, LocalServiceGeneratedSecret>>;
  readonly environment?: Readonly<Record<string, LocalServiceSecretEnvironment>>;
  readonly outputs: (
    context: LocalServiceRecipeOutputContext,
  ) => Readonly<Record<string, JsonValue>>;
  readonly initialize?: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L159)

### LocalServiceRecipeInput (type alias)

Either supported local recipe form.

**Example**

```ts
normalizeLocalServiceRecipe(recipe as LocalServiceRecipeInput);
```

**Signature**

```ts
type LocalServiceRecipeInput<IntegrationId extends string = string> =
  LocalServiceRecipe<IntegrationId> | CompositeLocalServiceRecipe<IntegrationId>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L152)

### LocalServiceRecipeOutputContext (interface)

Runtime values supplied to recipe output and initialization callbacks.

**Example**

```ts
const context: LocalServiceRecipeOutputContext = { ports: {}, secrets: {} };
```

**Signature**

```ts
export interface LocalServiceRecipeOutputContext {
  readonly ports: Readonly<Record<string, number>>;
  readonly secrets: Readonly<Record<string, string>>;
  readonly endpoints?: Readonly<Record<string, string>>;
  readonly signal?: AbortSignal;
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L8)

### LocalServiceSecretEnvironment (interface)

Reference to a declared generated secret.

**Example**

```ts
const password: LocalServiceSecretEnvironment = { secret: "password" };
```

**Signature**

```ts
export interface LocalServiceSecretEnvironment {
  readonly secret: string;
  readonly value?: never;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L44)

### LocalServiceVolume (interface)

Legacy single-container volume mount.

**Example**

```ts
const volume: LocalServiceVolume = { mountPath: "/data" };
```

**Signature**

```ts
export interface LocalServiceVolume {
  readonly mountPath: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L29)

### LocalServiceWorkerArtifact (interface)

Built worker inputs used by a local materializer.

**Example**

```ts
const artifact: LocalServiceWorkerArtifact = {
  entrypoint: "worker.js",
  providerOverridesFile: "overrides.json",
};
```

**Signature**

```ts
export interface LocalServiceWorkerArtifact {
  readonly entrypoint: string;
  readonly nodeModulesDirectory?: string;
  readonly providerOverridesFile: string;
  readonly environment?: Readonly<Record<string, string>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/local-service/src/recipe.types.ts#L85)

---

# OTLP API
Source: https://relkit.dev/docs/api/integrations/otlp

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [observability](/docs/modules/operations/observability).

## Public imports

- `@relkit/otlp` — 3 exports
- `@relkit/otlp/runtime` — 9 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                   | Kind  | Import from            | Example                                                                                                   |
| ------------------------------------------------------------------------------------- | ----- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
| [createOtlpExporter](/docs/api/integrations/otlp#createotlpexporter)                  | Value | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [createOtlpTransport](/docs/api/integrations/otlp#createotlptransport)                | Value | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [createTelemetryExporter](/docs/api/integrations/otlp#createtelemetryexporter)        | Value | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [otlp](/docs/api/integrations/otlp#otlp)                                              | Value | `@relkit/otlp`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/landing/telemetry.ts#L13) |
| [OtlpExporter](/docs/api/integrations/otlp#otlpexporter-interface)                    | Type  | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpExporterOptions](/docs/api/integrations/otlp#otlpexporteroptions-interface)      | Type  | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpOptions](/docs/api/integrations/otlp#otlpoptions-interface)                      | Type  | `@relkit/otlp`         | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpSignal](/docs/api/integrations/otlp#otlpsignal-type-alias)                       | Type  | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpTelemetryExporter](/docs/api/integrations/otlp#otlptelemetryexporter-type-alias) | Type  | `@relkit/otlp`         | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpTransport](/docs/api/integrations/otlp#otlptransport-interface)                  | Type  | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [OtlpTransportOptions](/docs/api/integrations/otlp#otlptransportoptions-interface)    | Type  | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [runtimeIntegration](/docs/api/integrations/otlp#runtimeintegration)                  | Value | `@relkit/otlp/runtime` | [Module example](/docs/modules/operations/observability)                                                  |

## `index.ts`

### "./otlp.js" (namespace export)

Re-exports all named exports from the "./otlp.js" module.

**Signature**

```ts
export * from "./otlp.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/index.ts#L1)

## `otlp.ts`

### OtlpOptions (interface)

**Signature**

```ts
export interface OtlpOptions {
  readonly endpoint: TextInput;
  readonly headers?: Readonly<Record<string, TextInput>>;
  readonly serviceName?: TextInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/otlp.ts#L13)

### OtlpTelemetryExporter (type alias)

**Signature**

```ts
type OtlpTelemetryExporter = TelemetryExporterDescriptor<"otlp", "otlp", OtlpOptions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/otlp.ts#L19)

### otlp

Declares one statically loaded OTLP/HTTP telemetry exporter.

**Signature**

```ts
declare const otlp: (options: OtlpOptions) => OtlpTelemetryExporter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/otlp.ts#L22)

## `exporter-support.ts`

### combinedSignal

**Signature**

```ts
declare const combinedSignal: (first: AbortSignal, second: AbortSignal | undefined) => AbortSignal;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L30)

### nonNegative

**Signature**

```ts
declare const nonNegative: (value: number, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L68)

### otlpPayload

**Signature**

```ts
declare const otlpPayload: (
  serviceName: string | undefined,
  records: readonly RedactedObservabilityRecord[],
  signal: OtlpSignal,
) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L5)

### otlpSignalFor

**Signature**

```ts
declare const otlpSignalFor: (record: RedactedObservabilityRecord) => OtlpSignal | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L19)

### otlpUnitId

**Signature**

```ts
declare const otlpUnitId: (record: RedactedObservabilityRecord, sequence: number) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L24)

### positive

**Signature**

```ts
declare const positive: (value: number, name: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L63)

### text

**Signature**

```ts
declare const text: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L49)

### textMap

**Signature**

```ts
declare const textMap: (value: unknown) => Readonly<Record<string, string>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L55)

### within

**Signature**

```ts
declare const within: (operation: Promise<unknown>, timeoutMs: number) => Promise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter-support.ts#L34)

## `exporter.ts`

### OtlpExporter (interface)

**Signature**

```ts
export interface OtlpExporter extends TelemetryExporterRuntime {
  readonly stats: () => TelemetryExporterRuntimeStats & {
    readonly exportedRecords: number;
    readonly retries: number;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter.ts#L32)

### OtlpExporterOptions (interface)

**Signature**

```ts
export interface OtlpExporterOptions {
  readonly transport: OtlpTransport;
  readonly serviceName?: string;
  readonly maxRecords?: number;
  readonly batchSize?: number;
  readonly maxRetries?: number;
  readonly retryDelayMs?: number;
  readonly signal?: AbortSignal;
  readonly delay?: (milliseconds: number) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter.ts#L21)

### createOtlpExporter

**Signature**

```ts
declare const createOtlpExporter: (options: OtlpExporterOptions) => OtlpExporter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter.ts#L39)

### createTelemetryExporter

**Signature**

```ts
declare const createTelemetryExporter: (
  context: TelemetryExporterFactoryContext,
) => Promise<TelemetryExporterRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/exporter.ts#L159)

## `index.ts`

### "./exporter.js" (namespace export)

Re-exports all named exports from the "./exporter.js" module.

**Signature**

```ts
export * from "./exporter.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/index.ts#L2)

### "./transport.js" (namespace export)

Re-exports all named exports from the "./transport.js" module.

**Signature**

```ts
export * from "./transport.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/index.ts#L1)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "otlp";
  registrations: ReadonlyArray<{ capability: string; adapterId: string; protocolVersion: number }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/index.ts#L4)

## `transport.ts`

### OtlpSignal (type alias)

**Signature**

```ts
type OtlpSignal = "logs" | "traces";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/transport.ts#L3)

### OtlpTransport (interface)

**Signature**

```ts
export interface OtlpTransport {
  readonly send: (signal: OtlpSignal, payload: JsonValue, abort?: AbortSignal) => Promise<void>;
  readonly flush: () => Promise<void>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/transport.ts#L11)

### OtlpTransportOptions (interface)

**Signature**

```ts
export interface OtlpTransportOptions {
  readonly endpoint: string;
  readonly headers?: Readonly<Record<string, string>>;
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/transport.ts#L5)

### createOtlpTransport

**Signature**

```ts
declare const createOtlpTransport: (options: OtlpTransportOptions) => OtlpTransport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/otlp/src/runtime/transport.ts#L17)

---

# Pulumi API
Source: https://relkit.dev/docs/api/integrations/pulumi

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [deployment](/docs/modules/jobs/deployment), [deployment](/docs/modules/deployment), [aws](/docs/modules/deployment/aws).

## Public imports

- `@relkit/pulumi` — 0 exports
- `@relkit/pulumi/engine` — 48 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                        | Kind  | Import from             | Example                                                                                                       |
| ---------------------------------------------------------------------------------------------------------- | ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| [createInlinePulumiProgram](/docs/api/integrations/pulumi#createinlinepulumiprogram)                       | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [createOutputReport](/docs/api/integrations/pulumi#createoutputreport-1)                                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [createPreviewReport](/docs/api/integrations/pulumi#createpreviewreport-1)                                 | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [createPulumiEventLogger](/docs/api/integrations/pulumi#createpulumieventlogger)                           | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [createPulumiProgram](/docs/api/integrations/pulumi#createpulumiprogram)                                   | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L43)    |
| [createPulumiWorkspace](/docs/api/integrations/pulumi#createpulumiworkspace)                               | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L34)    |
| [createUpdateReport](/docs/api/integrations/pulumi#createupdatereport-1)                                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [deploymentIntegration](/docs/api/integrations/pulumi#deploymentintegration)                               | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [ExecutedDeploymentOperations](/docs/api/integrations/pulumi#executeddeploymentoperations-interface)       | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [executeDeploymentOperations](/docs/api/integrations/pulumi#executedeploymentoperations)                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [formatPulumiSummary](/docs/api/integrations/pulumi#formatpulumisummary)                                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [materializeDeploymentOperations](/docs/api/integrations/pulumi#materializedeploymentoperations)           | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/grouped-pulumi.probe.ts#L41)    |
| [MaterializeDeploymentOptions](/docs/api/integrations/pulumi#materializedeploymentoptions-interface)       | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [materializePulumiDeployment](/docs/api/integrations/pulumi#materializepulumideployment)                   | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/grouped-pulumi.probe.ts#L45)    |
| [PULUMI_CLOUD_BACKEND_URL](/docs/api/integrations/pulumi#pulumi_cloud_backend_url)                         | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PULUMI_PROGRAM_VERSION](/docs/api/integrations/pulumi#pulumi_program_version)                             | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PULUMI_REPORT_VERSION](/docs/api/integrations/pulumi#pulumi_report_version)                               | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiBackend](/docs/api/integrations/pulumi#pulumibackend-interface)                                     | Type  | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L107)   |
| [PulumiBackendKind](/docs/api/integrations/pulumi#pulumibackendkind-type-alias)                            | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [pulumiEngine](/docs/api/integrations/pulumi#pulumiengine)                                                 | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L45)    |
| [PulumiEventLog](/docs/api/integrations/pulumi#pulumieventlog-interface)                                   | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiEventOptions](/docs/api/integrations/pulumi#pulumieventoptions-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiEventSummary](/docs/api/integrations/pulumi#pulumieventsummary-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiIntegrationImport](/docs/api/integrations/pulumi#pulumiintegrationimport-interface)                 | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiLogLevel](/docs/api/integrations/pulumi#pulumiloglevel-type-alias)                                  | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiOutput](/docs/api/integrations/pulumi#pulumioutput-interface)                                       | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiOutputReport](/docs/api/integrations/pulumi#pulumioutputreport-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiOutputs](/docs/api/integrations/pulumi#pulumioutputs-type-alias)                                    | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiOutputValue](/docs/api/integrations/pulumi#pulumioutputvalue-type-alias)                            | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiPreviewReport](/docs/api/integrations/pulumi#pulumipreviewreport-interface)                         | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiProgramFiles](/docs/api/integrations/pulumi#pulumiprogramfiles-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiProgramOptions](/docs/api/integrations/pulumi#pulumiprogramoptions-interface)                       | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiReport](/docs/api/integrations/pulumi#pulumireport-type-alias)                                      | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiSecretOutput](/docs/api/integrations/pulumi#pulumisecretoutput-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiStackMode](/docs/api/integrations/pulumi#pulumistackmode-type-alias)                                | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiUpdateReport](/docs/api/integrations/pulumi#pulumiupdatereport-interface)                           | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiWorkspaceConfigurationError](/docs/api/integrations/pulumi#pulumiworkspaceconfigurationerror-class) | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [PulumiWorkspaceHandle](/docs/api/integrations/pulumi#pulumiworkspacehandle-interface)                     | Type  | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/aws-integration.test.ts#L30)    |
| [PulumiWorkspaceOptions](/docs/api/integrations/pulumi#pulumiworkspaceoptions-interface)                   | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [redactPulumiOutputs](/docs/api/integrations/pulumi#redactpulumioutputs)                                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [renderPulumiProgram](/docs/api/integrations/pulumi#renderpulumiprogram)                                   | Value | `@relkit/pulumi/engine` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/deployment/grouped-layout-contract.ts#L85) |
| [ResolvedPulumiBackend](/docs/api/integrations/pulumi#resolvedpulumibackend-type-alias)                    | Type  | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [resolvePulumiBackend](/docs/api/integrations/pulumi#resolvepulumibackend)                                 | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [serializePulumiReport](/docs/api/integrations/pulumi#serializepulumireport)                               | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [summarizePulumiEvents](/docs/api/integrations/pulumi#summarizepulumievents-1)                             | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [toPulumiEffectLog](/docs/api/integrations/pulumi#topulumieffectlog)                                       | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [toPulumiLog](/docs/api/integrations/pulumi#topulumilog)                                                   | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |
| [writePulumiProgram](/docs/api/integrations/pulumi#writepulumiprogram)                                     | Value | `@relkit/pulumi/engine` | [Module example](/docs/modules/jobs/deployment)                                                               |

## `index.ts`

Declares selected Pulumi engine metadata and exposes its owning deployment implementation.

### "@relkit/deploy-pulumi" (namespace export)

Re-exports all named exports from the "@relkit/deploy-pulumi" module.

**Signature**

```ts
export * from "@relkit/deploy-pulumi";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/pulumi/src/engine/index.ts#L17)

### deploymentIntegration

**Signature**

```ts
declare const deploymentIntegration: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "pulumi";
  role: "engine";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/pulumi/src/engine/index.ts#L14)

### pulumiEngine

**Signature**

```ts
declare const pulumiEngine: Readonly<{
  kind: "deployment-integration";
  protocolVersion: 1;
  integrationId: "pulumi";
  role: "engine";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/pulumi/src/engine/index.ts#L7)

## `index.ts`

## `events-report.ts`

### createOutputReport

**Signature**

```ts
declare const createOutputReport: (
  outputs: OutputMap,
  options: PulumiEventOptions,
) => PulumiOutputReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-report.ts#L64)

### createPreviewReport

**Signature**

```ts
declare const createPreviewReport: (
  result: Pick<PreviewResult, "changeSummary">,
  events: readonly EngineEvent[],
  toLog: (event: EngineEvent) => PulumiEventLog | undefined,
) => PulumiPreviewReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-report.ts#L30)

### createUpdateReport

**Signature**

```ts
declare const createUpdateReport: (
  result: Pick<UpResult, "summary" | "outputs">,
  events: readonly EngineEvent[],
  toLog: (event: EngineEvent) => PulumiEventLog | undefined,
  options: PulumiEventOptions,
) => PulumiUpdateReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-report.ts#L43)

### formatPulumiSummary

**Signature**

```ts
declare const formatPulumiSummary: (
  summary: PulumiPreviewReport["summary"],
  operation?: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-report.ts#L21)

### serializePulumiReport

**Signature**

```ts
declare const serializePulumiReport: (report: PulumiReport, options?: PulumiEventOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-report.ts#L75)

## `events-support.ts`

### OP_TYPES

**Signature**

```ts
declare const OP_TYPES: ReadonlyArray<OpType>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L12)

### changes

**Signature**

```ts
declare const changes: (value: OpMap | undefined) => OpMap;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L30)

### eventLogs

**Signature**

```ts
declare const eventLogs: (
  events: readonly EngineEvent[],
  toLog: (event: EngineEvent) => PulumiEventLog | undefined,
) => readonly PulumiEventLog[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L81)

### finiteNumber

**Signature**

```ts
declare const finiteNumber: (value: unknown) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L143)

### nonNegativeInteger

**Signature**

```ts
declare const nonNegativeInteger: (value: unknown) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L147)

### redactPulumiOutputs

**Signature**

```ts
declare const redactPulumiOutputs: (
  outputs: OutputMap | PulumiOutputs,
  options: PulumiEventOptions,
) => PulumiOutputs;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L128)

### resourceLog

**Signature**

```ts
declare const resourceLog: (
  base: (kind: string, level: "info" | "error", message: string, fields?: object) => PulumiEventLog,
  kind: string,
  message: string,
  event: {
    readonly metadata: {
      readonly op: OpType;
      readonly urn: string;
      readonly type: string;
      readonly logical?: boolean;
    };
  },
  extra?: object,
) => PulumiEventLog;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L58)

### safeFields

**Signature**

```ts
declare const safeFields: (
  value: object,
  options: PulumiEventOptions,
) => Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L43)

### safeText

**Signature**

```ts
declare const safeText: (value: unknown, options: PulumiEventOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L53)

### safeValue

**Signature**

```ts
declare const safeValue: (value: unknown, options: PulumiEventOptions) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L39)

### summarizePulumiEvents

**Signature**

```ts
declare const summarizePulumiEvents: (events: readonly EngineEvent[]) => PulumiEventSummary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-support.ts#L98)

## `events-types.ts`

### PULUMI_REPORT_VERSION

**Signature**

```ts
declare const PULUMI_REPORT_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L4)

### PulumiEventLog (interface)

**Signature**

```ts
export interface PulumiEventLog {
  readonly sequence: number;
  readonly timestamp: number;
  readonly kind: string;
  readonly level: PulumiLogLevel;
  readonly message: string;
  readonly fields: Readonly<Record<string, JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L10)

### PulumiEventOptions (interface)

**Signature**

```ts
export interface PulumiEventOptions {
  readonly redaction?: import("@relkit/observability").RedactionPolicy;
  readonly redact?: (value: unknown) => JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L6)

### PulumiEventSummary (interface)

**Signature**

```ts
export interface PulumiEventSummary {
  readonly resourceChanges: OpMap;
  readonly diagnostics: Readonly<{
    readonly info: number;
    readonly warning: number;
    readonly error: number;
  }>;
  readonly maybeCorrupt: boolean;
  readonly durationSeconds?: number;
  readonly result?: UpdateResult;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L18)

### PulumiLogLevel (type alias)

**Signature**

```ts
type PulumiLogLevel = "info" | "warn" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L5)

### PulumiOutput (interface)

**Signature**

```ts
export interface PulumiOutput {
  readonly secret: false;
  readonly value: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L29)

### PulumiOutputReport (interface)

**Signature**

```ts
export interface PulumiOutputReport {
  readonly version: typeof PULUMI_REPORT_VERSION;
  readonly kind: "outputs";
  readonly outputs: PulumiOutputs;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L51)

### PulumiOutputValue (type alias)

**Signature**

```ts
type PulumiOutputValue = PulumiOutput | PulumiSecretOutput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L36)

### PulumiOutputs (type alias)

**Signature**

```ts
type PulumiOutputs = Readonly<Record<string, PulumiOutputValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L37)

### PulumiPreviewReport (interface)

**Signature**

```ts
export interface PulumiPreviewReport {
  readonly version: typeof PULUMI_REPORT_VERSION;
  readonly kind: "preview";
  readonly summary: PulumiEventSummary;
  readonly logs: readonly PulumiEventLog[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L38)

### PulumiReport (type alias)

**Signature**

```ts
type PulumiReport = PulumiPreviewReport | PulumiUpdateReport | PulumiOutputReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L56)

### PulumiSecretOutput (interface)

**Signature**

```ts
export interface PulumiSecretOutput {
  readonly secret: true;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L33)

### PulumiUpdateReport (interface)

**Signature**

```ts
export interface PulumiUpdateReport {
  readonly version: typeof PULUMI_REPORT_VERSION;
  readonly kind: "update";
  readonly summary: PulumiEventSummary;
  readonly outputs: PulumiOutputs;
  readonly logs: readonly PulumiEventLog[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events-types.ts#L44)

## `events.ts`

### PULUMI_REPORT_VERSION

**Signature**

```ts
declare const PULUMI_REPORT_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L29)

### PulumiEventLog

**Signature**

```ts
declare const PulumiEventLog: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L30)

### PulumiEventOptions

**Signature**

```ts
declare const PulumiEventOptions: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L31)

### PulumiEventSummary

**Signature**

```ts
declare const PulumiEventSummary: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L32)

### PulumiLogLevel

**Signature**

```ts
declare const PulumiLogLevel: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L33)

### PulumiOutput

**Signature**

```ts
declare const PulumiOutput: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L34)

### PulumiOutputReport

**Signature**

```ts
declare const PulumiOutputReport: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L35)

### PulumiOutputValue

**Signature**

```ts
declare const PulumiOutputValue: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L36)

### PulumiOutputs

**Signature**

```ts
declare const PulumiOutputs: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L37)

### PulumiPreviewReport

**Signature**

```ts
declare const PulumiPreviewReport: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L38)

### PulumiReport

**Signature**

```ts
declare const PulumiReport: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L39)

### PulumiSecretOutput

**Signature**

```ts
declare const PulumiSecretOutput: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L40)

### PulumiUpdateReport

**Signature**

```ts
declare const PulumiUpdateReport: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L41)

### createOutputReport

**Signature**

```ts
declare const createOutputReport: (
  outputs: OutputMap,
  options?: PulumiEventOptions,
) => PulumiOutputReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L187)

### createPreviewReport

**Signature**

```ts
declare const createPreviewReport: (
  result: Pick<PreviewResult, "changeSummary">,
  events?: readonly EngineEvent[],
  options?: PulumiEventOptions,
) => PulumiPreviewReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L171)

### createPulumiEventLogger

Adapts the synchronous Automation API callback to an existing Effect runtime/logger.

**Signature**

```ts
declare const createPulumiEventLogger: (
  emit: (effect: Effect.Effect<void>) => void,
  options?: PulumiEventOptions,
) => (event: EngineEvent) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L151)

### createUpdateReport

**Signature**

```ts
declare const createUpdateReport: (
  result: Pick<UpResult, "summary" | "outputs">,
  events?: readonly EngineEvent[],
  options?: PulumiEventOptions,
) => PulumiUpdateReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L179)

### formatPulumiSummary

**Signature**

```ts
declare const formatPulumiSummary: (
  summary: PulumiPreviewReport["summary"],
  operation?: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L169)

### redactPulumiOutputs

**Signature**

```ts
declare const redactPulumiOutputs: (
  outputs: OutputMap | PulumiOutputs,
  options: PulumiEventOptions,
) => PulumiOutputs;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L194)

### serializePulumiReport

**Signature**

```ts
declare const serializePulumiReport: (report: PulumiReport, options?: PulumiEventOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L169)

### summarizePulumiEvents

Produces a stable summary from event order-independent engine data.

**Signature**

```ts
declare const summarizePulumiEvents: (events: readonly EngineEvent[]) => PulumiEventSummary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L165)

### toPulumiEffectLog

Builds an Effect log with only the already-redacted event message and fields.

**Signature**

```ts
declare const toPulumiEffectLog: (
  event: EngineEvent,
  options?: PulumiEventOptions,
) => Effect.Effect<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L135)

### toPulumiLog

Converts one Automation API event into safe data suitable for Effect logs.

**Signature**

```ts
declare const toPulumiLog: (
  event: EngineEvent,
  options?: PulumiEventOptions,
) => PulumiEventLog | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/events.ts#L45)

## `materialization.ts`

### MaterializeDeploymentOptions (interface)

**Signature**

```ts
export interface MaterializeDeploymentOptions {
  readonly stackName: string;
  readonly integrations: readonly unknown[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/materialization.ts#L18)

### materializeDeploymentOperations

**Signature**

```ts
declare const materializeDeploymentOperations: (
  plan: DeploymentPlan,
  options: MaterializeDeploymentOptions,
) => DeploymentProgramMaterialization;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/materialization.ts#L23)

## `operation-executor.ts`

### ExecutedDeploymentOperations (interface)

**Signature**

```ts
export interface ExecutedDeploymentOperations {
  readonly outputs: Readonly<Record<string, pulumi.Input<unknown>>>;
  readonly resourceCount: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/operation-executor.ts#L9)

### executeDeploymentOperations

**Signature**

```ts
declare const executeDeploymentOperations: (
  program: DeploymentProgramMaterialization,
) => ExecutedDeploymentOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/operation-executor.ts#L26)

## `program.ts`

### PULUMI_PROGRAM_VERSION

**Signature**

```ts
declare const PULUMI_PROGRAM_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L10)

### PulumiIntegrationImport (interface)

**Signature**

```ts
export interface PulumiIntegrationImport {
  readonly integrationId: string;
  readonly role: "engine" | "host" | "infrastructure" | "access";
  readonly packageName: string;
  readonly packageVersion: string;
  readonly exportName: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L23)

### PulumiProgramFiles (interface)

**Signature**

```ts
export interface PulumiProgramFiles {
  readonly directory: string;
  readonly projectName: string;
  readonly stackName: string;
  readonly pulumiYaml: string;
  readonly indexTs: string;
  readonly planJson: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L31)

### PulumiProgramOptions (interface)

**Signature**

```ts
export interface PulumiProgramOptions {
  readonly stackName?: string;
  readonly projectName?: string;
  readonly projectRoot?: string;
  readonly directory?: string;
  readonly integrations?: readonly unknown[];
  readonly integrationImports?: readonly PulumiIntegrationImport[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L14)

### createInlinePulumiProgram

**Signature**

```ts
declare const createInlinePulumiProgram: (
  plan: DeploymentPlan,
  options?: PulumiProgramOptions,
) => PulumiFn;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L97)

### createPulumiProgram

Creates the same plan-only resource tree for Pulumi Automation API inline use.

**Signature**

```ts
declare const createPulumiProgram: (
  plan: DeploymentPlan,
  options?: PulumiProgramOptions,
) => PulumiFn;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L78)

### materializePulumiDeployment

**Signature**

```ts
declare const materializePulumiDeployment: (
  plan: DeploymentPlan,
  options: { readonly stackName: string; readonly integrations: readonly unknown[] },
) => ExecutedDeploymentOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L99)

### renderPulumiProgram

Renders a path-independent Pulumi project from a provider-neutral plan.

**Signature**

```ts
declare const renderPulumiProgram: (
  plan: DeploymentPlan,
  options?: PulumiProgramOptions,
) => PulumiProgramFiles;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L41)

### writePulumiProgram

Writes only the deterministic Pulumi project files and returns their contents.

**Signature**

```ts
declare const writePulumiProgram: (
  plan: DeploymentPlan,
  options?: PulumiProgramOptions,
) => Promise<PulumiProgramFiles>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/program.ts#L64)

## `workspace.ts`

Acquires an explicitly selected native Pulumi workspace without changing backend or stack ownership.

### PULUMI_CLOUD_BACKEND_URL

**Signature**

```ts
declare const PULUMI_CLOUD_BACKEND_URL: "https://api.pulumi.com";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L15)

### PulumiBackend (interface)

**Signature**

```ts
export interface PulumiBackend {
  readonly kind: PulumiBackendKind;
  readonly url?: string;
  readonly directory?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L19)

### PulumiBackendKind (type alias)

**Signature**

```ts
type PulumiBackendKind = "cloud" | "object-storage" | "local";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L16)

### PulumiStackMode (type alias)

**Signature**

```ts
type PulumiStackMode = "create" | "select" | "create-or-select";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L17)

### PulumiWorkspaceConfigurationError (class)

**Signature**

```ts
declare class PulumiWorkspaceConfigurationError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L50)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_PULUMI_WORKSPACE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L51)

### PulumiWorkspaceHandle (interface)

**Signature**

```ts
export interface PulumiWorkspaceHandle {
  readonly workspace: LocalWorkspace;
  readonly stack: Stack;
  readonly projectName: string;
  readonly stackName: string;
  readonly workDir: string;
  readonly backend: ResolvedPulumiBackend;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L41)

### PulumiWorkspaceOptions (interface)

**Signature**

```ts
export interface PulumiWorkspaceOptions {
  readonly projectName: string;
  readonly stackName: string;
  readonly workDir?: string;
  readonly backend?: PulumiBackend;
  readonly mode?: PulumiStackMode;
  readonly config?: ConfigMap;
  readonly envVars?: Readonly<Record<string, string>>;
  readonly pulumiHome?: string;
  readonly pulumiCommand?: PulumiCommand;
  readonly program?: PulumiFn;
  readonly secretsProvider?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L27)

### ResolvedPulumiBackend (type alias)

**Signature**

```ts
type ResolvedPulumiBackend = { readonly kind: PulumiBackendKind; readonly url: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L25)

### createPulumiWorkspace

Creates/selects one explicit Pulumi stack and delegates persistence to Pulumi.

**Signature**

```ts
declare const createPulumiWorkspace: (
  options: PulumiWorkspaceOptions,
) => Promise<PulumiWorkspaceHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L80)

### resolvePulumiBackend

Resolves a supported Pulumi backend without creating a second state store.

**Signature**

```ts
declare const resolvePulumiBackend: (
  backend?: PulumiBackend,
  workDir?: string,
) => ResolvedPulumiBackend;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/deploy-pulumi/src/workspace.ts#L60)

---

# Redis API
Source: https://relkit.dev/docs/api/integrations/redis

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [integrations](/docs/modules/integrations), [local docker](/docs/modules/integrations/local-docker), [providers](/docs/modules/deployment/providers).

For a complete workflow, follow [cache product prices](/guides/caching/cache-product-prices).

## Public imports

- `@relkit/redis` — 14 exports
- `@relkit/redis/runtime` — 11 exports
- `@relkit/redis/local-recipe` — 1 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                     | Kind  | Import from                  | Example                                                                                                                           |
| ------------------------------------------------------------------------------------------------------- | ----- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [assertRedisOptions](/docs/api/integrations/redis#assertredisoptions)                                   | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [createRedisAgentStateProvider](/docs/api/integrations/redis#createredisagentstateprovider)             | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/redis-state-acceptance.ts#L13)                     |
| [createRedisCacheProvider](/docs/api/integrations/redis#createrediscacheprovider)                       | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/redis.test.ts#L13)                                   |
| [createRedisClient](/docs/api/integrations/redis#createredisclient)                                     | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L63)                 |
| [createRedisRealtimeProvider](/docs/api/integrations/redis#createredisrealtimeprovider)                 | Value | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/packed-consumer/packed-mixed-redis.fixture.ts#L78) |
| [localRecipe](/docs/api/integrations/redis#localrecipe)                                                 | Value | `@relkit/redis/local-recipe` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L145)                |
| [redis](/docs/api/integrations/redis#redis)                                                             | Value | `@relkit/redis`              | [API example](/docs/api/integrations/redis#redis)                                                                                 |
| [RedisAdapter](/docs/api/integrations/redis#redisadapter-type-alias)                                    | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisAgentState](/docs/api/integrations/redis#redisagentstate)                                         | Value | `@relkit/redis`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/agents.ts#L9)                               |
| [RedisAgentStateAdapter](/docs/api/integrations/redis#redisagentstateadapter-type-alias)                | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisAgentStateProviderOptions](/docs/api/integrations/redis#redisagentstateprovideroptions-interface) | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisBehavior](/docs/api/integrations/redis#redisbehavior-type-alias)                                  | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisCacheOptions](/docs/api/integrations/redis#rediscacheoptions-interface)                           | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisCacheProvider](/docs/api/integrations/redis#rediscacheprovider-interface)                         | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisClientOptions](/docs/api/integrations/redis#redisclientoptions-interface)                         | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisConnection](/docs/api/integrations/redis#redisconnection-type-alias)                              | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisConnectionContract](/docs/api/integrations/redis#redisconnectioncontract)                         | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisIntegration](/docs/api/integrations/redis#redisintegration)                                       | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [redisLocalRecipe](/docs/api/integrations/redis#redislocalrecipe)                                       | Value | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisOptions](/docs/api/integrations/redis#redisoptions-interface)                                     | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisProtocolClient](/docs/api/integrations/redis#redisprotocolclient-interface)                       | Type  | `@relkit/redis/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/redis.test.ts#L32)                                   |
| [redisRealtime](/docs/api/integrations/redis#redisrealtime)                                             | Value | `@relkit/redis`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/agents.ts#L8)                               |
| [RedisRealtimeAdapter](/docs/api/integrations/redis#redisrealtimeadapter-type-alias)                    | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisRealtimeProviderOptions](/docs/api/integrations/redis#redisrealtimeprovideroptions-interface)     | Type  | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |
| [RedisUrlReference](/docs/api/integrations/redis#redisurlreference-type-alias)                          | Type  | `@relkit/redis`              | [Module example](/docs/modules/integrations)                                                                                      |
| [runtimeIntegration](/docs/api/integrations/redis#runtimeintegration)                                   | Value | `@relkit/redis/runtime`      | [Module example](/docs/modules/integrations)                                                                                      |

## `index.ts`

### "./realtime.js" (namespace export)

Re-exports all named exports from the "./realtime.js" module.

**Signature**

```ts
export * from "./realtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/index.ts#L2)

### "./redis.js" (namespace export)

Re-exports all named exports from the "./redis.js" module.

**Signature**

```ts
export * from "./redis.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/index.ts#L1)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 1;
  integrationId: "redis";
  recipeId: "redis-docker";
  recipeVersion: 1;
  materializerId: "docker";
  image: "redis:7.4.2-alpine@sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952";
  command: ReadonlyArray<string>;
  ports: Readonly<{ redis: 6379 }>;
  volume: Readonly<{ mountPath: "/data" }>;
  health: Readonly<{
    command: ReadonlyArray<string>;
    intervalMs: 250;
    timeoutMs: 2000;
    retries: 40;
  }>;
  outputs: ({
    ports,
  }: LocalServiceRecipeOutputContext) => Readonly<{ url: `redis://127.0.0.1:${number}` }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/local-recipe/index.ts#L10)

## `realtime.ts`

### RedisAgentStateAdapter (type alias)

**Signature**

```ts
type RedisAgentStateAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof agentState,
  "redis-agent-state",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L28)

### RedisRealtimeAdapter (type alias)

**Signature**

```ts
type RedisRealtimeAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof realtime,
  "redis-realtime",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L21)

### redisAgentState

**Signature**

```ts
declare const redisAgentState: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisAgentStateAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L41)

### redisRealtime

**Signature**

```ts
declare const redisRealtime: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisRealtimeAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/realtime.ts#L35)

## `redis.ts`

### redis

Defines a Redis-compatible cache adapter. Omit `url` for a deferred local or infrastructure source.

**Example**

```ts
import { env } from "@relkit/app/config";
import { redis } from "@relkit/redis";
const cache = redis({ url: env.secret("CACHE_URL") });
```

**Signature**

```ts
declare const redis: <
  const Options extends RedisOptions = RedisOptions<RedisUrlReference<string> | undefined>,
>(
  options?: Options,
) => RedisAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L67)

Since v0.2.0

### RedisAdapter (type alias)

**Signature**

```ts
type RedisAdapter<Options extends RedisOptions = RedisOptions> = ProviderAdapter<
  typeof cache,
  "redis",
  RedisConnection<Options>,
  ProviderBehavior<RedisBehavior<Options>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L48)

### RedisBehavior (type alias)

**Signature**

```ts
type RedisBehavior<Options extends RedisOptions> = Options extends {
  readonly connectionTimeoutMs: infer Timeout extends number;
}
  ? Readonly<{ connectionTimeoutMs: Timeout }>
  : Readonly<Record<never, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L42)

### RedisConnection (type alias)

**Signature**

```ts
type RedisConnection<Options extends RedisOptions> = Options extends {
  readonly url: infer Url extends RedisUrlReference;
}
  ? Readonly<{ url: Url }>
  : Readonly<Record<never, never>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L36)

### RedisOptions (interface)

**Signature**

```ts
export interface RedisOptions<
  Url extends RedisUrlReference | undefined = RedisUrlReference | undefined,
> {
  readonly url?: Url;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L29)

### RedisUrlReference (type alias)

**Signature**

```ts
type RedisUrlReference<Name extends string = string> = BindingValueRef<
  Name,
  string,
  "secret-string"
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L23)

### assertRedisOptions

**Signature**

```ts
declare const assertRedisOptions: (options: RedisOptions) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L88)

### redisConnectionContract

**Signature**

```ts
declare const redisConnectionContract: ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L18)

### redisIntegration

**Signature**

```ts
declare const redisIntegration: IntegrationReference<"redis">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L16)

### redisLocalRecipe

**Signature**

```ts
declare const redisLocalRecipe: ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/redis.ts#L21)

## `agent-state-provider.ts`

Binds the native Redis transaction adapter to the generic agent-state provider contract.

### RedisAgentStateProviderOptions (interface)

**Signature**

```ts
export interface RedisAgentStateProviderOptions {
  readonly url: string;
  readonly profile: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/agent-state-provider.ts#L14)

### createRedisAgentStateProvider

**Signature**

```ts
declare const createRedisAgentStateProvider: (
  options: RedisAgentStateProviderOptions,
) => AgentStateProvider & { ready(): Promise<void>; close(): Promise<void> };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/agent-state-provider.ts#L20)

## `client.ts`

Owns the native Redis connection; a later operation can reconnect without replaying failed commands.

### RedisClientOptions (interface)

Owns the native Redis connection; a later operation can reconnect without replaying failed commands.

**Signature**

```ts
export interface RedisClientOptions {
  readonly url: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L2)

### RedisProtocolClient (interface)

**Signature**

```ts
export interface RedisProtocolClient {
  readonly connected: boolean;
  connect(): Promise<void>;
  close(): void;
  ping(): Promise<boolean>;
  get(key: string): Promise<string | null>;
  set(key: string, value: string, ttlMs?: number): Promise<void>;
  delete(key: string): Promise<number>;
  has(key: string): Promise<boolean>;
  increment(key: string, amount?: number): Promise<number>;
  scan(
    cursor: string,
    pattern: string,
    count: number,
  ): Promise<readonly [string, readonly string[]]>;
  type(key: string): Promise<string>;
  ttl(key: string): Promise<number>;
  command(command: string, args: readonly string[]): Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L7)

### createRedisClient

Creates a protocol client whose next connection attempt replaces a failed native socket.

**Signature**

```ts
declare const createRedisClient: (options: RedisClientOptions) => RedisProtocolClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/client.ts#L30)

## `index.ts`

### "./agent-state-provider.js" (namespace export)

Re-exports all named exports from the "./agent-state-provider.js" module.

**Signature**

```ts
export * from "./agent-state-provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L9)

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L6)

### "./provider.js" (namespace export)

Re-exports all named exports from the "./provider.js" module.

**Signature**

```ts
export * from "./provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L7)

### "./realtime-provider.js" (namespace export)

Re-exports all named exports from the "./realtime-provider.js" module.

**Signature**

```ts
export * from "./realtime-provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L8)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "redis";
  registrations: ReadonlyArray<
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: RedisCacheProvider;
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: RealtimeProvider & { ready(): Promise<void>; close(): Promise<void> };
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
    | {
        capability: string;
        adapterId: string;
        protocolVersion: number;
        create: ({ profile, connection, behavior }: RuntimeProviderContext) => {
          value: AgentStateProvider & { ready(): Promise<void>; close(): Promise<void> };
          ready: () => Promise<void>;
          release: () => Promise<void>;
        };
      }
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/index.ts#L11)

## `provider.ts`

### RedisCacheOptions (interface)

**Signature**

```ts
export interface RedisCacheOptions {
  readonly url: string;
  readonly cacheId: string;
  readonly connectionTimeoutMs?: number;
  readonly client?: RedisProtocolClient;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L5)

### RedisCacheProvider (interface)

**Signature**

```ts
export interface RedisCacheProvider extends CacheProvider {
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
  readonly inspector: {
    readonly scan: (request: {
      readonly search?: string;
      readonly cursor?: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<{ readonly items: readonly unknown[]; readonly nextCursor?: string }>;
    readonly value: (request: {
      readonly key: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<unknown | undefined>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L12)

### createRedisCacheProvider

**Signature**

```ts
declare const createRedisCacheProvider: (options: RedisCacheOptions) => RedisCacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/provider.ts#L30)

## `realtime-provider.ts`

### RedisRealtimeProviderOptions (interface)

**Signature**

```ts
export interface RedisRealtimeProviderOptions {
  readonly url: string;
  readonly profile: string;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/realtime-provider.ts#L9)

### createRedisRealtimeProvider

**Signature**

```ts
declare const createRedisRealtimeProvider: (
  options: RedisRealtimeProviderOptions,
) => RealtimeProvider & { ready(): Promise<void>; close(): Promise<void> };
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/realtime-provider.ts#L15)

## `state-store.ts`

### RedisAgentStore (type alias)

**Signature**

```ts
type RedisAgentStore = AgentStateStore & RedisStateWaiter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L28)

### RedisRealtimeStore (type alias)

**Signature**

```ts
type RedisRealtimeStore = RealtimeStateStore & RedisStateWaiter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L27)

### RedisStateStoreOptions (interface)

**Signature**

```ts
export interface RedisStateStoreOptions<State> {
  readonly url: string;
  readonly key: string;
  readonly empty: () => State;
  readonly valid: (state: unknown) => state is State;
  readonly connectionTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L9)

### RedisStateWaiter (interface)

**Signature**

```ts
export interface RedisStateWaiter {
  waitForChange(
    recheck: () => Promise<boolean>,
    deadlineMs: number,
    signal: AbortSignal,
  ): Promise<void>;
  ready(): Promise<void>;
  close(): Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L17)

### createRedisAgentStore

**Signature**

```ts
declare const createRedisAgentStore: (
  options: RedisStateStoreOptions<LocalAgentState>,
) => RedisAgentStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L45)

### createRedisRealtimeStore

**Signature**

```ts
declare const createRedisRealtimeStore: (
  options: RedisStateStoreOptions<LocalRealtimeState>,
) => RedisRealtimeStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/runtime/state-store.ts#L30)

---

# S3 API
Source: https://relkit.dev/docs/api/integrations/s3

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [integrations](/docs/modules/integrations), [local docker](/docs/modules/integrations/local-docker), [providers](/docs/modules/deployment/providers).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/s3` — 5 exports
- `@relkit/s3/runtime` — 5 exports
- `@relkit/s3/local-recipe` — 1 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                              | Kind  | Import from               | Example                                                                                                            |
| -------------------------------------------------------------------------------- | ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [createS3BucketProvider](/docs/api/integrations/s3#creates3bucketprovider)       | Value | `@relkit/s3/runtime`      | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/s3.test.ts#L9)                        |
| [localRecipe](/docs/api/integrations/s3#localrecipe)                             | Value | `@relkit/s3/local-recipe` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/local-docker-services.test.ts#L145) |
| [runtimeIntegration](/docs/api/integrations/s3#runtimeintegration)               | Value | `@relkit/s3/runtime`      | [Module example](/docs/modules/integrations)                                                                       |
| [s3](/docs/api/integrations/s3#s3)                                               | Value | `@relkit/s3`              | [API example](/docs/api/integrations/s3#s3)                                                                        |
| [S3Adapter](/docs/api/integrations/s3#s3adapter-type-alias)                      | Type  | `@relkit/s3`              | [Module example](/docs/modules/integrations)                                                                       |
| [S3Behavior](/docs/api/integrations/s3#s3behavior-type-alias)                    | Type  | `@relkit/s3`              | [Module example](/docs/modules/integrations)                                                                       |
| [S3BucketOptions](/docs/api/integrations/s3#s3bucketoptions-interface)           | Type  | `@relkit/s3/runtime`      | [Module example](/docs/modules/integrations)                                                                       |
| [S3BucketProvider](/docs/api/integrations/s3#s3bucketprovider-interface)         | Type  | `@relkit/s3/runtime`      | [Module example](/docs/modules/integrations)                                                                       |
| [S3Credentials](/docs/api/integrations/s3#s3credentials-interface)               | Type  | `@relkit/s3/runtime`      | [Module example](/docs/modules/integrations)                                                                       |
| [S3CredentialsOptions](/docs/api/integrations/s3#s3credentialsoptions-interface) | Type  | `@relkit/s3`              | [Module example](/docs/modules/integrations)                                                                       |
| [S3Options](/docs/api/integrations/s3#s3options-interface)                       | Type  | `@relkit/s3`              | [Module example](/docs/modules/integrations)                                                                       |

## `index.ts`

### "./s3.js" (namespace export)

Re-exports all named exports from the "./s3.js" module.

**Signature**

```ts
export * from "./s3.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/index.ts#L1)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 1;
  integrationId: "s3";
  recipeId: "minio-docker";
  recipeVersion: 1;
  materializerId: "docker";
  image: "ghcr.io/teableio/minio@sha256:a1ea29fa28355559ef137d71fc570e508a214ec84ff8083e39bc5428980b015e";
  command: ReadonlyArray<string>;
  ports: Readonly<{ api: 9000; console: 9001 }>;
  volume: Readonly<{ mountPath: "/data" }>;
  health: Readonly<{
    command: ReadonlyArray<string>;
    intervalMs: 500;
    timeoutMs: 2000;
    retries: 60;
  }>;
  generatedSecrets: Readonly<{
    accessKeyId: Readonly<{ bytes: 12 }>;
    secretAccessKey: Readonly<{ bytes: 24 }>;
  }>;
  environment: Readonly<{
    MINIO_ROOT_USER: Readonly<{ secret: "accessKeyId" }>;
    MINIO_ROOT_PASSWORD: Readonly<{ secret: "secretAccessKey" }>;
  }>;
  outputs: (context: LocalServiceRecipeOutputContext) => Readonly<{
    readonly endpoint: `http://127.0.0.1:${number}`;
    readonly bucketName: "relkit";
    readonly region: "us-east-1";
    readonly accessKeyId: string;
    readonly secretAccessKey: string;
  }>;
  initialize: (context: LocalServiceRecipeOutputContext) => Promise<void>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/local-recipe/index.ts#L14)

## `index.ts`

### "./s3.js" (namespace export)

Re-exports all named exports from the "./s3.js" module.

**Signature**

```ts
export * from "./s3.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/index.ts#L4)

### S3Credentials

**Signature**

```ts
declare const S3Credentials: S3Credentials;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/index.ts#L5)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "s3";
  registrations: ReadonlyArray<{
    capability: string;
    adapterId: string;
    protocolVersion: number;
    create: ({ connection, behavior }: RuntimeProviderContext) => { value: S3BucketProvider };
  }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/index.ts#L7)

## `s3-url.ts`

### endpointFor

**Signature**

```ts
declare const endpointFor: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-url.ts#L18)

### objectUrl

**Signature**

```ts
declare const objectUrl: (
  endpoint: string,
  bucket: string,
  key: string,
  pathStyle: boolean,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-url.ts#L1)

### requiredText

**Signature**

```ts
declare const requiredText: (value: unknown, label: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-url.ts#L27)

## `s3-xml.ts`

### decodeS3Xml

**Signature**

```ts
declare const decodeS3Xml: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-xml.ts#L1)

### s3ErrorDetail

**Signature**

```ts
declare const s3ErrorDetail: (body: string) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-xml.ts#L9)

### s3XmlValue

**Signature**

```ts
declare const s3XmlValue: (xml: string, name: string) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3-xml.ts#L5)

## `s3.ts`

### S3BucketOptions (interface)

**Signature**

```ts
export interface S3BucketOptions {
  readonly endpoint: string;
  readonly bucketName: string;
  readonly region: string;
  readonly credentials?: S3Credentials;
  readonly forcePathStyle?: boolean;
  readonly signedUrlTtlSeconds?: number;
  readonly fetch?: typeof globalThis.fetch;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3.ts#L12)

### S3BucketProvider (interface)

**Signature**

```ts
export interface S3BucketProvider extends BucketProvider {
  readonly inspector: {
    readonly list: (request: {
      readonly prefix?: string;
      readonly cursor?: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<{ readonly items: readonly unknown[]; readonly nextCursor?: string }>;
    readonly preview: (request: {
      readonly key: string;
      readonly offset: number;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<
      | { readonly bytes: Uint8Array; readonly metadata: unknown; readonly totalBytes: number }
      | undefined
    >;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3.ts#L22)

### createS3BucketProvider

**Signature**

```ts
declare const createS3BucketProvider: (options: S3BucketOptions) => S3BucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/s3.ts#L41)

## `signing.ts`

### S3Credentials (interface)

**Signature**

```ts
export interface S3Credentials {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
  readonly sessionToken?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L2)

### SignedRequestInit (type alias)

**Signature**

```ts
type SignedRequestInit = Omit<RequestInit, "body"> & {
  readonly body?: string | Uint8Array | null;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L8)

### SignedRequestOptions (interface)

**Signature**

```ts
export interface SignedRequestOptions {
  readonly region: string;
  readonly credentials?: S3Credentials;
  readonly fetch?: typeof globalThis.fetch;
  readonly init?: SignedRequestInit;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L12)

### assertResponse

**Signature**

```ts
declare const assertResponse: (response: Response, operation: string) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L104)

### presignS3Url

**Signature**

```ts
declare const presignS3Url: (
  url: string,
  method: "GET" | "PUT",
  region: string,
  expiresSeconds: number,
  options?: Pick<SignedRequestOptions, "credentials" | "fetch">,
) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L35)

### signedRequest

**Signature**

```ts
declare const signedRequest: (url: string, options: SignedRequestOptions) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/runtime/signing.ts#L19)

## `s3.ts`

### s3

Defines an S3-compatible bucket adapter. Omit connection fields for local or infrastructure use.

**Example**

```ts
import { s3 } from "@relkit/s3";
const assets = s3({
  endpoint: "https://s3.example.com",
  bucketName: "assets",
  region: "us-east-1",
});
```

**Signature**

```ts
declare const s3: (options?: S3Options) => S3Adapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/s3.ts#L81)

Since v0.2.0

### S3Adapter (type alias)

**Signature**

```ts
type S3Adapter = ProviderAdapter<
  typeof bucket,
  "s3",
  ProviderConnectionValues,
  ProviderBehavior<S3Behavior>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/s3.ts#L63)

### S3Behavior (type alias)

**Signature**

```ts
type S3Behavior = Readonly<{
  forcePathStyle: boolean;
  signedUrlTtlSeconds: number;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/s3.ts#L58)

### S3CredentialsOptions (interface)

**Signature**

```ts
export interface S3CredentialsOptions {
  readonly accessKeyId: SecretReference;
  readonly secretAccessKey: SecretReference;
  readonly sessionToken?: SecretReference;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/s3.ts#L43)

### S3Options (interface)

**Signature**

```ts
export interface S3Options {
  readonly endpoint?: string | URL | TextReference | UrlReference;
  readonly bucketName?: string | TextReference;
  readonly region?: string | TextReference;
  readonly credentials?: S3CredentialsOptions;
  readonly forcePathStyle?: boolean;
  readonly signedUrlTtlSeconds?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/s3.ts#L49)

---

# Sentry API
Source: https://relkit.dev/docs/api/integrations/sentry

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [observability](/docs/modules/operations/observability).

## Public imports

- `@relkit/sentry` — 3 exports
- `@relkit/sentry/runtime` — 7 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                         | Kind  | Import from              | Example                                                                                                   |
| ------------------------------------------------------------------------------------------- | ----- | ------------------------ | --------------------------------------------------------------------------------------------------------- |
| [createSentryExporter](/docs/api/integrations/sentry#createsentryexporter)                  | Value | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [createTelemetryExporter](/docs/api/integrations/sentry#createtelemetryexporter)            | Value | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [runtimeIntegration](/docs/api/integrations/sentry#runtimeintegration)                      | Value | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [sentry](/docs/api/integrations/sentry#sentry)                                              | Value | `@relkit/sentry`         | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/landing/telemetry.ts#L12) |
| [SentryExporter](/docs/api/integrations/sentry#sentryexporter-interface)                    | Type  | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [SentryExporterOptions](/docs/api/integrations/sentry#sentryexporteroptions-interface)      | Type  | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [SentryOptions](/docs/api/integrations/sentry#sentryoptions-interface)                      | Type  | `@relkit/sentry`         | [Module example](/docs/modules/operations/observability)                                                  |
| [SentryScope](/docs/api/integrations/sentry#sentryscope-interface)                          | Type  | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [SentrySdk](/docs/api/integrations/sentry#sentrysdk-interface)                              | Type  | `@relkit/sentry/runtime` | [Module example](/docs/modules/operations/observability)                                                  |
| [SentryTelemetryExporter](/docs/api/integrations/sentry#sentrytelemetryexporter-type-alias) | Type  | `@relkit/sentry`         | [Module example](/docs/modules/operations/observability)                                                  |

## `index.ts`

### "./sentry.js" (namespace export)

Re-exports all named exports from the "./sentry.js" module.

**Signature**

```ts
export * from "./sentry.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/index.ts#L1)

## `exporter.ts`

### SentryExporter (interface)

**Signature**

```ts
export interface SentryExporter {
  readonly exportRecord: (record: RedactedObservabilityRecord) => void;
  readonly flush: (timeoutMs?: number) => Promise<boolean>;
  readonly close: (timeoutMs?: number) => Promise<boolean>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L28)

### SentryExporterOptions (interface)

**Signature**

```ts
export interface SentryExporterOptions {
  readonly dsn: string;
  readonly environment?: string;
  readonly release?: string;
  readonly sdk?: SentrySdk;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L8)

### SentryScope (interface)

**Signature**

```ts
export interface SentryScope {
  readonly setTag: (name: string, value: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L15)

### SentrySdk (interface)

**Signature**

```ts
export interface SentrySdk {
  readonly init: (options: Readonly<Record<string, unknown>>) => void;
  readonly withScope: (callback: (scope: SentryScope) => void) => void;
  readonly captureException: (error: Error) => unknown;
  readonly captureEvent: (event: Readonly<Record<string, unknown>>) => unknown;
  readonly flush: (timeout?: number) => Promise<boolean>;
  readonly close: (timeout?: number) => Promise<boolean>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L19)

### createSentryExporter

**Signature**

```ts
declare const createSentryExporter: (options: SentryExporterOptions) => Promise<SentryExporter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L34)

### createTelemetryExporter

**Signature**

```ts
declare const createTelemetryExporter: (
  context: TelemetryExporterFactoryContext,
) => Promise<TelemetryExporterRuntime>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/exporter.ts#L76)

## `index.ts`

### "./exporter.js" (namespace export)

Re-exports all named exports from the "./exporter.js" module.

**Signature**

```ts
export * from "./exporter.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/index.ts#L1)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: Readonly<{
  kind: "runtime-integration";
  integrationId: "sentry";
  registrations: ReadonlyArray<{ capability: string; adapterId: string; protocolVersion: number }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/runtime/index.ts#L3)

## `sentry.ts`

### SentryOptions (interface)

**Signature**

```ts
export interface SentryOptions {
  readonly dsn: TextInput;
  readonly environment?: TextInput;
  readonly release?: TextInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/sentry.ts#L13)

### SentryTelemetryExporter (type alias)

**Signature**

```ts
type SentryTelemetryExporter = TelemetryExporterDescriptor<"sentry", "sentry", SentryOptions>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/sentry.ts#L19)

### sentry

Declares one statically loaded Sentry telemetry exporter.

**Signature**

```ts
declare const sentry: (options: SentryOptions) => SentryTelemetryExporter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/sentry/src/sentry.ts#L26)

---

# Trigger.dev API
Source: https://relkit.dev/docs/api/integrations/trigger

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [docker](/docs/modules/jobs/docker), [providers](/docs/modules/jobs/providers).

## Public imports

- `@relkit/trigger` — 7 exports
- `@relkit/trigger/runtime` — 22 exports
- `@relkit/trigger/local-recipe` — 1 exports
- `@relkit/trigger/deployment` — 4 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                           | Kind  | Import from                    | Example                                                                                                               |
| ------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [createTriggerHttpClient](/docs/api/integrations/trigger#createtriggerhttpclient)                             | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [createTriggerRuntime](/docs/api/integrations/trigger#createtriggerruntime)                                   | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [createTriggerTask](/docs/api/integrations/trigger#createtriggertask)                                         | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [createTriggerTaskConfig](/docs/api/integrations/trigger#createtriggertaskconfig)                             | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [createTriggerWorker](/docs/api/integrations/trigger#createtriggerworker)                                     | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [deploymentProfile](/docs/api/integrations/trigger#deploymentprofile)                                         | Value | `@relkit/trigger/deployment`   | [Module example](/docs/modules/jobs/docker)                                                                           |
| [loadTriggerSdk](/docs/api/integrations/trigger#loadtriggersdk)                                               | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [localRecipe](/docs/api/integrations/trigger#localrecipe-1)                                                   | Value | `@relkit/trigger/local-recipe` | [Module example](/docs/modules/jobs/docker)                                                                           |
| [nativeWorkerPublication](/docs/api/integrations/trigger#nativeworkerpublication)                             | Value | `@relkit/trigger/deployment`   | [Module example](/docs/modules/jobs/docker)                                                                           |
| [observeTriggerRun](/docs/api/integrations/trigger#observetriggerrun)                                         | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [runtimeIntegration](/docs/api/integrations/trigger#runtimeintegration)                                       | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [statusOf](/docs/api/integrations/trigger#statusof-1)                                                         | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [trigger](/docs/api/integrations/trigger#trigger)                                                             | Value | `@relkit/trigger`              | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/providers/trigger-config.ts#L12) |
| [TriggerAdapter](/docs/api/integrations/trigger#triggeradapter-type-alias)                                    | Type  | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerBehavior](/docs/api/integrations/trigger#triggerbehavior-type-alias)                                  | Type  | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [triggerConnectionContract](/docs/api/integrations/trigger#triggerconnectioncontract)                         | Value | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerDeploymentProfile](/docs/api/integrations/trigger#triggerdeploymentprofile-interface)                 | Type  | `@relkit/trigger/deployment`   | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerHttpClientOptions](/docs/api/integrations/trigger#triggerhttpclientoptions-interface)                 | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [triggerIntegration](/docs/api/integrations/trigger#triggerintegration)                                       | Value | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [triggerLocalRecipe](/docs/api/integrations/trigger#triggerlocalrecipe)                                       | Value | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerNativeClient](/docs/api/integrations/trigger#triggernativeclient-interface)                           | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerObservationOptions](/docs/api/integrations/trigger#triggerobservationoptions-interface)               | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerOptions](/docs/api/integrations/trigger#triggeroptions-interface)                                     | Type  | `@relkit/trigger`              | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerRuntime](/docs/api/integrations/trigger#triggerruntime-interface)                                     | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerRuntimeOptions](/docs/api/integrations/trigger#triggerruntimeoptions-interface)                       | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerSdk](/docs/api/integrations/trigger#triggersdk-interface)                                             | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerSdkApi](/docs/api/integrations/trigger#triggersdkapi-interface)                                       | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [triggerSnapshot](/docs/api/integrations/trigger#triggersnapshot-1)                                           | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerSubscription](/docs/api/integrations/trigger#triggersubscription-interface)                           | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerTaskDefinition](/docs/api/integrations/trigger#triggertaskdefinition-interface)                       | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [triggerTaskIdentifier](/docs/api/integrations/trigger#triggertaskidentifier-1)                               | Value | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerWorkerHandle](/docs/api/integrations/trigger#triggerworkerhandle-interface)                           | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerWorkerPublication](/docs/api/integrations/trigger#triggerworkerpublication-interface)                 | Type  | `@relkit/trigger/deployment`   | [Module example](/docs/modules/jobs/docker)                                                                           |
| [TriggerWorkerRegistrationOptions](/docs/api/integrations/trigger#triggerworkerregistrationoptions-interface) | Type  | `@relkit/trigger/runtime`      | [Module example](/docs/modules/jobs/docker)                                                                           |

## `index.ts`

### TriggerDeploymentProfile (interface)

**Signature**

```ts
export interface TriggerDeploymentProfile {
  readonly provider: "trigger";
  readonly compatibility: "unverified";
  readonly adapterId: "trigger";
  readonly sdk: "4.5.16";
  readonly dockerImageDigest: "sha256:3563088912cf4b880602d99815ddd787274c4ce5fc77738adf1e5bad287fbd1e";
  readonly dockerDurableSleep: false;
  readonly managedStatus: "not-tested";
  readonly scheduleVariants: readonly string[];
  readonly workerRuntime: "bun";
  readonly executionLimits: Readonly<{
    readonly inputBytes: number;
    readonly progressBytes: number;
    readonly maxRunList: number;
  }>;
  readonly policyIdentity: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/deployment/index.ts#L1)

### TriggerWorkerPublication (interface)

**Signature**

```ts
export interface TriggerWorkerPublication {
  readonly provider: "trigger";
  readonly mechanism: "trigger-sdk";
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly serviceGeneration: string;
  readonly entrypoint: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/deployment/index.ts#L19)

### deploymentProfile

**Signature**

```ts
declare const deploymentProfile: TriggerDeploymentProfile;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/deployment/index.ts#L29)

### nativeWorkerPublication

**Signature**

```ts
declare const nativeWorkerPublication: (
  value: Omit<TriggerWorkerPublication, "provider" | "mechanism">,
) => TriggerWorkerPublication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/deployment/index.ts#L50)

## `index.ts`

### TriggerAdapter (type alias)

**Signature**

```ts
type TriggerAdapter<Options extends TriggerOptions = TriggerOptions> = ProviderAdapter<
  typeof job,
  "trigger",
  ProviderConnectionValues,
  ProviderBehavior<TriggerBehavior>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L44)

### TriggerBehavior (type alias)

**Signature**

```ts
type TriggerBehavior = JobsServiceBehavior;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L43)

### TriggerOptions (interface)

**Signature**

```ts
export interface TriggerOptions extends JobsServiceOptions {
  readonly projectRef?: string | TextReference;
  readonly secretKey?: SecretReference;
  readonly baseUrl?: string | URL | TextReference;
  readonly native?: Readonly<Record<string, import("@relkit/contracts").JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L36)

### trigger

**Signature**

```ts
declare const trigger: <const Options extends TriggerOptions = TriggerOptions>(
  options?: Options,
) => TriggerAdapter<Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L55)

### triggerConnectionContract

**Signature**

```ts
declare const triggerConnectionContract: ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L52)

### triggerIntegration

**Signature**

```ts
declare const triggerIntegration: IntegrationReference<"trigger">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L51)

### triggerLocalRecipe

**Signature**

```ts
declare const triggerLocalRecipe: ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/index.ts#L53)

## `index.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "trigger";
  recipeId: "trigger-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    | Readonly<{
        id: "postgres";
        image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        environment: Readonly<{
          POSTGRES_DB: Readonly<{ value: "trigger" }>;
          POSTGRES_USER: Readonly<{ value: "trigger" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "trigger";
        image: "triggerdotdev/trigger.dev@sha256:3563088912cf4b880602d99815ddd787274c4ce5fc77738adf1e5bad287fbd1e";
        dependsOn: ReadonlyArray<string>;
        ports: Readonly<{ api: 8030 }>;
        health: Readonly<{
          command: Array<string>;
          intervalMs: 500;
          timeoutMs: 2000;
          retries: 120;
        }>;
        networkAliases: ReadonlyArray<string>;
        environment: Readonly<{
          DATABASE_URL: Readonly<{
            value: "postgres://trigger:$POSTGRES_PASSWORD@postgres:5432/trigger";
          }>;
          TRIGGER_ACCOUNT_FREE: Readonly<{ value: "1" }>;
          TRIGGER_PROJECT_REF: Readonly<{ secret: "projectRef" }>;
          TRIGGER_SECRET_KEY: Readonly<{ secret: "secretKey" }>;
        }>;
      }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 120 }>;
      networkAliases: ReadonlyArray<string>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{
    postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }>;
    projectRef: Readonly<{ bytes: 12; encoding: "hex" }>;
    secretKey: Readonly<{ bytes: 32; encoding: "hex" }>;
  }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({ ports, secrets }: LocalServiceRecipeOutputContext) => Readonly<{
    baseUrl: string;
    projectRef: string;
    secretKey: string;
  }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/local-recipe/index.ts#L1)

## `local.ts`

### localRecipe

**Signature**

```ts
declare const localRecipe: Readonly<{
  kind: "local-service-recipe";
  protocolVersion: 2;
  integrationId: "trigger";
  recipeId: "trigger-docker";
  recipeVersion: 2;
  materializerId: "docker";
  containers: ReadonlyArray<
    | Readonly<{
        id: "postgres";
        image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
        ports: Readonly<{}>;
        volumes: ReadonlyArray<{ name: string; mountPath: string }>;
        environment: Readonly<{
          POSTGRES_DB: Readonly<{ value: "trigger" }>;
          POSTGRES_USER: Readonly<{ value: "trigger" }>;
          POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }>;
        }>;
        health: Readonly<{ command: Array<string>; intervalMs: 250; timeoutMs: 2000; retries: 60 }>;
        networkAliases: ReadonlyArray<string>;
      }>
    | Readonly<{
        id: "trigger";
        image: "triggerdotdev/trigger.dev@sha256:3563088912cf4b880602d99815ddd787274c4ce5fc77738adf1e5bad287fbd1e";
        dependsOn: ReadonlyArray<string>;
        ports: Readonly<{ api: 8030 }>;
        health: Readonly<{
          command: Array<string>;
          intervalMs: 500;
          timeoutMs: 2000;
          retries: 120;
        }>;
        networkAliases: ReadonlyArray<string>;
        environment: Readonly<{
          DATABASE_URL: Readonly<{
            value: "postgres://trigger:$POSTGRES_PASSWORD@postgres:5432/trigger";
          }>;
          TRIGGER_ACCOUNT_FREE: Readonly<{ value: "1" }>;
          TRIGGER_PROJECT_REF: Readonly<{ secret: "projectRef" }>;
          TRIGGER_SECRET_KEY: Readonly<{ secret: "secretKey" }>;
        }>;
      }>
  >;
  init: ReadonlyArray<
    Readonly<{
      id: "postgres-ready";
      image: "postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685";
      dependsOn: ReadonlyArray<string>;
      command: ReadonlyArray<string>;
      environment: Readonly<{ POSTGRES_PASSWORD: Readonly<{ secret: "postgresPassword" }> }>;
    }>
  >;
  workers: ReadonlyArray<
    Readonly<{
      id: "worker";
      image: "oven/bun:1.3.10@sha256:b86c67b531d87b4db11470d9b2bd0c519b1976eee6fcd71634e73abfa6230d2e";
      command: ReadonlyArray<string>;
      dependsOn: ReadonlyArray<string>;
      ports: Readonly<{ api: 3000 }>;
      health: Readonly<{ command: Array<string>; intervalMs: 500; timeoutMs: 2000; retries: 120 }>;
      networkAliases: ReadonlyArray<string>;
    }>
  >;
  volumes: Readonly<{
    postgres: Readonly<{ mountPath: "/var/lib/postgresql/data"; persistent: true }>;
  }>;
  generatedSecrets: Readonly<{
    postgresPassword: Readonly<{ bytes: 24; encoding: "hex" }>;
    projectRef: Readonly<{ bytes: 12; encoding: "hex" }>;
    secretKey: Readonly<{ bytes: 32; encoding: "hex" }>;
  }>;
  network: Readonly<{ internal: false }>;
  ownership: Readonly<{ scope: "project"; retainVolumes: true }>;
  outputs: ({ ports, secrets }: LocalServiceRecipeOutputContext) => Readonly<{
    baseUrl: string;
    projectRef: string;
    secretKey: string;
  }>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/local.ts#L14)

## `index-support.ts`

### observationOptions

**Signature**

```ts
declare const observationOptions: (options: TriggerRuntimeOptions) => TriggerObservationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index-support.ts#L25)

### optionalText

**Signature**

```ts
declare const optionalText: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index-support.ts#L11)

### text

**Signature**

```ts
declare const text: (value: unknown, label: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index-support.ts#L6)

### unknown

**Signature**

```ts
declare const unknown: (value: NativeControlReceipt) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index-support.ts#L21)

### url

**Signature**

```ts
declare const url: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index-support.ts#L15)

## `index.ts`

### "./native.js" (namespace export)

Re-exports all named exports from the "./native.js" module.

**Signature**

```ts
export * from "./native.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L26)

### "./subscription.js" (namespace export)

Re-exports all named exports from the "./subscription.js" module.

**Signature**

```ts
export * from "./subscription.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L27)

### "./task-binding.js" (namespace export)

Re-exports all named exports from the "./task-binding.js" module.

**Signature**

```ts
export * from "./task-binding.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L28)

### TriggerRuntime (interface)

**Signature**

```ts
export interface TriggerRuntime extends JobsAdapterRuntime {
  readonly registerWorker: (options: TriggerWorkerRegistrationOptions) => TriggerWorkerHandle;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L50)

### TriggerRuntimeOptions (interface)

**Signature**

```ts
export interface TriggerRuntimeOptions {
  readonly projectRef: string;
  readonly secretKey?: string;
  readonly baseUrl: string;
  readonly fetch?: typeof globalThis.fetch;
  readonly native?: TriggerNativeClient;
  readonly sdk?: TriggerSdk;
  readonly supportsDurableSleep?: boolean;
  readonly pollIntervalMs?: number;
  readonly maxPolls?: number;
  readonly serviceOptions?: JobsServiceOptions;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L30)

### TriggerWorkerRegistrationOptions (interface)

**Signature**

```ts
export interface TriggerWorkerRegistrationOptions {
  readonly definitions: readonly TriggerTaskDefinition[];
  readonly executor: import("@relkit/jobs/adapter").TaskExecutor;
  readonly startWorker?: boolean;
  readonly register?: (tasks: readonly unknown[]) => Promise<void> | void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L43)

### createTriggerRuntime

**Signature**

```ts
declare const createTriggerRuntime: (options: TriggerRuntimeOptions) => TriggerRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L54)

### runtimeIntegration

**Signature**

```ts
declare const runtimeIntegration: RuntimeProviderIntegration<"trigger">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/index.ts#L172)

## `native.ts`

### TriggerHttpClientOptions (interface)

**Signature**

```ts
export interface TriggerHttpClientOptions {
  readonly baseUrl: string;
  readonly projectRef: string;
  readonly secretKey?: string;
  readonly fetch?: typeof globalThis.fetch;
  readonly client?: TriggerSdkApi;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L56)

### TriggerNativeClient (interface)

**Signature**

```ts
export interface TriggerNativeClient {
  readonly submit: (request: NativeSubmission, context: OperationContext) => Promise<NativeReceipt>;
  readonly get: (runId: string, context: OperationContext) => Promise<NativeRun>;
  readonly list: (query: NativeRunQuery, context: OperationContext) => Promise<NativeRunPage>;
  readonly cancel: (
    runId: string,
    operationId: string,
    reason: string | undefined,
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly retry: (
    request: NativeRetryRequest,
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly subscribeToRun?: (
    runId: string,
    context: OperationContext,
    after?: string,
  ) => Promise<TriggerSubscription | undefined>;
  readonly schedules?: NativeScheduleOperations;
  readonly registerTasks?: (tasks: readonly unknown[]) => Promise<void> | void;
  readonly close?: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L32)

### TriggerSdkApi (interface)

**Signature**

```ts
export interface TriggerSdkApi {
  readonly tasks: {
    readonly trigger: (...args: readonly unknown[]) => Promise<unknown>;
  };
  readonly runs: {
    readonly retrieve: (...args: readonly unknown[]) => Promise<unknown>;
    readonly list: (...args: readonly unknown[]) => Promise<unknown>;
    readonly cancel: (...args: readonly unknown[]) => Promise<unknown>;
    readonly replay: (...args: readonly unknown[]) => Promise<unknown>;
    readonly subscribeToRun: (...args: readonly unknown[]) => AsyncIterable<unknown>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L19)

### TriggerSubscription (interface)

**Signature**

```ts
export interface TriggerSubscription {
  readonly stream: AsyncIterable<unknown>;
  readonly unsubscribe?: () => Promise<void> | void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L14)

### createTriggerHttpClient

Compatibility name retained for callers; the implementation uses the pinned SDK.

**Signature**

```ts
declare const createTriggerHttpClient: (options: TriggerHttpClientOptions) => TriggerNativeClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L65)

### statusOf

**Signature**

```ts
declare const statusOf: (value: unknown) => RunSnapshot["status"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L69)

### triggerSnapshot

**Signature**

```ts
declare const triggerSnapshot: (
  value: unknown,
  context: OperationContext,
  fallbackRunId?: string,
) => NativeRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L69)

### triggerTaskIdentifier

**Signature**

```ts
declare const triggerTaskIdentifier: (
  request: Pick<NativeSubmission, "jobId" | "taskId" | "taskVersion" | "buildId">,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/native.ts#L70)

## `sdk-list.ts`

### listRuns

**Signature**

```ts
declare const listRuns: (
  client: TriggerSdkApi,
  projectRef: string,
  query: NativeRunQuery,
  context: OperationContext,
) => Promise<NativeRunPage>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-list.ts#L11)

## `sdk-mapping.ts`

### isJsonValue

**Signature**

```ts
declare const isJsonValue: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-mapping.ts#L107)

### record

**Signature**

```ts
declare const record: (value: unknown) => Record<string, any> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-mapping.ts#L116)

### statusOf

**Signature**

```ts
declare const statusOf: (value: unknown) => RunSnapshot["status"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-mapping.ts#L78)

### triggerSnapshot

**Signature**

```ts
declare const triggerSnapshot: (
  value: unknown,
  context: OperationContext,
  fallbackRunId?: string,
) => NativeRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-mapping.ts#L5)

## `sdk-native-support.ts`

### definiteRejection

**Signature**

```ts
declare const definiteRejection: (error: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L107)

### handle

**Signature**

```ts
declare const handle: (value: unknown, request: NativeSubmission) => RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L61)

### loadClient

**Signature**

```ts
declare const loadClient: (options: TriggerHttpClientOptions) => TriggerSdkApi;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L73)

### metadata

**Signature**

```ts
declare const metadata: (
  request: NativeSubmission,
  context: OperationContext,
) => Record<string, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L13)

### text

**Signature**

```ts
declare const text: (value: unknown, label: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L113)

### triggerOptions

**Signature**

```ts
declare const triggerOptions: (
  request: NativeSubmission,
  context: OperationContext,
) => Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L46)

### unknownControl

**Signature**

```ts
declare const unknownControl: (operationId: string) => JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L98)

### unknownSubmission

**Signature**

```ts
declare const unknownSubmission: (request: NativeSubmission) => JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native-support.ts#L89)

## `sdk-native.ts`

### createTriggerSdkNativeClient

**Signature**

```ts
declare const createTriggerSdkNativeClient: (
  options: TriggerHttpClientOptions,
) => TriggerNativeClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-native.ts#L29)

## `sdk-support.ts`

### triggerTaskIdentifier

**Signature**

```ts
declare const triggerTaskIdentifier: (
  request: Pick<NativeSubmission, "jobId" | "taskId" | "taskVersion" | "buildId">,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/sdk-support.ts#L3)

## `subscription.ts`

### TriggerObservationOptions (interface)

**Signature**

```ts
export interface TriggerObservationOptions {
  readonly pollIntervalMs?: number;
  readonly readTimeoutMs?: number;
  readonly maxPolls?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/subscription.ts#L44)

### observeTriggerRun

**Signature**

```ts
declare const observeTriggerRun: (
  request: NativeWatchRequest,
  context: OperationContext,
  client: TriggerNativeClient,
  options?: TriggerObservationOptions,
) => AsyncGenerator<NativeObservation>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/subscription.ts#L11)

## `task-binding-support.ts`

### bindingFrom

**Signature**

```ts
declare const bindingFrom: (
  envelope: TaskExecutionEnvelope,
  context: unknown,
) => TaskExecutionBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding-support.ts#L48)

### envelopeFrom

**Signature**

```ts
declare const envelopeFrom: (
  payload: unknown,
  context: unknown,
  definition: TriggerTaskDefinition,
) => TaskExecutionEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding-support.ts#L5)

### number

**Signature**

```ts
declare const number: (value: unknown) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding-support.ts#L135)

### record

**Signature**

```ts
declare const record: (value: unknown) => Record<string, any> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding-support.ts#L124)

### text

**Signature**

```ts
declare const text: (value: unknown, label: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding-support.ts#L130)

## `task-binding.ts`

### TriggerSdk (interface)

**Signature**

```ts
export interface TriggerSdk {
  readonly createTask?: (options: Readonly<Record<string, unknown>>) => unknown;
  readonly task?: (options: Readonly<Record<string, unknown>>) => unknown;
  readonly tasks?:
    ((options: Readonly<Record<string, unknown>>) => unknown) | Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L21)

### TriggerTaskDefinition (interface)

**Signature**

```ts
export interface TriggerTaskDefinition {
  readonly id: string;
  readonly jobId?: string;
  readonly taskId?: string;
  readonly version: string;
  readonly buildId: string;
  readonly retries?: number;
  readonly trigger?: Readonly<Record<string, unknown>>;
  readonly policy?: unknown;
  readonly resources?: {
    readonly cpu: number;
    readonly memory: string;
    readonly nativeClass?: string;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L5)

### TriggerWorkerHandle (interface)

**Signature**

```ts
export interface TriggerWorkerHandle {
  readonly tasks: readonly unknown[];
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L28)

### createTriggerTask

**Signature**

```ts
declare const createTriggerTask: (
  sdk: TriggerSdk,
  definition: TriggerTaskDefinition,
  executor: TaskExecutor,
) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L43)

### createTriggerTaskConfig

**Signature**

```ts
declare const createTriggerTaskConfig: (
  definition: TriggerTaskDefinition,
) => Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L60)

### createTriggerWorker

**Signature**

```ts
declare const createTriggerWorker: (options: {
  readonly sdk?: TriggerSdk;
  readonly definitions: readonly TriggerTaskDefinition[];
  readonly executor: TaskExecutor;
  readonly register?: (tasks: readonly unknown[]) => Promise<void> | void;
}) => TriggerWorkerHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L84)

### loadTriggerSdk

**Signature**

```ts
declare const loadTriggerSdk: () => TriggerSdk;
```

[Source](https://github.com/rel-kit/relkit/blob/main/integrations/packages/trigger/src/runtime/task-binding.ts#L34)

---

# Jobs API
Source: https://relkit.dev/docs/api/jobs

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineTask](/docs/api/jobs#definetask)
- [defineJob](/docs/api/jobs#definejob)

For configuration and examples, read [quickstart](/docs/modules/jobs/quickstart), [schedules](/docs/modules/jobs/schedules), [comparison](/docs/modules/jobs/providers/comparison).

## Frontend usage

[Trigger and observe a job](/docs/modules/jobs/clients#use-from-react) shows the client side of this capability.

## Public imports

- `@relkit/jobs` — 413 exports
- `@relkit/jobs/adapter` — 34 exports
- `@relkit/jobs/server` — 9 exports
- `@relkit/jobs/legacy` — 33 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                               | Kind  | Import from                            | Example                                                                                                                    |
| ------------------------------------------------------------------------------------------------- | ----- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| [assertAdapterMethods](/docs/api/jobs#assertadaptermethods)                                       | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#assertadaptermethods)                                                                         |
| [assertAdapterMethodsEffect](/docs/api/jobs#assertadaptermethodseffect)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertadaptermethodseffect)                                                                   |
| [assertAuthorizedOperation](/docs/api/jobs#assertauthorizedoperation)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertauthorizedoperation)                                                                    |
| [assertAuthorizedOperationEffect](/docs/api/jobs#assertauthorizedoperationeffect)                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertauthorizedoperationeffect)                                                              |
| [assertBoundedString](/docs/api/jobs#assertboundedstring)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertboundedstring)                                                                          |
| [assertBoundedStringEffect](/docs/api/jobs#assertboundedstringeffect)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertboundedstringeffect)                                                                    |
| [assertCanonicalScalarKey](/docs/api/jobs#assertcanonicalscalarkey)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertcanonicalscalarkey)                                                                     |
| [assertCanonicalScalarKeyEffect](/docs/api/jobs#assertcanonicalscalarkeyeffect)                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertcanonicalscalarkeyeffect)                                                               |
| [assertFieldName](/docs/api/jobs#assertfieldname)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertfieldname)                                                                              |
| [assertFieldNameEffect](/docs/api/jobs#assertfieldnameeffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertfieldnameeffect)                                                                        |
| [assertJobDescriptor](/docs/api/jobs#assertjobdescriptor)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobdescriptor)                                                                          |
| [assertJobDescriptorEffect](/docs/api/jobs#assertjobdescriptoreffect)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobdescriptoreffect)                                                                    |
| [assertJobGrant](/docs/api/jobs#assertjobgrant)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobgrant)                                                                               |
| [assertJobGrantEffect](/docs/api/jobs#assertjobgranteffect)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobgranteffect)                                                                         |
| [assertJobName](/docs/api/jobs#assertjobname-1)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobname-1)                                                                              |
| [assertJobNameEffect](/docs/api/jobs#assertjobnameeffect-1)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobnameeffect-1)                                                                        |
| [assertJobsAdapterRuntime](/docs/api/jobs#assertjobsadapterruntime)                               | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#assertjobsadapterruntime)                                                                     |
| [assertJobsAdapterRuntimeEffect](/docs/api/jobs#assertjobsadapterruntimeeffect)                   | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#assertjobsadapterruntimeeffect)                                                               |
| [assertJobsCapability](/docs/api/jobs#assertjobscapability-1)                                     | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#assertjobscapability-1)                                                                       |
| [assertJobsCapabilityEffect](/docs/api/jobs#assertjobscapabilityeffect)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertjobscapabilityeffect)                                                                   |
| [assertRfc3339Instant](/docs/api/jobs#assertrfc3339instant-1)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertrfc3339instant-1)                                                                       |
| [assertRfc3339InstantEffect](/docs/api/jobs#assertrfc3339instanteffect-1)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertrfc3339instanteffect-1)                                                                 |
| [assertSupportedJobsServiceOptions](/docs/api/jobs#assertsupportedjobsserviceoptions)             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertsupportedjobsserviceoptions)                                                            |
| [assertSupportedJobsServiceOptionsEffect](/docs/api/jobs#assertsupportedjobsserviceoptionseffect) | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#assertsupportedjobsserviceoptionseffect)                                                      |
| [assertTaskDescriptor](/docs/api/jobs#asserttaskdescriptor)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#asserttaskdescriptor)                                                                         |
| [assertTaskDescriptorEffect](/docs/api/jobs#asserttaskdescriptoreffect)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#asserttaskdescriptoreffect)                                                                   |
| [authorize](/docs/api/jobs#authorize)                                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#authorize)                                                                                    |
| [authorizeJobAccess](/docs/api/jobs#authorizejobaccess)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#authorizejobaccess)                                                                           |
| [authorizeJobAccessEffect](/docs/api/jobs#authorizejobaccesseffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#authorizejobaccesseffect)                                                                     |
| [BindingSource](/docs/api/jobs#bindingsource-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [cancelRun](/docs/api/jobs#cancelrun)                                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#cancelrun)                                                                                    |
| [cancelRunEffect](/docs/api/jobs#cancelruneffect)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#cancelruneffect)                                                                              |
| [CanonicalTaskSubmissionOptions](/docs/api/jobs#canonicaltasksubmissionoptions-interface)         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [copyConcurrency](/docs/api/jobs#copyconcurrency)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copyconcurrency)                                                                              |
| [copyConcurrencyEffect](/docs/api/jobs#copyconcurrencyeffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copyconcurrencyeffect)                                                                        |
| [copyLogging](/docs/api/jobs#copylogging)                                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copylogging)                                                                                  |
| [copyLoggingEffect](/docs/api/jobs#copyloggingeffect)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copyloggingeffect)                                                                            |
| [copyResources](/docs/api/jobs#copyresources)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copyresources)                                                                                |
| [copyResourcesEffect](/docs/api/jobs#copyresourceseffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copyresourceseffect)                                                                          |
| [copyTaskTags](/docs/api/jobs#copytasktags)                                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copytasktags)                                                                                 |
| [copyTaskTagsEffect](/docs/api/jobs#copytasktagseffect)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copytasktagseffect)                                                                           |
| [copyTriggerOptions](/docs/api/jobs#copytriggeroptions-1)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#copytriggeroptions-1)                                                                         |
| [createCursor](/docs/api/jobs#createcursor)                                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createcursor)                                                                                 |
| [createJobClient](/docs/api/jobs#createjobclient)                                                 | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#createjobclient)                                                                              |
| [createJobClientEffect](/docs/api/jobs#createjobclienteffect)                                     | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#createjobclienteffect)                                                                        |
| [createJobCursor](/docs/api/jobs#createjobcursor)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobcursor)                                                                              |
| [createJobCursorEffect](/docs/api/jobs#createjobcursoreffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobcursoreffect)                                                                        |
| [createJobsControls](/docs/api/jobs#createjobscontrols)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobscontrols)                                                                           |
| [createJobsControlsEffect](/docs/api/jobs#createjobscontrolseffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobscontrolseffect)                                                                     |
| [createJobsRuntime](/docs/api/jobs#createjobsruntime)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobsruntime)                                                                            |
| [createJobsRuntimeEffect](/docs/api/jobs#createjobsruntimeeffect)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createjobsruntimeeffect)                                                                      |
| [createRunLocator](/docs/api/jobs#createrunlocator)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createrunlocator)                                                                             |
| [createRunLocatorEffect](/docs/api/jobs#createrunlocatoreffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createrunlocatoreffect)                                                                       |
| [createScheduleControls](/docs/api/jobs#createschedulecontrols)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createschedulecontrols)                                                                       |
| [createScheduleControlsEffect](/docs/api/jobs#createschedulecontrolseffect)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createschedulecontrolseffect)                                                                 |
| [createSubmissionPipeline](/docs/api/jobs#createsubmissionpipeline)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createsubmissionpipeline)                                                                     |
| [createSubmissionPipelineEffect](/docs/api/jobs#createsubmissionpipelineeffect)                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createsubmissionpipelineeffect)                                                               |
| [createTaskProgressEmitter](/docs/api/jobs#createtaskprogressemitter)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createtaskprogressemitter)                                                                    |
| [createTaskProgressEmitterEffect](/docs/api/jobs#createtaskprogressemittereffect)                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createtaskprogressemittereffect)                                                              |
| [createTaskStreamEmitter](/docs/api/jobs#createtaskstreamemitter)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createtaskstreamemitter)                                                                      |
| [createTaskStreamEmitterEffect](/docs/api/jobs#createtaskstreamemittereffect)                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#createtaskstreamemittereffect)                                                                |
| [currentJobsRuntime](/docs/api/jobs#currentjobsruntime)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#currentjobsruntime)                                                                           |
| [currentJobsRuntimeEffect](/docs/api/jobs#currentjobsruntimeeffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#currentjobsruntimeeffect)                                                                     |
| [decodeCursor](/docs/api/jobs#decodecursor)                                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#decodecursor)                                                                                 |
| [decodeJobWire](/docs/api/jobs#decodejobwire)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#decodejobwire)                                                                                |
| [decodeJobWireEffect](/docs/api/jobs#decodejobwireeffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#decodejobwireeffect)                                                                          |
| [decodeRunLocator](/docs/api/jobs#decoderunlocator)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#decoderunlocator)                                                                             |
| [defineJob](/docs/api/jobs#definejob)                                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#definejob)                                                                                    |
| [defineJob](/docs/api/jobs#definejob-1)                                                           | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#definejob-1)                                                                                  |
| [defineJobEffect](/docs/api/jobs#definejobeffect)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#definejobeffect)                                                                              |
| [defineJobEffect](/docs/api/jobs#definejobeffect-1)                                               | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#definejobeffect-1)                                                                            |
| [DefineJobOptions](/docs/api/jobs#definejoboptions-type-alias)                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [DefineJobOptions](/docs/api/jobs#definejoboptions-interface)                                     | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [defineTask](/docs/api/jobs#definetask)                                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#definetask)                                                                                   |
| [defineTaskEffect](/docs/api/jobs#definetaskeffect)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#definetaskeffect)                                                                             |
| [DefineTaskOptions](/docs/api/jobs#definetaskoptions-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [deserializeJobsServiceOptions](/docs/api/jobs#deserializejobsserviceoptions)                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#deserializejobsserviceoptions)                                                                |
| [deserializeJobsServiceOptionsEffect](/docs/api/jobs#deserializejobsserviceoptionseffect)         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#deserializejobsserviceoptionseffect)                                                          |
| [diagnoseJobMigration](/docs/api/jobs#diagnosejobmigration)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#diagnosejobmigration)                                                                         |
| [diagnoseJobMigrationEffect](/docs/api/jobs#diagnosejobmigrationeffect)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#diagnosejobmigrationeffect)                                                                   |
| [diagnoseLegacyCompatibility](/docs/api/jobs#diagnoselegacycompatibility)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#diagnoselegacycompatibility)                                                                  |
| [diagnoseLegacyCompatibilityEffect](/docs/api/jobs#diagnoselegacycompatibilityeffect)             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#diagnoselegacycompatibilityeffect)                                                            |
| [DurationInput](/docs/api/jobs#durationinput-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [durationToMillis](/docs/api/jobs#durationtomillis)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#durationtomillis)                                                                             |
| [durationToMillisEffect](/docs/api/jobs#durationtomilliseffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#durationtomilliseffect)                                                                       |
| [DurationUnit](/docs/api/jobs#durationunit-type-alias)                                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [DurationValidationError](/docs/api/jobs#durationvalidationerror-class)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#durationvalidationerror-class)                                                                |
| [EffectJobClient](/docs/api/jobs#effectjobclient-interface)                                       | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [EffectTaskEmitter](/docs/api/jobs#effecttaskemitter-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [encodeJobWire](/docs/api/jobs#encodejobwire)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodejobwire)                                                                                |
| [encodeJobWireEffect](/docs/api/jobs#encodejobwireeffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodejobwireeffect)                                                                          |
| [encodeRunLocator](/docs/api/jobs#encoderunlocator)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encoderunlocator)                                                                             |
| [encodeTaskInput](/docs/api/jobs#encodetaskinput)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodetaskinput)                                                                              |
| [encodeTaskInputEffect](/docs/api/jobs#encodetaskinputeffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodetaskinputeffect)                                                                        |
| [encodeTaskOutput](/docs/api/jobs#encodetaskoutput)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodetaskoutput)                                                                             |
| [encodeTaskOutputEffect](/docs/api/jobs#encodetaskoutputeffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#encodetaskoutputeffect)                                                                       |
| [getRun](/docs/api/jobs#getrun)                                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#getrun)                                                                                       |
| [getRunEffect](/docs/api/jobs#getruneffect)                                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#getruneffect)                                                                                 |
| [getScheduleEffect](/docs/api/jobs#getscheduleeffect)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#getscheduleeffect)                                                                            |
| [IdempotencyDefinition](/docs/api/jobs#idempotencydefinition-interface)                           | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [InputOf](/docs/api/jobs#inputof-type-alias)                                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [InstantValidationError](/docs/api/jobs#instantvalidationerror-class)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#instantvalidationerror-class)                                                                 |
| [isDurationInput](/docs/api/jobs#isdurationinput)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isdurationinput)                                                                              |
| [isDurationInputEffect](/docs/api/jobs#isdurationinputeffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isdurationinputeffect)                                                                        |
| [isJobDescriptor](/docs/api/jobs#isjobdescriptor)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isjobdescriptor)                                                                              |
| [isJobDescriptorEffect](/docs/api/jobs#isjobdescriptoreffect)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isjobdescriptoreffect)                                                                        |
| [isJobName](/docs/api/jobs#isjobname-1)                                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isjobname-1)                                                                                  |
| [isJobNameEffect](/docs/api/jobs#isjobnameeffect-1)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isjobnameeffect-1)                                                                            |
| [isJobsAdapterRuntime](/docs/api/jobs#isjobsadapterruntime)                                       | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#isjobsadapterruntime)                                                                         |
| [isJobsAdapterRuntimeEffect](/docs/api/jobs#isjobsadapterruntimeeffect)                           | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#isjobsadapterruntimeeffect)                                                                   |
| [isRfc3339Instant](/docs/api/jobs#isrfc3339instant-1)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isrfc3339instant-1)                                                                           |
| [isRfc3339InstantEffect](/docs/api/jobs#isrfc3339instanteffect-1)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isrfc3339instanteffect-1)                                                                     |
| [isTaskDescriptor](/docs/api/jobs#istaskdescriptor)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#istaskdescriptor)                                                                             |
| [isTaskDescriptorEffect](/docs/api/jobs#istaskdescriptoreffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#istaskdescriptoreffect)                                                                       |
| [isValidJobName](/docs/api/jobs#isvalidjobname-1)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#isvalidjobname-1)                                                                             |
| [JOB_NAME_MAX_LENGTH](/docs/api/app#job_name_max_length)                                          | Value | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JOB_NAME_PATTERN](/docs/api/jobs#job_name_pattern-1)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#job_name_pattern-1)                                                                           |
| [JOB_NAME_RESERVED](/docs/api/jobs#job_name_reserved-1)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#job_name_reserved-1)                                                                          |
| [JOB_PROFILE_DEPRECATED_CODE](/docs/api/jobs#job_profile_deprecated_code)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#job_profile_deprecated_code)                                                                  |
| [JobAccessGrant](/docs/api/app#jobaccessgrant-interface)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobAccessRequest](/docs/api/app#jobaccessrequest-interface)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobAdmission](/docs/api/jobs#jobadmission-interface)                                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobAuthorizationContext](/docs/api/jobs#jobauthorizationcontext-interface)                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobAuthorizationError](/docs/api/jobs#jobauthorizationerror-class)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobauthorizationerror-class)                                                                  |
| [JobAuthorizationFailure](/docs/api/jobs#jobauthorizationfailure-class)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobauthorizationfailure-class)                                                                |
| [JobBindingErrorCode](/docs/api/jobs#jobbindingerrorcode-type-alias)                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobBindingFailure](/docs/api/jobs#jobbindingfailure-class)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobbindingfailure-class)                                                                      |
| [JobBindingMigration](/docs/api/jobs#jobbindingmigration-type-alias)                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobBindingResolutionError](/docs/api/jobs#jobbindingresolutionerror-class)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobbindingresolutionerror-class)                                                              |
| [JobCancelOptions](/docs/api/jobs#jobcanceloptions-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobClient](/docs/api/jobs#jobclient-interface)                                                   | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobClientAccess](/docs/api/jobs#jobclientaccess-type-alias)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobClientFailure](/docs/api/jobs#jobclientfailure-class)                                         | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#jobclientfailure-class)                                                                       |
| [JobClientField](/docs/api/jobs#jobclientfield-type-alias)                                        | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobClientOperation](/docs/api/app#jobclientoperation-type-alias)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobClientOptions](/docs/api/jobs#jobclientoptions-interface)                                     | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobControlFailure](/docs/api/jobs#jobcontrolfailure-class)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobcontrolfailure-class)                                                                      |
| [JobControlUnknownError](/docs/api/jobs#jobcontrolunknownerror-class)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobcontrolunknownerror-class)                                                                 |
| [JobCursorBinding](/docs/api/jobs#jobcursorbinding-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobCursorError](/docs/api/jobs#jobcursorerror-class)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobcursorerror-class)                                                                         |
| [JobCursorFailure](/docs/api/jobs#jobcursorfailure-class)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobcursorfailure-class)                                                                       |
| [JobCursorOptions](/docs/api/jobs#jobcursoroptions-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobDeclaredEdge](/docs/api/jobs#jobdeclarededge-interface)                                       | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobDefinitionFailure](/docs/api/jobs#jobdefinitionfailure-class)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobdefinitionfailure-class)                                                                   |
| [JobDependencyError](/docs/api/jobs#jobdependencyerror-class)                                     | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#jobdependencyerror-class)                                                                     |
| [JobDescriptor](/docs/api/jobs#jobdescriptor-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobDescriptor](/docs/api/jobs#jobdescriptor-interface)                                           | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobDescriptorAny](/docs/api/jobs#jobdescriptorany-type-alias)                                    | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L42)                 |
| [JobDescriptorForThisTask](/docs/api/jobs#jobdescriptorforthistask-type-alias)                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobEnqueueOptions](/docs/api/functions#jobenqueueoptions-interface)                              | Type  | `@relkit/jobs/legacy`                  | [API example](/docs/api/functions#jobenqueueoptions-interface)                                                             |
| [JobEnqueueResult](/docs/api/functions#jobenqueueresult-interface)                                | Type  | `@relkit/jobs/legacy`                  | [API example](/docs/api/functions#jobenqueueresult-interface)                                                              |
| [JobErrorEnvelope](/docs/api/app#joberrorenvelope-interface)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobIdentityError](/docs/api/jobs#jobidentityerror-class)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobidentityerror-class)                                                                       |
| [JobInputValidationError](/docs/api/jobs#jobinputvalidationerror-class)                           | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#jobinputvalidationerror-class)                                                                |
| [JobInvocationBridge](/docs/api/jobs#jobinvocationbridge-interface)                               | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobInvocationBridgeOptions](/docs/api/jobs#jobinvocationbridgeoptions-interface)                 | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobMigrationDiagnostic](/docs/api/jobs#jobmigrationdiagnostic-interface)                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobMigrationSeverity](/docs/api/jobs#jobmigrationseverity-type-alias)                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobMigrationSnapshot](/docs/api/jobs#jobmigrationsnapshot-interface)                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobName](/docs/api/jobs#jobname-type-alias)                                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobNameValidationError](/docs/api/jobs#jobnamevalidationerror-class)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobnamevalidationerror-class)                                                                 |
| [JobObservationTimeoutError](/docs/api/jobs#jobobservationtimeouterror-class)                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobobservationtimeouterror-class)                                                             |
| [JobObservedEdge](/docs/api/jobs#jobobservededge-interface)                                       | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobObserveOptions](/docs/api/jobs#jobobserveoptions-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobOperationCancelledError](/docs/api/jobs#joboperationcancellederror-class)                     | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#joboperationcancellederror-class)                                                             |
| [JobOperationContext](/docs/api/jobs#joboperationcontext-interface)                               | Type  | `@relkit/jobs/legacy`                  | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/client.test.ts#L26)                       |
| [JobOperationTimeoutError](/docs/api/jobs#joboperationtimeouterror-class)                         | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#joboperationtimeouterror-class)                                                               |
| [JobProfileError](/docs/api/jobs#jobprofileerror-class)                                           | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#jobprofileerror-class)                                                                        |
| [JobProvider](/docs/api/jobs#jobprovider-interface)                                               | Type  | `@relkit/jobs/legacy`                  | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/client.test.ts#L27)                       |
| [JobProviderError](/docs/api/jobs#jobprovidererror-class)                                         | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#jobprovidererror-class)                                                                       |
| [JobProviderResult](/docs/api/jobs#jobproviderresult-type-alias)                                  | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobReceiptError](/docs/api/jobs#jobreceipterror-class)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobreceipterror-class)                                                                        |
| [JobResultUnavailableError](/docs/api/jobs#jobresultunavailableerror-class)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobresultunavailableerror-class)                                                              |
| [JobRetryOptions](/docs/api/jobs#jobretryoptions-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobRunResultOptions](/docs/api/jobs#jobrunresultoptions-type-alias)                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobRunStatus](/docs/api/app#jobrunstatus-type-alias)                                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JOBS_ADAPTER_PROTOCOL_VERSION](/docs/api/jobs#jobs_adapter_protocol_version)                     | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#jobs_adapter_protocol_version)                                                                |
| [JobsAdapterRuntime](/docs/api/jobs#jobsadapterruntime-interface)                                 | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/adapter-effect.test.ts#L32)               |
| [JobsAdapterValidationError](/docs/api/jobs#jobsadaptervalidationerror-class)                     | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#jobsadaptervalidationerror-class)                                                             |
| [JobsCapability](/docs/api/jobs#jobscapability-interface)                                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsCapabilityError](/docs/api/jobs#jobscapabilityerror-class)                                   | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#jobscapabilityerror-class)                                                                    |
| [JobsCapabilityFailure](/docs/api/jobs#jobscapabilityfailure-class)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobscapabilityfailure-class)                                                                  |
| [JobsCapabilityName](/docs/api/jobs#jobscapabilityname-type-alias)                                | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsCapabilityReport](/docs/api/jobs#jobscapabilityreport-interface)                             | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsCapabilitySupport](/docs/api/jobs#jobscapabilitysupport-type-alias)                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobScheduleClient](/docs/api/jobs#jobscheduleclient-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobScheduleControlFailure](/docs/api/jobs#jobschedulecontrolfailure-class)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobschedulecontrolfailure-class)                                                              |
| [JobsControls](/docs/api/jobs#jobscontrols-interface)                                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobServiceSelection](/docs/api/jobs#jobserviceselection-type-alias)                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsManifestLike](/docs/api/jobs#jobsmanifestlike-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsManifestReader](/docs/api/jobs#jobsmanifestreader-class)                                     | Value | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#jobsmanifestreader-class)                                                                     |
| [JobsManifestReaderLive](/docs/api/jobs#jobsmanifestreaderlive)                                   | Value | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#jobsmanifestreaderlive)                                                                       |
| [JobsOperationOptions](/docs/api/jobs#jobsoperationoptions-type-alias)                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsRuntime](/docs/api/jobs#jobsruntime-interface)                                               | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/control-result-effect.test.ts#L12)        |
| [JobsRuntimeBinding](/docs/api/jobs#jobsruntimebinding-interface)                                 | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/submission-support-effect.test.ts#L37)    |
| [JobsRuntimeCallbackError](/docs/api/jobs#jobsruntimecallbackerror-class)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsruntimecallbackerror-class)                                                               |
| [JobsRuntimeError](/docs/api/jobs#jobsruntimeerror-class)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsruntimeerror-class)                                                                       |
| [JobsRuntimeOptions](/docs/api/jobs#jobsruntimeoptions-interface)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsServerError](/docs/api/jobs#jobsservererror-class)                                           | Value | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#jobsservererror-class)                                                                        |
| [JobsServiceBehavior](/docs/api/jobs#jobsservicebehavior-type-alias)                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsServiceOptionName](/docs/api/jobs#jobsserviceoptionname-type-alias)                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobsServiceOptions](/docs/api/jobs#jobsserviceoptions-interface)                                 | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/service-options-validation.test.ts#L9)    |
| [JobsServiceOptionsError](/docs/api/jobs#jobsserviceoptionserror-class)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsserviceoptionserror-class)                                                                |
| [JobState](/docs/api/functions#jobstate-type-alias)                                               | Type  | `@relkit/jobs/legacy`                  | [API example](/docs/api/functions#jobstate-type-alias)                                                                     |
| [JobStatus](/docs/api/functions#jobstatus-interface)                                              | Type  | `@relkit/jobs/legacy`                  | [API example](/docs/api/functions#jobstatus-interface)                                                                     |
| [JobsTelemetry](/docs/api/jobs#jobstelemetry-class)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobstelemetry-class)                                                                          |
| [JobsTelemetryLive](/docs/api/jobs#jobstelemetrylive-1)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobstelemetrylive-1)                                                                          |
| [JobSubmissionCancelledError](/docs/api/jobs#jobsubmissioncancellederror-class)                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsubmissioncancellederror-class)                                                            |
| [JobSubmissionError](/docs/api/jobs#jobsubmissionerror-class)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsubmissionerror-class)                                                                     |
| [JobSubmissionPipelineFailure](/docs/api/jobs#jobsubmissionpipelinefailure-class)                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsubmissionpipelinefailure-class)                                                           |
| [JobSubmissionUnknownError](/docs/api/jobs#jobsubmissionunknownerror-class)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#jobsubmissionunknownerror-class)                                                              |
| [JobTriggerClients](/docs/api/jobs#jobtriggerclients-type-alias)                                  | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobUnknownOutcome](/docs/api/app#jobunknownoutcome-interface)                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JobWireEnvelope](/docs/api/app#jobwireenvelope-type-alias)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [JsonWireEnvelope](/docs/api/app#jsonwireenvelope-interface)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [LegacyCompatibilitySnapshot](/docs/api/jobs#legacycompatibilitysnapshot-interface)               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [LegacyJobValidationError](/docs/api/jobs#legacyjobvalidationerror-class)                         | Value | `@relkit/jobs/legacy`                  | [API example](/docs/api/jobs#legacyjobvalidationerror-class)                                                               |
| [listRuns](/docs/api/jobs#listruns)                                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#listruns)                                                                                     |
| [listRunsEffect](/docs/api/jobs#listrunseffect)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#listrunseffect)                                                                               |
| [listSchedulesEffect](/docs/api/jobs#listscheduleseffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#listscheduleseffect)                                                                          |
| [memoryBytes](/docs/api/jobs#memorybytes)                                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#memorybytes)                                                                                  |
| [memoryBytesEffect](/docs/api/jobs#memorybyteseffect)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#memorybyteseffect)                                                                            |
| [MemoryInput](/docs/api/jobs#memoryinput-type-alias)                                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NamedStreamFrame](/docs/api/app#namedstreamframe-type-alias)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [namespaceHash](/docs/api/jobs#namespacehash-1)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#namespacehash-1)                                                                              |
| [namespaceHashEffect](/docs/api/jobs#namespacehasheffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#namespacehasheffect)                                                                          |
| [NativeCancelRequest](/docs/api/jobs#nativecancelrequest-interface)                               | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeControlReceipt](/docs/api/jobs#nativecontrolreceipt-type-alias)                            | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeDurableSleep](/docs/api/jobs#nativedurablesleep-interface)                                 | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeLocator](/docs/api/jobs#nativelocator-type-alias)                                          | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeObservation](/docs/api/jobs#nativeobservation-type-alias)                                  | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeOwnedScheduleRecord](/docs/api/jobs#nativeownedschedulerecord-interface)                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeProgressWriter](/docs/api/jobs#nativeprogresswriter-interface)                             | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeReceipt](/docs/api/jobs#nativereceipt-type-alias)                                          | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeRetryRequest](/docs/api/jobs#nativeretryrequest-interface)                                 | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeRun](/docs/api/jobs#nativerun-type-alias)                                                  | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeRunPage](/docs/api/jobs#nativerunpage-type-alias)                                          | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeRunQuery](/docs/api/jobs#nativerunquery-type-alias)                                        | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [nativeScheduleLayer](/docs/api/jobs#nativeschedulelayer)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#nativeschedulelayer)                                                                          |
| [NativeScheduleOperations](/docs/api/jobs#nativescheduleoperations-interface)                     | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-controls-operations.test.ts#L19) |
| [NativeScheduleService](/docs/api/jobs#nativescheduleservice-class)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#nativescheduleservice-class)                                                                  |
| [NativeStreamWriter](/docs/api/jobs#nativestreamwriter-interface)                                 | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeStreamWriters](/docs/api/jobs#nativestreamwriters-type-alias)                              | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeSubmission](/docs/api/jobs#nativesubmission-interface)                                     | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/native-jobs.test.ts#L19)       |
| [NativeTaskWork](/docs/api/jobs#nativetaskwork-interface)                                         | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/commerce-layout-task-run.ts#L59)   |
| [NativeTaskWorker](/docs/api/jobs#nativetaskworker-interface)                                     | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NativeWatchRequest](/docs/api/jobs#nativewatchrequest-interface)                                 | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [NormalizedTaskRetryPolicy](/docs/api/jobs#normalizedtaskretrypolicy-interface)                   | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L27)                 |
| [normalizeJobName](/docs/api/jobs#normalizejobname-1)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#normalizejobname-1)                                                                           |
| [observeRun](/docs/api/jobs#observerun)                                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#observerun)                                                                                   |
| [observeRunEffect](/docs/api/jobs#observeruneffect)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#observeruneffect)                                                                             |
| [OperationContext](/docs/api/jobs#operationcontext-interface)                                     | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-reconciliation.test.ts#L18)      |
| [OutputOf](/docs/api/jobs#outputof-type-alias)                                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [parseDuration](/docs/api/jobs#parseduration)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#parseduration)                                                                                |
| [prepareCanonicalSubmission](/docs/api/jobs#preparecanonicalsubmission)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#preparecanonicalsubmission)                                                                   |
| [prepareCanonicalSubmissionEffect](/docs/api/jobs#preparecanonicalsubmissioneffect)               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#preparecanonicalsubmissioneffect)                                                             |
| [prepareSubmission](/docs/api/jobs#preparesubmission)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#preparesubmission)                                                                            |
| [prepareSubmissionEffect](/docs/api/jobs#preparesubmissioneffect)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#preparesubmissioneffect)                                                                      |
| [ProgressEmitReceipt](/docs/api/app#progressemitreceipt-interface)                                | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [projectRun](/docs/api/jobs#projectrun)                                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#projectrun)                                                                                   |
| [projectRunPage](/docs/api/jobs#projectrunpage)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#projectrunpage)                                                                               |
| [projectRunPageEffect](/docs/api/jobs#projectrunpageeffect)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#projectrunpageeffect)                                                                         |
| [projectRunSnapshot](/docs/api/jobs#projectrunsnapshot)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#projectrunsnapshot)                                                                           |
| [projectRunSnapshotEffect](/docs/api/jobs#projectrunsnapshoteffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#projectrunsnapshoteffect)                                                                     |
| [PublishedEventName](/docs/api/jobs#publishedeventname-type-alias)                                | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [readJobCursor](/docs/api/jobs#readjobcursor)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#readjobcursor)                                                                                |
| [readJobCursorEffect](/docs/api/jobs#readjobcursoreffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#readjobcursoreffect)                                                                          |
| [reconcileNativeSchedules](/docs/api/jobs#reconcilenativeschedules)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#reconcilenativeschedules)                                                                     |
| [reconcileNativeSchedulesEffect](/docs/api/jobs#reconcilenativescheduleseffect)                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#reconcilenativescheduleseffect)                                                               |
| [requireJobsRuntime](/docs/api/jobs#requirejobsruntime)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#requirejobsruntime)                                                                           |
| [requireJobsRuntimeEffect](/docs/api/jobs#requirejobsruntimeeffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#requirejobsruntimeeffect)                                                                     |
| [resolveBinding](/docs/api/jobs#resolvebinding)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#resolvebinding)                                                                               |
| [ResolveBindingOptions](/docs/api/jobs#resolvebindingoptions-interface)                           | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ResolvedTaskBinding](/docs/api/jobs#resolvedtaskbinding-interface)                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [resolveTaskBinding](/docs/api/jobs#resolvetaskbinding)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#resolvetaskbinding)                                                                           |
| [resolveTaskBindingEffect](/docs/api/jobs#resolvetaskbindingeffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#resolvetaskbindingeffect)                                                                     |
| [ResultAvailability](/docs/api/app#resultavailability-type-alias)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [retryDelayMillis](/docs/api/jobs#retrydelaymillis)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retrydelaymillis)                                                                             |
| [retryDelayMillisEffect](/docs/api/jobs#retrydelaymilliseffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retrydelaymilliseffect)                                                                       |
| [RetryJitter](/docs/api/jobs#retryjitter-type-alias)                                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RetryJitter](/docs/api/jobs#retryjitter-type-alias-1)                                            | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [retryOperationIdentity](/docs/api/jobs#retryoperationidentity)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retryoperationidentity)                                                                       |
| [retryOperationIdentityEffect](/docs/api/jobs#retryoperationidentityeffect)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retryoperationidentityeffect)                                                                 |
| [RetryPolicy](/docs/api/jobs#retrypolicy-interface)                                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RetryPolicy](/docs/api/jobs#retrypolicy-interface-1)                                             | Type  | `@relkit/jobs/legacy`                  | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/events.ts#L19)                                |
| [retryRun](/docs/api/jobs#retryrun)                                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retryrun)                                                                                     |
| [retryRunEffect](/docs/api/jobs#retryruneffect)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#retryruneffect)                                                                               |
| [rotateRunLocatorKeys](/docs/api/jobs#rotaterunlocatorkeys)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#rotaterunlocatorkeys)                                                                         |
| [rotateRunLocatorKeysEffect](/docs/api/jobs#rotaterunlocatorkeyseffect)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#rotaterunlocatorkeyseffect)                                                                   |
| [RUN_LOCATOR_MAX_BYTES](/docs/api/jobs#run_locator_max_bytes)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#run_locator_max_bytes)                                                                        |
| [RUN_LOCATOR_VERSION](/docs/api/jobs#run_locator_version)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#run_locator_version)                                                                          |
| [RunAvailability](/docs/api/app#runavailability-interface)                                        | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunCancellationReceipt](/docs/api/app#runcancellationreceipt-interface)                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunConnection](/docs/api/app#runconnection-type-alias)                                           | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunHandle](/docs/api/app#runhandle-interface)                                                    | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-client.ts#L36)                               |
| [runInJobsRuntime](/docs/api/jobs#runinjobsruntime)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runinjobsruntime)                                                                             |
| [runInJobsRuntimeEffect](/docs/api/jobs#runinjobsruntimeeffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runinjobsruntimeeffect)                                                                       |
| [RunListQuery](/docs/api/app#runlistquery-interface)                                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorCreateOptions](/docs/api/jobs#runlocatorcreateoptions-interface)                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorError](/docs/api/jobs#runlocatorerror-class)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorerror-class)                                                                        |
| [RunLocatorFailure](/docs/api/jobs#runlocatorfailure-class)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorfailure-class)                                                                      |
| [RunLocatorGeneration](/docs/api/jobs#runlocatorgeneration-interface)                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorGenerationStorage](/docs/api/jobs#runlocatorgenerationstorage-class)                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorgenerationstorage-class)                                                            |
| [RunLocatorGenerationStore](/docs/api/jobs#runlocatorgenerationstore-interface)                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorKeyRing](/docs/api/jobs#runlocatorkeyring-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorKeyRingStore](/docs/api/jobs#runlocatorkeyringstore-interface)                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorPayload](/docs/api/jobs#runlocatorpayload-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunLocatorRouter](/docs/api/jobs#runlocatorrouter-class)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorrouter-class)                                                                       |
| [RunLocatorStoreFailure](/docs/api/jobs#runlocatorstorefailure-class)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorstorefailure-class)                                                                 |
| [runLocatorStoreLayer](/docs/api/jobs#runlocatorstorelayer)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runlocatorstorelayer)                                                                         |
| [RunLocatorVerifyOptions](/docs/api/jobs#runlocatorverifyoptions-interface)                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunPage](/docs/api/app#runpage-interface)                                                        | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector-api/tests/compatibility/jobs.test.ts#L85)  |
| [RunResultOptions](/docs/api/jobs#runresultoptions-interface)                                     | Type  | `@relkit/jobs`, `@relkit/jobs/server`  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunRetryReceipt](/docs/api/app#runretryreceipt-interface)                                        | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [RunSnapshot](/docs/api/app#runsnapshot-type-alias)                                               | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L557)  |
| [RunWatchFrame](/docs/api/app#runwatchframe-type-alias)                                           | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts#L615)  |
| [runWithJobs](/docs/api/jobs#runwithjobs)                                                         | Value | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#runwithjobs)                                                                                  |
| [RunWithJobsConfig](/docs/api/jobs#runwithjobsconfig-interface)                                   | Type  | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#runwithjobsconfig-interface)                                                                  |
| [runWithJobsEffect](/docs/api/jobs#runwithjobseffect)                                             | Value | `@relkit/jobs/server`                  | [API example](/docs/api/jobs#runwithjobseffect)                                                                            |
| [runWithJobsRuntime](/docs/api/jobs#runwithjobsruntime)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runwithjobsruntime)                                                                           |
| [runWithJobsRuntimeEffect](/docs/api/jobs#runwithjobsruntimeeffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#runwithjobsruntimeeffect)                                                                     |
| [ScheduleDefinition](/docs/api/jobs#scheduledefinition-type-alias)                                | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-controls.test.ts#L70)            |
| [ScheduleDefinition](/docs/api/jobs#scheduledefinition-interface)                                 | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleListOptions](/docs/api/jobs#schedulelistoptions-interface)                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleMisfire](/docs/api/jobs#schedulemisfire-type-alias)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [scheduleOccurrenceIdentity](/docs/api/jobs#scheduleoccurrenceidentity)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleoccurrenceidentity)                                                                   |
| [scheduleOccurrenceIdentityEffect](/docs/api/jobs#scheduleoccurrenceidentityeffect)               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleoccurrenceidentityeffect)                                                             |
| [scheduleOperationId](/docs/api/jobs#scheduleoperationid)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleoperationid)                                                                          |
| [scheduleOperationIdEffect](/docs/api/jobs#scheduleoperationideffect)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleoperationideffect)                                                                    |
| [ScheduleOverlap](/docs/api/jobs#scheduleoverlap-type-alias-1)                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleOverlap](/docs/api/jobs#scheduleoverlap-type-alias)                                      | Type  | `@relkit/jobs/legacy`                  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [scheduleOwner](/docs/api/jobs#scheduleowner)                                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleowner)                                                                                |
| [scheduleOwnerEffect](/docs/api/jobs#scheduleownereffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#scheduleownereffect)                                                                          |
| [ScheduleReadReceipt](/docs/api/jobs#schedulereadreceipt-interface)                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleReconciliationFailure](/docs/api/jobs#schedulereconciliationfailure-class)               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#schedulereconciliationfailure-class)                                                          |
| [ScheduleReconciliationOptions](/docs/api/jobs#schedulereconciliationoptions-interface)           | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleReconciliationResult](/docs/api/jobs#schedulereconciliationresult-interface)             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleRecord](/docs/api/jobs#schedulerecord-interface)                                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleWriteOptions](/docs/api/jobs#schedulewriteoptions-interface)                             | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleWriteOutcome](/docs/api/jobs#schedulewriteoutcome-type-alias)                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [ScheduleWriteReceipt](/docs/api/jobs#schedulewritereceipt-type-alias)                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [serializeJobsServiceOptions](/docs/api/jobs#serializejobsserviceoptions)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#serializejobsserviceoptions)                                                                  |
| [serializeJobsServiceOptionsEffect](/docs/api/jobs#serializejobsserviceoptionseffect)             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#serializejobsserviceoptionseffect)                                                            |
| [ServerTriggerOptions](/docs/api/jobs#servertriggeroptions-interface)                             | Type  | `@relkit/jobs`, `@relkit/jobs/server`  | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [stableIdentityTuple](/docs/api/jobs#stableidentitytuple)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#stableidentitytuple)                                                                          |
| [stableIdentityTupleEffect](/docs/api/jobs#stableidentitytupleeffect)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#stableidentitytupleeffect)                                                                    |
| [StreamIdentity](/docs/api/app#streamidentity-interface)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [StreamItem](/docs/api/app#streamitem-type-alias)                                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [SubmissionAdmission](/docs/api/jobs#submissionadmission-interface)                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [SubmissionPipeline](/docs/api/jobs#submissionpipeline-interface)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [submitCanonicalTask](/docs/api/jobs#submitcanonicaltask)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submitcanonicaltask)                                                                          |
| [submitCanonicalTaskEffect](/docs/api/jobs#submitcanonicaltaskeffect)                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submitcanonicaltaskeffect)                                                                    |
| [submitJob](/docs/api/jobs#submitjob)                                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submitjob)                                                                                    |
| [submitJobEffect](/docs/api/jobs#submitjobeffect)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submitjobeffect)                                                                              |
| [submitPreparedSubmission](/docs/api/jobs#submitpreparedsubmission)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submitpreparedsubmission)                                                                     |
| [submitTask](/docs/api/jobs#submittask)                                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submittask)                                                                                   |
| [submitTaskEffect](/docs/api/jobs#submittaskeffect)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#submittaskeffect)                                                                             |
| [TASK_INPUT_MAX_BYTES](/docs/api/jobs#task_input_max_bytes-2)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_input_max_bytes-2)                                                                       |
| [TASK_ITEM_MAX_BYTES](/docs/api/jobs#task_item_max_bytes-2)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_item_max_bytes-2)                                                                        |
| [TASK_KEY_MAX_BYTES](/docs/api/jobs#task_key_max_bytes-2)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_key_max_bytes-2)                                                                         |
| [TASK_MAX_TAGS](/docs/api/jobs#task_max_tags-2)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_max_tags-2)                                                                              |
| [TASK_OUTPUT_MAX_BYTES](/docs/api/jobs#task_output_max_bytes-2)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_output_max_bytes-2)                                                                      |
| [TASK_REASON_MAX_BYTES](/docs/api/jobs#task_reason_max_bytes-2)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#task_reason_max_bytes-2)                                                                      |
| [TaskAuthContext](/docs/api/jobs#taskauthcontext-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskBlockingWaitError](/docs/api/jobs#taskblockingwaiterror-class)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskblockingwaiterror-class)                                                                  |
| [TaskCallerInput](/docs/api/jobs#taskcallerinput-type-alias)                                      | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L80)                         |
| [TaskCanonicalInput](/docs/api/jobs#taskcanonicalinput-type-alias)                                | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L81)                         |
| [TaskClientFor](/docs/api/jobs#taskclientfor-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskClients](/docs/api/jobs#taskclients-type-alias)                                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskConcurrency](/docs/api/jobs#taskconcurrency-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskContext](/docs/api/jobs#taskcontext-type-alias)                                              | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskContextBase](/docs/api/jobs#taskcontextbase-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskDefinitionFailure](/docs/api/jobs#taskdefinitionfailure-class)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskdefinitionfailure-class)                                                                  |
| [TaskDependencies](/docs/api/jobs#taskdependencies-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskDescriptor](/docs/api/jobs#taskdescriptor-interface)                                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskDescriptorAny](/docs/api/jobs#taskdescriptorany-type-alias)                                  | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/jobs-quality.test.ts#L32)                 |
| [TaskEmissionError](/docs/api/jobs#taskemissionerror-class)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskemissionerror-class)                                                                      |
| [TaskEmissionErrorCode](/docs/api/jobs#taskemissionerrorcode-type-alias)                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskEmissionFailure](/docs/api/jobs#taskemissionfailure-class)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskemissionfailure-class)                                                                    |
| [TaskEmissionSink](/docs/api/jobs#taskemissionsink-type-alias)                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskEmitterOptions](/docs/api/jobs#taskemitteroptions-interface)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskExecution](/docs/api/jobs#taskexecution-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskExecutionBinding](/docs/api/jobs#taskexecutionbinding-interface)                             | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskExecutionEnvelope](/docs/api/jobs#taskexecutionenvelope-interface)                           | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskExecutor](/docs/api/jobs#taskexecutor-interface)                                             | Type  | `@relkit/jobs`, `@relkit/jobs/adapter` | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskFailureHook](/docs/api/jobs#taskfailurehook-type-alias)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskHandler](/docs/api/jobs#taskhandler-type-alias)                                              | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L94)                         |
| [TaskHandlerResult](/docs/api/jobs#taskhandlerresult-type-alias)                                  | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskHookContext](/docs/api/jobs#taskhookcontext-type-alias)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskInput](/docs/api/jobs#taskinput-type-alias)                                                  | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskLogging](/docs/api/jobs#tasklogging-interface)                                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskObservation](/docs/api/jobs#taskobservation-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [taskOperationIdentity](/docs/api/jobs#taskoperationidentity)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskoperationidentity)                                                                        |
| [taskOperationIdentityEffect](/docs/api/jobs#taskoperationidentityeffect)                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskoperationidentityeffect)                                                                  |
| [TaskOutput](/docs/api/jobs#taskoutput-type-alias)                                                | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskPolicyRandom](/docs/api/jobs#taskpolicyrandom-class)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskpolicyrandom-class)                                                                       |
| [taskPolicyRandomLayer](/docs/api/jobs#taskpolicyrandomlayer)                                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskpolicyrandomlayer)                                                                        |
| [TaskProgressEmitter](/docs/api/jobs#taskprogressemitter-interface)                               | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskProgressInput](/docs/api/jobs#taskprogressinput-type-alias)                                  | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L86)                         |
| [TaskProgressOutput](/docs/api/jobs#taskprogressoutput-type-alias)                                | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L87)                         |
| [TaskRawHandlerOutput](/docs/api/jobs#taskrawhandleroutput-type-alias)                            | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L82)                         |
| [TaskResources](/docs/api/jobs#taskresources-interface)                                           | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskRetryPolicy](/docs/api/jobs#taskretrypolicy-interface)                                       | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskRunContext](/docs/api/jobs#taskruncontext-interface)                                         | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskSleepOptions](/docs/api/jobs#tasksleepoptions-interface)                                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStartHook](/docs/api/jobs#taskstarthook-type-alias)                                          | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamEmitter](/docs/api/jobs#taskstreamemitter-interface)                                   | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamEmitterOptions](/docs/api/jobs#taskstreamemitteroptions-interface)                     | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamEmitters](/docs/api/jobs#taskstreamemitters-type-alias)                                | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamFrames](/docs/api/jobs#taskstreamframes-type-alias)                                    | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamInput](/docs/api/jobs#taskstreaminput-type-alias)                                      | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L88)                         |
| [TaskStreamItem](/docs/api/jobs#taskstreamitem-type-alias)                                        | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamOutput](/docs/api/jobs#taskstreamoutput-type-alias)                                    | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L89)                         |
| [TaskStreamSchemas](/docs/api/jobs#taskstreamschemas-type-alias)                                  | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskStreamSink](/docs/api/jobs#taskstreamsink-type-alias)                                        | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskSubmissionMetadata](/docs/api/jobs#tasksubmissionmetadata-interface)                         | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/submission-write-effect.test.ts#L16)      |
| [TaskSuccessHook](/docs/api/jobs#tasksuccesshook-type-alias)                                      | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L90)                         |
| [TaskTriggerOptions](/docs/api/jobs#tasktriggeroptions-interface)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskValidatedOutput](/docs/api/jobs#taskvalidatedoutput-type-alias)                              | Type  | `@relkit/jobs`                         | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L83)                         |
| [TaskWireErrorCode](/docs/api/jobs#taskwireerrorcode-type-alias)                                  | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [TaskWireFailure](/docs/api/jobs#taskwirefailure-class)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskwirefailure-class)                                                                        |
| [TaskWireValidationError](/docs/api/jobs#taskwirevalidationerror-class)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#taskwirevalidationerror-class)                                                                |
| [TriggerOptions](/docs/api/jobs#triggeroptions-interface)                                         | Type  | `@relkit/jobs`, `@relkit/jobs/server`  | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/jobs-names.test-d.ts#L224)                        |
| [TrustedJobScope](/docs/api/jobs#trustedjobscope-interface)                                       | Type  | `@relkit/jobs`                         | [API example](/docs/api/jobs#trustedjobscope-interface)                                                                    |
| [utf8Bytes](/docs/api/jobs#utf8bytes)                                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#utf8bytes)                                                                                    |
| [utf8BytesEffect](/docs/api/jobs#utf8byteseffect)                                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#utf8byteseffect)                                                                              |
| [validateCanonicalInput](/docs/api/jobs#validatecanonicalinput)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatecanonicalinput)                                                                       |
| [validateCanonicalInputEffect](/docs/api/jobs#validatecanonicalinputeffect)                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatecanonicalinputeffect)                                                                 |
| [validateCanonicalOutput](/docs/api/jobs#validatecanonicaloutput)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatecanonicaloutput)                                                                      |
| [validateCanonicalOutputEffect](/docs/api/jobs#validatecanonicaloutputeffect)                     | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatecanonicaloutputeffect)                                                                |
| [validateDuration](/docs/api/jobs#validateduration)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validateduration)                                                                             |
| [validateJobName](/docs/api/jobs#validatejobname-1)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatejobname-1)                                                                            |
| [validateJobNameEffect](/docs/api/jobs#validatejobnameeffect-1)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatejobnameeffect-1)                                                                      |
| [validateJobsCapabilityReport](/docs/api/jobs#validatejobscapabilityreport-1)                     | Value | `@relkit/jobs`, `@relkit/jobs/adapter` | [API example](/docs/api/jobs#validatejobscapabilityreport-1)                                                               |
| [validateJobsCapabilityReportEffect](/docs/api/jobs#validatejobscapabilityreporteffect)           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatejobscapabilityreporteffect)                                                           |
| [validateJobsServiceOptions](/docs/api/jobs#validatejobsserviceoptions)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatejobsserviceoptions)                                                                   |
| [validateJobsServiceOptionsEffect](/docs/api/jobs#validatejobsserviceoptionseffect)               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatejobsserviceoptionseffect)                                                             |
| [validateResultOptions](/docs/api/jobs#validateresultoptions-1)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validateresultoptions-1)                                                                      |
| [validateRunLocatorKeyRing](/docs/api/jobs#validaterunlocatorkeyring-1)                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validaterunlocatorkeyring-1)                                                                  |
| [validateRunLocatorKeyRingEffect](/docs/api/jobs#validaterunlocatorkeyringeffect)                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validaterunlocatorkeyringeffect)                                                              |
| [validateTaskInput](/docs/api/jobs#validatetaskinput)                                             | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatetaskinput)                                                                            |
| [validateTaskInputEffect](/docs/api/jobs#validatetaskinputeffect)                                 | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatetaskinputeffect)                                                                      |
| [validateTaskOutput](/docs/api/jobs#validatetaskoutput)                                           | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatetaskoutput)                                                                           |
| [validateTaskOutputEffect](/docs/api/jobs#validatetaskoutputeffect)                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#validatetaskoutputeffect)                                                                     |
| [ValidJobName](/docs/api/jobs#validjobname-type-alias)                                            | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [VerifiedRunLocator](/docs/api/jobs#verifiedrunlocator-interface)                                 | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [verifyRunLocator](/docs/api/jobs#verifyrunlocator)                                               | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#verifyrunlocator)                                                                             |
| [verifyRunLocatorEffect](/docs/api/jobs#verifyrunlocatoreffect)                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#verifyrunlocatoreffect)                                                                       |
| [VoidWireEnvelope](/docs/api/app#voidwireenvelope-interface)                                      | Type  | `@relkit/jobs`                         | [Module example](/docs/modules/jobs/quickstart)                                                                            |
| [waitForResult](/docs/api/jobs#waitforresult-1)                                                   | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#waitforresult-1)                                                                              |
| [waitForResultEffect](/docs/api/jobs#waitforresulteffect-1)                                       | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#waitforresulteffect-1)                                                                        |
| [writeScheduleEffect](/docs/api/jobs#writescheduleeffect)                                         | Value | `@relkit/jobs`                         | [API example](/docs/api/jobs#writescheduleeffect)                                                                          |

## `adapter-methods.ts`

### assertAdapterMethods

Synchronous adapter method check.

**Throws**

JobsCapabilityError when a method is missing.

**Example**

```ts
assertAdapterMethods(adapter);
```

**Signature**

```ts
declare const assertAdapterMethods: (adapter: JobsAdapterRuntime) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-methods.ts#L51)

### assertAdapterMethodsEffect

Checks the methods promised by a jobs adapter.

**Example**

```ts
Effect.runSync(assertAdapterMethodsEffect(adapter));
```

**Signature**

```ts
declare const assertAdapterMethodsEffect: (
  adapter: JobsAdapterRuntime,
) => Effect.Effect<undefined, JobsCapabilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-methods.ts#L10)

## `adapter-requests.types.ts`

### NativeCancelRequest (interface)

Provider-facing cancel request contract at the adapter boundary.

**Signature**

```ts
export interface NativeCancelRequest {
  readonly runId: string;
  readonly operationId: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L66)

### NativeControlReceipt (type alias)

Provider acknowledgement for a run control operation.

**Signature**

```ts
type NativeControlReceipt = RunCancellationReceipt | RunRetryReceipt | JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L57)

### NativeReceipt (type alias)

Provider acknowledgement for an accepted submission.

**Signature**

```ts
type NativeReceipt = RunHandle | JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L55)

### NativeRetryRequest (interface)

Provider-facing retry request contract at the adapter boundary.

**Signature**

```ts
export interface NativeRetryRequest {
  readonly runId: string;
  readonly operationId: string;
  readonly retryIdentity?: string;
  readonly canonicalInput?: JobWireEnvelope;
  readonly inputHash?: string;
  readonly inputSchemaHash?: string;
  readonly taskId?: string;
  readonly jobId?: string;
  readonly taskVersion?: string;
  readonly buildId?: string;
  readonly scope?: string;
  readonly acceptanceIdentity?: string;
  readonly canonicalAdmission?: {
    readonly validatePinnedInput: true;
    readonly allocateFreshBudget: true;
    readonly clearInitialDelay: true;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L73)

### NativeSubmission (interface)

Provider request created from a validated job submission.

**Signature**

```ts
export interface NativeSubmission {
  readonly jobId: string;
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly execution?: "durable" | "retryable";
  readonly scope?: string;
  readonly input: JsonValue;
  readonly operationId: string;
  readonly idempotencyKey?: string;
  readonly canonicalInput?: JobWireEnvelope;
  readonly inputHash?: string;
  readonly inputSchemaHash?: string;
  readonly policy?: JsonValue;
  readonly scheduledFor?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
  readonly parentRunId?: string;
  readonly propagation?: TracePropagation;
  readonly acceptanceIdentity?: string;
  readonly occurrenceIdentity?: string;
  readonly retryOfRunId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L30)

### NativeWatchRequest (interface)

Provider-facing watch request contract at the adapter boundary.

**Signature**

```ts
export interface NativeWatchRequest {
  readonly runId: string;
  readonly after?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L60)

### OperationContext (interface)

Scope, signal, and tracing data passed to one provider operation.

**Signature**

```ts
export interface OperationContext {
  readonly signal: AbortSignal;
  readonly application: string;
  readonly environment: string;
  readonly scope: string;
  readonly service: string;
  readonly serviceGeneration: string;
  readonly operationId?: string;
  readonly deadlineMs?: number;
  readonly correlationId?: string;
  readonly parentRunId?: string;
  readonly propagation?: TracePropagation;
  readonly acceptanceIdentity?: string;
  readonly occurrenceIdentity?: string;
  readonly inputSchemaHash?: string;
  readonly retryOfRunId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter-requests.types.ts#L11)

## `adapter.ts`

### JOBS_ADAPTER_PROTOCOL_VERSION

Protocol version required by all jobs adapters.

**Example**

```ts
adapter.protocolVersion === JOBS_ADAPTER_PROTOCOL_VERSION;
```

**Signature**

```ts
declare const JOBS_ADAPTER_PROTOCOL_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L47)

### JobsAdapterRuntime

**Signature**

```ts
declare const JobsAdapterRuntime: JobsAdapterRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L32)

### JobsAdapterValidationError (class)

Invalid jobs adapter shape or protocol.

**Example**

```ts
if (error instanceof JobsAdapterValidationError) console.log(error.message);
```

**Signature**

```ts
declare class JobsAdapterValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L51)

### JobsCapabilityError

**Signature**

```ts
declare const JobsCapabilityError: typeof JobsCapabilityError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L39)

### JobsCapabilityReport

**Signature**

```ts
declare const JobsCapabilityReport: JobsCapabilityReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L37)

### NativeCancelRequest

**Signature**

```ts
declare const NativeCancelRequest: NativeCancelRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L11)

### NativeControlReceipt

**Signature**

```ts
declare const NativeControlReceipt: NativeControlReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L12)

### NativeDurableSleep

**Signature**

```ts
declare const NativeDurableSleep: NativeDurableSleep;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L29)

### NativeLocator

**Signature**

```ts
declare const NativeLocator: string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L24)

### NativeObservation

**Signature**

```ts
declare const NativeObservation: NativeObservation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L23)

### NativeProgressWriter

**Signature**

```ts
declare const NativeProgressWriter: NativeProgressWriter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L26)

### NativeReceipt

**Signature**

```ts
declare const NativeReceipt: NativeReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L13)

### NativeRetryRequest

**Signature**

```ts
declare const NativeRetryRequest: NativeRetryRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L14)

### NativeRun

**Signature**

```ts
declare const NativeRun: NativeRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L20)

### NativeRunPage

**Signature**

```ts
declare const NativeRunPage: NativeRunPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L22)

### NativeRunQuery

**Signature**

```ts
declare const NativeRunQuery: RunListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L21)

### NativeScheduleOperations

**Signature**

```ts
declare const NativeScheduleOperations: NativeScheduleOperations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L25)

### NativeStreamWriter

**Signature**

```ts
declare const NativeStreamWriter: NativeStreamWriter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L27)

### NativeStreamWriters

**Signature**

```ts
declare const NativeStreamWriters: Readonly<Record<string, NativeStreamWriter>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L28)

### NativeSubmission

**Signature**

```ts
declare const NativeSubmission: NativeSubmission;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L15)

### NativeTaskWork

**Signature**

```ts
declare const NativeTaskWork: NativeTaskWork;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L33)

### NativeTaskWorker

**Signature**

```ts
declare const NativeTaskWorker: NativeTaskWorker;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L34)

### NativeWatchRequest

**Signature**

```ts
declare const NativeWatchRequest: NativeWatchRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L16)

### OperationContext

**Signature**

```ts
declare const OperationContext: OperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L17)

### TaskExecutionBinding

**Signature**

```ts
declare const TaskExecutionBinding: TaskExecutionBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L35)

### TaskExecutionEnvelope

**Signature**

```ts
declare const TaskExecutionEnvelope: TaskExecutionEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L30)

### TaskExecutor

**Signature**

```ts
declare const TaskExecutor: TaskExecutor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L31)

### assertAdapterMethods

**Signature**

```ts
declare const assertAdapterMethods: (adapter: JobsAdapterRuntime) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L40)

### assertJobsAdapterRuntime

Synchronous adapter shape assertion.

**Throws**

TypeError or JobsCapabilityError when invalid.

**Example**

```ts
assertJobsAdapterRuntime(adapter);
```

**Signature**

```ts
declare const assertJobsAdapterRuntime: (value: unknown) => asserts value is JobsAdapterRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L87)

### assertJobsAdapterRuntimeEffect

Validates an untrusted jobs adapter in Effect.

**Example**

```ts
Effect.runSync(assertJobsAdapterRuntimeEffect(adapter));
```

**Signature**

```ts
declare const assertJobsAdapterRuntimeEffect: (
  value: unknown,
) => Effect.Effect<JobsAdapterRuntime, JobsCapabilityFailure | JobsAdapterValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L60)

### assertJobsCapability

**Signature**

```ts
declare const assertJobsCapability: (report: JobsCapabilityReport, capability: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L41)

### isJobsAdapterRuntime

Synchronous jobs adapter brand check.

**Example**

```ts
isJobsAdapterRuntime(value);
```

**Signature**

```ts
declare const isJobsAdapterRuntime: (value: unknown) => value is JobsAdapterRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L115)

### isJobsAdapterRuntimeEffect

Checks the jobs adapter brand in Effect.

**Example**

```ts
Effect.runSync(isJobsAdapterRuntimeEffect(value));
```

**Signature**

```ts
declare const isJobsAdapterRuntimeEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L99)

### validateJobsCapabilityReport

**Signature**

```ts
declare const validateJobsCapabilityReport: (value: unknown) => JobsCapabilityReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.ts#L42)

## `adapter.types.ts`

### JobsAdapterRuntime (interface)

Provider protocol for submitting, reading, controlling, and observing jobs.

**Signature**

```ts
export interface JobsAdapterRuntime {
  readonly kind: "jobs-adapter-runtime";
  readonly protocolVersion: typeof JOBS_PROTOCOL_VERSION;
  readonly capabilities: JobsCapabilityReport;
  readonly submit: (request: NativeSubmission, context: OperationContext) => Promise<NativeReceipt>;
  readonly get: (locator: NativeLocator, context: OperationContext) => Promise<NativeRun>;
  readonly list: (query: NativeRunQuery, context: OperationContext) => Promise<NativeRunPage>;
  readonly observe: (
    request: NativeWatchRequest,
    context: OperationContext,
  ) => AsyncIterable<NativeObservation>;
  readonly cancel: (
    request: NativeCancelRequest,
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly retry?: (
    request: NativeRetryRequest,
    context: OperationContext,
  ) => Promise<NativeControlReceipt>;
  readonly close: () => Promise<void>;
  readonly worker?: NativeTaskWorker;
  readonly schedules?: NativeScheduleOperations;
  readonly streams?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L93)

### NativeDurableSleep (interface)

Provider-facing durable sleep contract at the adapter boundary.

**Signature**

```ts
export interface NativeDurableSleep {
  readonly sleep: (key: string, durationMs: number) => Promise<void>;
  readonly sleepUntil?: (key: string, instant: string) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L60)

### NativeLocator (type alias)

Provider-facing locator contract at the adapter boundary.

**Signature**

```ts
type NativeLocator = string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L30)

### NativeObservation (type alias)

Provider-facing observation contract at the adapter boundary.

**Signature**

```ts
type NativeObservation = RunWatchFrame<NativeRun>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L28)

### NativeProgressWriter (interface)

Provider-facing progress writer contract at the adapter boundary.

**Signature**

```ts
export interface NativeProgressWriter {
  readonly emit: (
    value: JsonValue,
    context?: OperationContext,
  ) => MaybePromise<ProgressEmitReceipt | void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L44)

### NativeRun (type alias)

Provider-facing run contract at the adapter boundary.

**Signature**

```ts
type NativeRun = RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L22)

### NativeRunPage (type alias)

Provider-facing run page contract at the adapter boundary.

**Signature**

```ts
type NativeRunPage = RunPage<NativeRun>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L26)

### NativeRunQuery (type alias)

Provider-facing run query contract at the adapter boundary.

**Signature**

```ts
type NativeRunQuery = RunListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L24)

### NativeScheduleOperations (interface)

Provider-facing schedule operations contract at the adapter boundary.

**Signature**

```ts
export interface NativeScheduleOperations {
  readonly list: (
    query: Readonly<Record<string, unknown>>,
    context: OperationContext,
  ) => Promise<unknown>;
  readonly get: (id: string, context: OperationContext) => Promise<unknown>;
  readonly upsert: (definition: JsonValue, context: OperationContext) => Promise<unknown>;
  readonly pause: (id: string, context: OperationContext) => Promise<unknown>;
  readonly resume: (id: string, context: OperationContext) => Promise<unknown>;
  readonly delete: (id: string, context: OperationContext) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L32)

### NativeStreamWriter (interface)

Provider-facing stream writer contract at the adapter boundary.

**Signature**

```ts
export interface NativeStreamWriter {
  readonly emit: (
    value: JsonValue,
    context?: OperationContext,
  ) => MaybePromise<ProgressEmitReceipt | void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L51)

### NativeStreamWriters (type alias)

Provider-facing stream writers contract at the adapter boundary.

**Signature**

```ts
type NativeStreamWriters = Readonly<Record<string, NativeStreamWriter>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L58)

### NativeTaskWork (interface)

Provider-facing task work contract at the adapter boundary.

**Signature**

```ts
export interface NativeTaskWork {
  readonly envelope: TaskExecutionEnvelope;
  readonly binding: TaskExecutionBinding;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L118)

### NativeTaskWorker (interface)

Provider worker operations for accepting and completing task work.

**Signature**

```ts
export interface NativeTaskWorker {
  readonly next: (context: OperationContext) => Promise<NativeTaskWork | undefined>;
  readonly complete: (runId: string, output: unknown, context: OperationContext) => Promise<void>;
  readonly fail: (runId: string, error: unknown, context: OperationContext) => Promise<void>;
  /** Returns an intentional provider park/yield to the native continuation owner. */
  readonly suspend?: (runId: string, value: unknown, context: OperationContext) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L123)

### TaskExecutionBinding (interface)

Provider-owned context and sinks supplied to one task execution.

**Signature**

```ts
export interface TaskExecutionBinding {
  readonly run: {
    readonly runId: string;
    readonly jobId: string;
    readonly taskId: string;
    readonly taskVersion: string;
    readonly buildId: string;
    readonly service?: string;
    readonly serviceGeneration?: string;
    readonly attempt?: number;
    readonly acceptedAt?: string;
    readonly scheduledFor?: string;
    readonly parentRunId?: string;
    readonly deadlineMs?: number;
    readonly scope?: string;
    readonly inputSchemaHash?: string;
    readonly acceptanceIdentity?: string;
    readonly occurrenceIdentity?: string;
    readonly propagation?: TracePropagation;
  };
  readonly signal: AbortSignal;
  readonly isSuspension?: (cause: unknown) => boolean;
  readonly sleep?: NativeDurableSleep;
  readonly progress?: NativeProgressWriter;
  readonly streams?: NativeStreamWriters;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L131)

### TaskExecutionEnvelope (interface)

Provider-owned envelope containing the accepted task input and run identity.

**Signature**

```ts
export interface TaskExecutionEnvelope {
  readonly runId: string;
  readonly jobId: string;
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly input: JobWireEnvelope;
  readonly inputHash?: string;
  readonly inputSchemaHash?: string;
  readonly acceptedAt?: string;
  readonly scheduledFor?: string;
  readonly attempt?: number;
  readonly parentRunId?: string;
  readonly service?: string;
  readonly serviceGeneration?: string;
  readonly scope?: string;
  readonly acceptanceIdentity?: string;
  readonly occurrenceIdentity?: string;
  readonly propagation?: TracePropagation;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L65)

### TaskExecutor (interface)

Execution callback used by a native task worker.

**Signature**

```ts
export interface TaskExecutor {
  readonly execute: (
    envelope: TaskExecutionEnvelope,
    binding: TaskExecutionBinding,
  ) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/adapter.types.ts#L86)

## `authorization-cursor-codec.ts`

### createCursorValue

Encodes a bounded authorization cursor, signing it when keys are supplied.

**Throws**

JobCursorError for invalid binding, key, or encoded size.

**Example**

```ts
createCursorValue(binding, { key: "secret" });
```

**Signature**

```ts
declare const createCursorValue: (binding: JobCursorBinding, options?: JobCursorOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor-codec.ts#L13)

### readCursorValue

Decodes and verifies a cursor against the caller's trusted authorization binding.

**Throws**

JobCursorError for invalid encoding, signature, or binding mismatch.

**Example**

```ts
readCursorValue(cursor, expected, { key: "secret" });
```

**Signature**

```ts
declare const readCursorValue: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions,
) => JobCursorBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor-codec.ts#L47)

## `authorization-cursor.ts`

### JobCursorBinding

**Signature**

```ts
declare const JobCursorBinding: JobCursorBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L4)

### JobCursorFailure (class)

A rejected cursor creation or verification.

**Example**

```ts
if (error instanceof JobCursorFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobCursorFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L10)

### JobCursorOptions

**Signature**

```ts
declare const JobCursorOptions: JobCursorOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L4)

### createJobCursor

Synchronous cursor creator.

**Throws**

JobCursorError when the binding or encoded cursor is invalid.

**Example**

```ts
createJobCursor(binding, { key: "secret" });
```

**Signature**

```ts
declare const createJobCursor: (binding: JobCursorBinding, options?: JobCursorOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L39)

### createJobCursorEffect

Creates a bound, optionally signed job cursor in Effect.

**Example**

```ts
Effect.runSync(createJobCursorEffect(binding, { key: "secret" }));
```

**Signature**

```ts
declare const createJobCursorEffect: (
  binding: JobCursorBinding,
  options?: JobCursorOptions | undefined,
) => Effect.Effect<string, JobCursorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L19)

### readJobCursor

Synchronous bound cursor reader.

**Throws**

JobCursorError when the cursor is invalid or has a different binding.

**Example**

```ts
readJobCursor(cursor, expected, { key: "secret" });
```

**Signature**

```ts
declare const readJobCursor: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions,
) => JobCursorBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L72)

### readJobCursorEffect

Reads and verifies a cursor against its expected binding in Effect.

**Example**

```ts
Effect.runSync(readJobCursorEffect(cursor, expected, { key: "secret" }));
```

**Signature**

```ts
declare const readJobCursorEffect: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions | undefined,
) => Effect.Effect<JobCursorBinding, JobCursorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.ts#L51)

## `authorization-cursor.types.ts`

### JobCursorBinding (interface)

Trusted job and scope identity bound into a pagination cursor.

**Signature**

```ts
export interface JobCursorBinding {
  readonly application?: string;
  readonly environment?: string;
  readonly scope: string;
  readonly subject?: string;
  readonly jobId: string;
  readonly operation: JobClientOperation;
  readonly filters: JsonValue;
  readonly schema: string;
  readonly position: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.types.ts#L4)

### JobCursorOptions (interface)

Options accepted for job cursor operations.

**Signature**

```ts
export interface JobCursorOptions {
  readonly key: string | Uint8Array;
  readonly keyId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-cursor.types.ts#L16)

## `authorization-errors.ts`

A caller attempted a job operation outside its trusted grant.

**Example**

```ts
new JobAuthorizationError("Run belongs to another subject");
```

### JobAuthorizationError (class)

A caller attempted a job operation outside its trusted grant.

**Example**

```ts
new JobAuthorizationError("Run belongs to another subject");
```

**Signature**

```ts
declare class JobAuthorizationError {
  constructor(message = "Job operation is not authorized");
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-errors.ts#L4)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_ACCESS_DENIED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-errors.ts#L5)

### JobCursorError (class)

A continuation cursor is malformed or bound to another request.

**Example**

```ts
new JobCursorError();
```

**Signature**

```ts
declare class JobCursorError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-errors.ts#L17)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_CURSOR_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-errors.ts#L18)

## `authorization-failure.ts`

### JobAuthorizationFailure (class)

A denied or malformed jobs authorization decision.

**Example**

```ts
new JobAuthorizationFailure({ reason: "scope" });
```

**Signature**

```ts
declare class JobAuthorizationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-failure.ts#L6)

## `authorization-grant.ts`

### assertAuthorizedOperation

Synchronous compatibility assertion for an authorized operation.

**Throws**

JobAuthorizationError for an invalid grant or request.

**Example**

```ts
assertAuthorizedOperation(grant, request, trusted);
```

**Signature**

```ts
declare const assertAuthorizedOperation: (
  grant: JobAccessGrant,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  now?: number,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-grant.ts#L93)

### assertAuthorizedOperationEffect

Validates a grant and the requested operation in Effect.

**Example**

```ts
Effect.runPromise(assertAuthorizedOperationEffect(grant, request, trusted));
```

**Signature**

```ts
declare const assertAuthorizedOperationEffect: (
  grant: JobAccessGrant,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  now?: number | undefined,
) => Effect.Effect<undefined, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-grant.ts#L70)

### assertJobGrant

Synchronous compatibility assertion for policy grants.

**Throws**

JobAuthorizationError for an invalid or expired grant.

**Example**

```ts
assertJobGrant({ scope: "tenant:a" }, trusted);
```

**Signature**

```ts
declare const assertJobGrant: (
  value: unknown,
  trusted: TrustedJobScope,
  now?: number,
) => asserts value is JobAccessGrant;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-grant.ts#L53)

### assertJobGrantEffect

Validates a grant against a trusted tenant scope and current time.

**Example**

```ts
Effect.runPromise(assertJobGrantEffect({ scope: "tenant:a" }, trusted));
```

**Signature**

```ts
declare const assertJobGrantEffect: (
  value: unknown,
  trusted: TrustedJobScope,
  now?: number | undefined,
) => Effect.Effect<JobAccessGrant, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-grant.ts#L16)

### boundedTextEffect

Checks bounded trusted and grant strings.

**Example**

```ts
Effect.runPromise(boundedTextEffect("tenant:a"));
```

**Signature**

```ts
declare const boundedTextEffect: (
  value: unknown,
) => Effect.Effect<undefined, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-grant.ts#L110)

## `authorization-projection.ts`

### JobProjectionOptions

**Signature**

```ts
declare const JobProjectionOptions: JobProjectionOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.ts#L7)

### projectRunPage

Synchronous compatibility projection of a page.

**Example**

```ts
projectRunPage(page, ["progress"]);
```

**Signature**

```ts
declare const projectRunPage: (
  page: RunPage<RunSnapshot>,
  fields?: readonly JobClientField[],
  options?: JobProjectionOptions,
) => RunPage<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.ts#L104)

### projectRunPageEffect

Projects a page of runs without exposing fields outside the grant.

**Example**

```ts
Effect.runSync(projectRunPageEffect(page, ["progress"]));
```

**Signature**

```ts
declare const projectRunPageEffect: (
  page: RunPage<RunSnapshot>,
  fields?: ReadonlyArray<JobClientField> | undefined,
  options?: JobProjectionOptions | undefined,
) => Effect.Effect<RunPage<RunSnapshot>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.ts#L86)

### projectRunSnapshot

Synchronous compatibility projection of one run.

**Example**

```ts
projectRunSnapshot(run, ["output"]);
```

**Signature**

```ts
declare const projectRunSnapshot: (
  run: RunSnapshot,
  fields?: readonly JobClientField[],
  options?: JobProjectionOptions,
) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.ts#L29)

### projectRunSnapshotEffect

Copies only authorized run fields into a safe client snapshot.

**Example**

```ts
Effect.runSync(projectRunSnapshotEffect(run, ["output"]));
```

**Signature**

```ts
declare const projectRunSnapshotEffect: (
  run: RunSnapshot,
  fields?: ReadonlyArray<JobClientField> | undefined,
  options?: JobProjectionOptions | undefined,
) => Effect.Effect<RunSnapshot, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.ts#L15)

## `authorization-projection.types.ts`

Fields needed to disclose a declared job error safely.

### JobProjectionOptions (interface)

Fields needed to disclose a declared job error safely.

**Signature**

```ts
export interface JobProjectionOptions {
  readonly declaredErrorIds?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization-projection.types.ts#L2)

## `authorization.ts`

### JobAuthorizationError

**Signature**

```ts
declare const JobAuthorizationError: typeof JobAuthorizationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L12)

### JobAuthorizationFailure

**Signature**

```ts
declare const JobAuthorizationFailure: typeof JobAuthorizationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L13)

### JobCursorBinding

**Signature**

```ts
declare const JobCursorBinding: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L27)

### JobCursorError

**Signature**

```ts
declare const JobCursorError: typeof JobCursorError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L12)

### JobCursorFailure

**Signature**

```ts
declare const JobCursorFailure: typeof JobCursorFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L25)

### JobCursorOptions

**Signature**

```ts
declare const JobCursorOptions: any;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L26)

### TrustedJobScope

**Signature**

```ts
declare const TrustedJobScope: TrustedJobScope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L11)

### assertAuthorizedOperation

**Signature**

```ts
declare const assertAuthorizedOperation: (
  grant: JobAccessGrant,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  now?: number,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L17)

### assertAuthorizedOperationEffect

**Signature**

```ts
declare const assertAuthorizedOperationEffect: (
  grant: JobAccessGrant,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  now?: number | undefined,
) => Effect.Effect<undefined, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L18)

### assertJobGrant

**Signature**

```ts
declare const assertJobGrant: (
  value: unknown,
  trusted: TrustedJobScope,
  now?: number,
) => asserts value is JobAccessGrant;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L15)

### assertJobGrantEffect

**Signature**

```ts
declare const assertJobGrantEffect: (
  value: unknown,
  trusted: TrustedJobScope,
  now?: number | undefined,
) => Effect.Effect<JobAccessGrant, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L16)

### authorize

Compatibility alias for authorizeJobAccess.

**Example**

```ts
await authorize(job, request, trusted);
```

**Signature**

```ts
declare const authorize: (
  job: JobDescriptorAny,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  context?: JobAuthorizationContext,
) => Promise<JobAccessGrant>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L120)

### authorizeJobAccess

Promise compatibility adapter for job authorization.
Preflight denials still throw synchronously before a Promise is returned.

**Throws**

JobAuthorizationError for invalid preflight or policy decisions.

**Example**

```ts
await authorizeJobAccess(job, request, trusted);
```

**Signature**

```ts
declare const authorizeJobAccess: (
  job: JobDescriptorAny,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  context?: JobAuthorizationContext,
) => Promise<JobAccessGrant>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L81)

### authorizeJobAccessEffect

Authorizes a job operation against trusted scope in Effect.
Policy callback failures are redacted to a tagged authorization failure.

**Example**

```ts
Effect.runPromise(authorizeJobAccessEffect(job, request, trusted));
```

**Signature**

```ts
declare const authorizeJobAccessEffect: (
  job: JobDescriptorAny,
  request: JobAccessRequest,
  trusted: TrustedJobScope,
  context?: JobAuthorizationContext | undefined,
) => Effect.Effect<Readonly<{ scope: string }>, JobAuthorizationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L44)

### createCursor

Compatibility alias for createJobCursor.

**Example**

```ts
createCursor(options);
```

**Signature**

```ts
declare const createCursor: (binding: JobCursorBinding, options?: JobCursorOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L128)

### createJobCursor

**Signature**

```ts
declare const createJobCursor: (binding: JobCursorBinding, options?: JobCursorOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L21)

### createJobCursorEffect

**Signature**

```ts
declare const createJobCursorEffect: (
  binding: JobCursorBinding,
  options?: JobCursorOptions | undefined,
) => Effect.Effect<string, JobCursorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L22)

### decodeCursor

Compatibility alias for readJobCursor.

**Example**

```ts
decodeCursor(cursor, options);
```

**Signature**

```ts
declare const decodeCursor: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions,
) => JobCursorBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L132)

### projectRun

Compatibility alias for projectRunSnapshot.

**Example**

```ts
projectRun(snapshot, grant);
```

**Signature**

```ts
declare const projectRun: (
  run: RunSnapshot,
  fields?: readonly JobClientField[],
  options?: JobProjectionOptions,
) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L124)

### projectRunPage

**Signature**

```ts
declare const projectRunPage: (
  page: RunPage<RunSnapshot>,
  fields?: readonly JobClientField[],
  options?: JobProjectionOptions,
) => RunPage<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L30)

### projectRunPageEffect

**Signature**

```ts
declare const projectRunPageEffect: (
  page: RunPage<RunSnapshot>,
  fields?: ReadonlyArray<JobClientField> | undefined,
  options?: JobProjectionOptions | undefined,
) => Effect.Effect<RunPage<RunSnapshot>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L31)

### projectRunSnapshot

**Signature**

```ts
declare const projectRunSnapshot: (
  run: RunSnapshot,
  fields?: readonly JobClientField[],
  options?: JobProjectionOptions,
) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L32)

### projectRunSnapshotEffect

**Signature**

```ts
declare const projectRunSnapshotEffect: (
  run: RunSnapshot,
  fields?: ReadonlyArray<JobClientField> | undefined,
  options?: JobProjectionOptions | undefined,
) => Effect.Effect<RunSnapshot, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L33)

### readJobCursor

**Signature**

```ts
declare const readJobCursor: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions,
) => JobCursorBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L23)

### readJobCursorEffect

**Signature**

```ts
declare const readJobCursorEffect: (
  cursor: string,
  expected: JobCursorBinding,
  options?: JobCursorOptions | undefined,
) => Effect.Effect<JobCursorBinding, JobCursorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.ts#L24)

## `authorization.types.ts`

Trusted application and tenant context for a jobs authorization decision.
The scope may be narrowed by a policy but never broadened.

**Example**

```ts
const trusted: TrustedJobScope = { application: "app", environment: "test", scope: "tenant:a" };
```

### TrustedJobScope (interface)

Trusted application and tenant context for a jobs authorization decision.
The scope may be narrowed by a policy but never broadened.

**Example**

```ts
const trusted: TrustedJobScope = { application: "app", environment: "test", scope: "tenant:a" };
```

**Signature**

```ts
export interface TrustedJobScope {
  readonly application: string;
  readonly environment: string;
  readonly scope: string;
  readonly subject?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/authorization.types.ts#L5)

## `canonical-support.ts`

### CanonicalProjectionError (class)

A task schema that cannot be represented as faithful canonical JSON.

**Example**

```ts
new CanonicalProjectionError({ name: "input", reason: "invalid schema" });
```

**Signature**

```ts
declare class CanonicalProjectionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/canonical-support.ts#L7)

### assertCanonicalProjection

Synchronous canonical-schema assertion.

**Throws**

TypeError when the projection is not faithful canonical JSON.

**Example**

```ts
assertCanonicalProjection({ type: "string" }, "input");
```

**Signature**

```ts
declare const assertCanonicalProjection: (
  value: unknown,
  name: string,
  allowVoid?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/canonical-support.ts#L34)

### assertCanonicalProjectionEffect

Traverses a projected schema in Effect, preserving exact validation failures.

**Example**

```ts
Effect.runPromise(assertCanonicalProjectionEffect({ type: "string" }, "input"));
```

**Signature**

```ts
declare const assertCanonicalProjectionEffect: (
  value: unknown,
  name: string,
  allowVoid?: any,
) => Effect.Effect<void, CanonicalProjectionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/canonical-support.ts#L19)

## `capabilities.ts`

### JobsCapability

**Signature**

```ts
declare const JobsCapability: JobsCapability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L9)

### JobsCapabilityError (class)

Compatibility error raised by synchronous capability checks.

**Example**

```ts
if (error instanceof JobsCapabilityError) console.log(error.message);
```

**Signature**

```ts
declare class JobsCapabilityError {
  constructor(capability: string, message = `Jobs capability "${capability}" is unavailable`);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L25)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_CAPABILITY_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L26)

### capability (property)

**Signature**

```ts
readonly capability: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L27)

### JobsCapabilityFailure (class)

A capability rejected by the Effect jobs boundary.

**Example**

```ts
if (error instanceof JobsCapabilityFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobsCapabilityFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L18)

### JobsCapabilityName

**Signature**

```ts
declare const JobsCapabilityName: JobsCapabilityName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L10)

### JobsCapabilityReport

**Signature**

```ts
declare const JobsCapabilityReport: JobsCapabilityReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L11)

### JobsCapabilitySupport

**Signature**

```ts
declare const JobsCapabilitySupport: JobsCapabilitySupport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L12)

### assertAdapterMethods

**Signature**

```ts
declare const assertAdapterMethods: (adapter: JobsAdapterRuntime) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L14)

### assertAdapterMethodsEffect

**Signature**

```ts
declare const assertAdapterMethodsEffect: (
  adapter: JobsAdapterRuntime,
) => Effect.Effect<undefined, JobsCapabilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L14)

### assertJobsCapability

Synchronously requires a supported jobs capability.

**Throws**

JobsCapabilityError when unsupported.

**Example**

```ts
assertJobsCapability(report, "submission");
```

**Signature**

```ts
declare const assertJobsCapability: (report: JobsCapabilityReport, capability: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L59)

### assertJobsCapabilityEffect

Requires support for one jobs capability.

**Example**

```ts
Effect.runSync(assertJobsCapabilityEffect(report, "submission"));
```

**Signature**

```ts
declare const assertJobsCapabilityEffect: (
  report: JobsCapabilityReport,
  capability: string,
) => Effect.Effect<undefined, JobsCapabilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L40)

### validateJobsCapabilityReport

Synchronously validates and freezes a provider report.

**Throws**

JobsCapabilityError when invalid.

**Example**

```ts
validateJobsCapabilityReport(candidate);
```

**Signature**

```ts
declare const validateJobsCapabilityReport: (value: unknown) => JobsCapabilityReport;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L89)

### validateJobsCapabilityReportEffect

Validates and freezes an untrusted provider report in Effect.

**Example**

```ts
Effect.runSync(validateJobsCapabilityReportEffect(candidate));
```

**Signature**

```ts
declare const validateJobsCapabilityReportEffect: (
  value: unknown,
) => Effect.Effect<JobsCapabilityReport, JobsCapabilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.ts#L71)

## `capabilities.types.ts`

Level of support reported by a jobs provider.

### JobsCapability (interface)

Evidence and constraints for one provider capability.

**Signature**

```ts
export interface JobsCapability {
  readonly support: JobsCapabilitySupport;
  readonly constraints?: Readonly<Record<string, unknown>>;
  readonly evidence?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.types.ts#L4)

### JobsCapabilityName (type alias)

Standard jobs capability names.

**Signature**

```ts
type JobsCapabilityName =
  "submission" | "read" | "list" | "observation" | "cancel" | "retry" | "schedules" | "streams";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.types.ts#L20)

### JobsCapabilityReport (interface)

Provider capabilities validated at the jobs boundary.

**Signature**

```ts
export interface JobsCapabilityReport {
  readonly service: string;
  readonly provider?: string;
  readonly adapterId?: string;
  readonly protocolVersion?: 1;
  readonly features: Readonly<Record<string, boolean>>;
  readonly capabilities?: Readonly<Record<string, JobsCapability>>;
  readonly limits?: Readonly<Record<string, number>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.types.ts#L10)

### JobsCapabilitySupport (type alias)

Level of support reported by a jobs provider.

**Signature**

```ts
type JobsCapabilitySupport = "native" | "adapter" | "unsupported" | "unverified";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/capabilities.types.ts#L2)

## `client-abort.ts`

### JobClientAbortFailure (class)

Cancelled, timed out, or failed client enqueue, with the original cause.

**Example**

```ts
if (error instanceof JobClientAbortFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobClientAbortFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-abort.ts#L8)

### runAbortable

Promise compatibility adapter for abortable client work.

**Throws**

The original cancellation, timeout, or provider error.

**Example**

```ts
await runAbortable(signal, undefined, () => Promise.resolve("ok"));
```

**Signature**

```ts
declare const runAbortable: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (signal: AbortSignal) => Promise<A>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-abort.ts#L77)

### runAbortableEffect

Runs client work with an Effect owned abort listener and deadline.

**Example**

```ts
Effect.runPromise(runAbortableEffect(signal, undefined, () => Promise.resolve("ok")));
```

**Signature**

```ts
declare const runAbortableEffect: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (signal: AbortSignal) => Promise<A>,
) => Effect.Effect<Awaited<A>, JobClientAbortFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-abort.ts#L19)

## `client-abort.types.ts`

Cancellation and deadline state owned by one client enqueue.

### JobClientAbortRegistration (interface)

Cancellation and deadline state owned by one client enqueue.

**Signature**

```ts
export interface JobClientAbortRegistration {
  readonly stopped: Promise<Error>;
  readonly failure: () => Error | undefined;
  readonly dispose: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-abort.types.ts#L2)

## `client-errors.ts`

### JobDependencyError (class)

A job call crossed an undeclared function dependency boundary.

**Example**

```ts
new JobDependencyError("billing.charge");
```

**Signature**

```ts
declare class JobDependencyError { constructor(readonly jobId: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L39)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_DEPENDENCY_UNDECLARED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L40)

### JobInputValidationError (class)

Invalid caller input with the schema issues retained for clients.

**Example**

```ts
new JobInputValidationError(issues);
```

**Signature**

```ts
declare class JobInputValidationError { constructor(readonly issues: readonly StandardIssue[]) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L6)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_INPUT_VALIDATION"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L7)

### JobOperationCancelledError (class)

Caller cancellation before the job operation completed.

**Example**

```ts
new JobOperationCancelledError();
```

**Signature**

```ts
declare class JobOperationCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L51)

### code (property)

**Signature**

```ts
readonly code: "ABORT_ERR"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L52)

### JobOperationTimeoutError (class)

A job client operation exceeded its configured timeout.

**Example**

```ts
new JobOperationTimeoutError();
```

**Signature**

```ts
declare class JobOperationTimeoutError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L62)

### code (property)

**Signature**

```ts
readonly code: "ETIMEDOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L63)

### JobProfileError (class)

Requested job provider profile is absent from client configuration.

**Example**

```ts
new JobProfileError("primary");
```

**Signature**

```ts
declare class JobProfileError { constructor(readonly profile: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L17)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_PROFILE_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L18)

### JobProviderError (class)

The selected provider does not implement job enqueue.

**Example**

```ts
new JobProviderError();
```

**Signature**

```ts
declare class JobProviderError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L28)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_PROVIDER_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-errors.ts#L29)

## `client-utils-error.ts`

### ClientUtilityFailure (class)

Expected client helper failure with its original compatibility error.

**Example**

```ts
if (error instanceof ClientUtilityFailure) console.log(error.message);
```

**Signature**

```ts
declare class ClientUtilityFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-error.ts#L6)

## `client-utils-output.ts`

### normalizeResult

Synchronous provider receipt normalizer.

**Throws**

Original normalization error.

**Example**

```ts
normalizeResult(receipt, "default", undefined);
```

**Signature**

```ts
declare const normalizeResult: (
  value: JobProviderResult | undefined,
  profile: string,
  correlationId: string | undefined,
) => JobEnqueueResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L36)

### normalizeResultEffect

Normalizes a provider receipt in Effect.

**Example**

```ts
Effect.runSync(normalizeResultEffect(receipt, "default", undefined));
```

**Signature**

```ts
declare const normalizeResultEffect: (
  value: JobProviderResult | undefined,
  profile: string,
  correlationId: string | undefined,
) => Effect.Effect<JobEnqueueResult, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L18)

### notify

Synchronous client edge hook notification.

**Example**

```ts
notify(onEdge, edge);
```

**Signature**

```ts
declare const notify: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L68)

### notifyEffect

Delivers a client edge hook without changing enqueue outcome in Effect.

**Example**

```ts
Effect.runSync(notifyEffect(onEdge, edge));
```

**Signature**

```ts
declare const notifyEffect: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean | undefined,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L54)

### resolveCorrelation

Synchronous correlation id resolver.

**Throws**

Original callback error.

**Example**

```ts
resolveCorrelation(() => "request");
```

**Signature**

```ts
declare const resolveCorrelation: (value: JobClientOptions["correlationId"]) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L92)

### resolveCorrelationEffect

Resolves a configured correlation id in Effect.

**Example**

```ts
Effect.runSync(resolveCorrelationEffect(() => "request"));
```

**Signature**

```ts
declare const resolveCorrelationEffect: (
  value: string | (() => string | undefined) | undefined,
) => Effect.Effect<string | undefined, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-output.ts#L76)

## `client-utils-validation.ts`

### assertOptionalText

Synchronous optional client text assertion.

**Throws**

TypeError for invalid text.

**Example**

```ts
assertOptionalText("request", "correlationId");
```

**Signature**

```ts
declare const assertOptionalText: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L128)

### assertOptionalTextEffect

Validates optional client text in Effect.

**Example**

```ts
Effect.runSync(assertOptionalTextEffect("request", "correlationId"));
```

**Signature**

```ts
declare const assertOptionalTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L111)

### assertOptions

Synchronous enqueue options assertion.

**Throws**

TypeError for invalid options.

**Example**

```ts
assertOptions({ correlationId: "request" });
```

**Signature**

```ts
declare const assertOptions: (
  value: unknown,
) => asserts value is { readonly correlationId?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L99)

### assertOptionsEffect

Validates enqueue options in Effect.

**Example**

```ts
Effect.runSync(assertOptionsEffect({ correlationId: "request" }));
```

**Signature**

```ts
declare const assertOptionsEffect: (
  value: unknown,
) => Effect.Effect<void, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L84)

### parseInput

Promise compatibility input validator.

**Throws**

Original input validation error.

**Example**

```ts
await parseInput(z.string(), "value");
```

**Signature**

```ts
declare const parseInput: (
  schema: StandardSchemaV1 | undefined,
  input: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L71)

### parseInputEffect

Validates client input against an optional schema in Effect.

**Example**

```ts
Effect.runPromise(parseInputEffect(z.string(), "value"));
```

**Signature**

```ts
declare const parseInputEffect: (
  schema: StandardSchemaV1<unknown, unknown> | undefined,
  input: unknown,
) => Effect.Effect<unknown, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L54)

### resolveProvider

Synchronous provider resolver.

**Throws**

Original profile or provider error.

**Example**

```ts
resolveProvider(source, "default", undefined);
```

**Signature**

```ts
declare const resolveProvider: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => JobProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L37)

### resolveProviderEffect

Resolves a job provider in Effect.

**Example**

```ts
Effect.runSync(resolveProviderEffect(source, "default"));
```

**Signature**

```ts
declare const resolveProviderEffect: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => Effect.Effect<JobProvider, ClientUtilityFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-validation.ts#L19)

## `client-utils-value.ts`

### assertOptionalTextValue

Requires a present optional text field to be nonempty.

**Throws**

TypeError for nontext or blank text.

**Example**

```ts
assertOptionalTextValue("request-1", "correlationId");
```

**Signature**

```ts
declare const assertOptionalTextValue: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L117)

### assertOptionsValue

Validates the client enqueue options shape and correlation identifier.

**Throws**

TypeError for missing object shape or invalid correlation text.

**Example**

```ts
assertOptionsValue({ correlationId: "request-1" });
```

**Signature**

```ts
declare const assertOptionsValue: (
  value: unknown,
) => asserts value is { readonly correlationId?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L104)

### normalizeResultValue

Normalizes a provider acceptance into the public enqueue receipt.

**Example**

```ts
normalizeResultValue(result, "primary", "request-1");
```

**Signature**

```ts
declare const normalizeResultValue: (
  value: JobProviderResult | undefined,
  profile: string,
  correlationId: string | undefined,
) => JobEnqueueResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L52)

### notifyValue

Calls an optional observer without letting hook errors change acceptance.

**Example**

```ts
notifyValue(onAccepted, receipt);
```

**Signature**

```ts
declare const notifyValue: <T>(
  hook: ((value: T) => void) | undefined,
  value: T,
  enabled?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L76)

### parseInputValue

Validates authored client input before enqueueing.

**Throws**

JobInputValidationError for schema issues.

**Example**

```ts
await parseInputValue(schema, { id: "one" });
```

**Signature**

```ts
declare const parseInputValue: (
  schema: StandardSchemaV1 | undefined,
  input: unknown,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L36)

### resolveCorrelationValue

Resolves a literal or lazy client correlation identifier.

**Example**

```ts
resolveCorrelationValue(() => "request-1");
```

**Signature**

```ts
declare const resolveCorrelationValue: (
  value: JobClientOptions["correlationId"],
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L93)

### resolveProviderValue

Resolves an enqueue provider from a named profile or explicit resolver.

**Throws**

JobProfileError or JobProviderError when unavailable.

**Example**

```ts
resolveProviderValue(providers, "primary", undefined);
```

**Signature**

```ts
declare const resolveProviderValue: (
  source: unknown,
  profile: string,
  resolveProfile: ((profile: string) => unknown) | undefined,
) => JobProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils-value.ts#L13)

## `client-utils.ts`

### "./client-utils-output.js" (namespace export)

Re-exports all named exports from the "./client-utils-output.js" module.

**Signature**

```ts
export * from "./client-utils-output.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L2)

### "./client-utils-validation.js" (namespace export)

Re-exports all named exports from the "./client-utils-validation.js" module.

**Signature**

```ts
export * from "./client-utils-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L1)

### ClientUtilityFailure

**Signature**

```ts
declare const ClientUtilityFailure: typeof ClientUtilityFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L4)

### JobClientAbortFailure

**Signature**

```ts
declare const JobClientAbortFailure: typeof JobClientAbortFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L3)

### runAbortable

**Signature**

```ts
declare const runAbortable: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (signal: AbortSignal) => Promise<A>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L3)

### runAbortableEffect

**Signature**

```ts
declare const runAbortableEffect: <A>(
  signal: AbortSignal,
  deadlineMs: number | undefined,
  work: (signal: AbortSignal) => Promise<A>,
) => Effect<Awaited<A>, JobClientAbortFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client-utils.ts#L3)

## `client.ts`

### EffectJobClient

**Signature**

```ts
declare const EffectJobClient: EffectJobClient<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L27)

### JobClient

**Signature**

```ts
declare const JobClient: JobClient<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L26)

### JobClientFailure (class)

Expected client setup or enqueue failure, preserving its original cause.

**Example**

```ts
if (error instanceof JobClientFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobClientFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L47)

### JobClientOptions

**Signature**

```ts
declare const JobClientOptions: JobClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L25)

### JobDeclaredEdge

**Signature**

```ts
declare const JobDeclaredEdge: JobDeclaredEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L23)

### JobDependencyError

**Signature**

```ts
declare const JobDependencyError: typeof JobDependencyError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L33)

### JobEnqueueOptions

**Signature**

```ts
declare const JobEnqueueOptions: JobEnqueueOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L16)

### JobEnqueueResult

**Signature**

```ts
declare const JobEnqueueResult: JobEnqueueResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L16)

### JobInputValidationError

**Signature**

```ts
declare const JobInputValidationError: typeof JobInputValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L30)

### JobInvocationBridge

**Signature**

```ts
declare const JobInvocationBridge: JobInvocationBridge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L22)

### JobInvocationBridgeOptions

**Signature**

```ts
declare const JobInvocationBridgeOptions: JobInvocationBridgeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L21)

### JobObservedEdge

**Signature**

```ts
declare const JobObservedEdge: JobObservedEdge;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L24)

### JobOperationCancelledError

**Signature**

```ts
declare const JobOperationCancelledError: typeof JobOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L34)

### JobOperationContext

**Signature**

```ts
declare const JobOperationContext: JobOperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L18)

### JobOperationTimeoutError

**Signature**

```ts
declare const JobOperationTimeoutError: typeof JobOperationTimeoutError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L35)

### JobProfileError

**Signature**

```ts
declare const JobProfileError: typeof JobProfileError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L31)

### JobProvider

**Signature**

```ts
declare const JobProvider: JobProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L19)

### JobProviderError

**Signature**

```ts
declare const JobProviderError: typeof JobProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L32)

### JobProviderResult

**Signature**

```ts
declare const JobProviderResult: JobProviderResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L20)

### JobState

**Signature**

```ts
declare const JobState: JobState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L16)

### JobStatus

**Signature**

```ts
declare const JobStatus: JobStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L16)

### createJobClient

Synchronous compatibility client factory.

**Throws**

The original invalid profile or provider error.

**Example**

```ts
createJobClient(options);
```

**Signature**

```ts
declare const createJobClient: (options: JobClientOptions) => EffectJobClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L71)

### createJobClientEffect

Creates a jobs enqueue client in Effect.

**Example**

```ts
Effect.runSync(createJobClientEffect(options));
```

**Signature**

```ts
declare const createJobClientEffect: (
  options: JobClientOptions,
) => Effect.Effect<EffectJobClient<unknown>, JobClientFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.ts#L55)

## `client.types.ts`

### EffectJobClient (interface)

A client whose enqueue operation is directly available in Effect.

**Signature**

```ts
export interface EffectJobClient<Input = unknown> extends JobClient<Input> {
  readonly enqueueEffect: (
    input: Input,
    options?: JobEnqueueOptions,
  ) => Effect.Effect<JobEnqueueResult, JobClientFailure>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L84)

### JobClient (interface)

Client operations exposed for a job through its provider.

**Signature**

```ts
export interface JobClient<Input = unknown> {
  readonly enqueue: (input: Input, options?: JobEnqueueOptions) => Promise<JobEnqueueResult>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L80)

### JobClientOptions (interface)

Options accepted for job client operations.

**Signature**

```ts
export interface JobClientOptions {
  readonly ownerId: string;
  readonly jobId: string;
  readonly source: unknown;
  readonly inputSchema?: StandardSchemaV1;
  readonly profile?: string;
  readonly resolveProfile?: (profile: string) => unknown;
  readonly bridge?: JobInvocationBridge;
  readonly signal?: () => AbortSignal;
  readonly deadline?: () => number | undefined;
  readonly correlationId?: string | (() => string | undefined);
  readonly declared?: boolean;
  readonly onDeclaredEdge?: (edge: JobDeclaredEdge) => void;
  readonly onObservedEdge?: (edge: JobObservedEdge) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L64)

### JobClientState (interface)

Resolved dependencies shared by a client's enqueue operations.

**Signature**

```ts
export interface JobClientState {
  readonly options: JobClientOptions;
  readonly ownerId: string;
  readonly jobId: string;
  readonly profile: string;
  readonly declared: boolean;
  readonly provider: JobProvider;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L91)

### JobDeclaredEdge (interface)

Declared dependency between a task and job.

**Signature**

```ts
export interface JobDeclaredEdge {
  readonly kind: "enqueues-job";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L52)

### JobInvocationBridge (interface)

Bridge for invoking jobs from a task execution context.

**Signature**

```ts
export interface JobInvocationBridge {
  readonly run: <A>(
    operation: () => MaybePromise<A>,
    options?: JobInvocationBridgeOptions,
  ) => Promise<A>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L45)

### JobInvocationBridgeOptions (interface)

Options accepted for job invocation bridge operations.

**Signature**

```ts
export interface JobInvocationBridgeOptions {
  readonly name: string;
  readonly attributes: Readonly<Record<string, unknown>>;
  readonly signal: AbortSignal;
  readonly kind?: "producer";
  readonly input?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L37)

### JobObservedEdge (interface)

Job edge recorded during a concrete invocation.

**Signature**

```ts
export interface JobObservedEdge {
  readonly relationship: "enqueues-job";
  readonly from: string;
  readonly to: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L58)

### JobOperationContext (interface)

Trusted job, scope, and signal data available during a client operation.

**Signature**

```ts
export interface JobOperationContext {
  readonly operation: "enqueue";
  readonly signal: AbortSignal;
  readonly profile: string;
  readonly deadlineMs?: number;
  readonly correlationId?: string;
  readonly propagation?: TracePropagation;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L7)

### JobProvider (interface)

Provider callback used to resolve the jobs runtime.

**Signature**

```ts
export interface JobProvider {
  readonly enqueue: (
    input: unknown,
    options: JobEnqueueOptions,
    context: JobOperationContext,
  ) => MaybePromise<JobProviderResult>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L16)

### JobProviderResult (type alias)

Runtime or handle returned by the job provider.

**Signature**

```ts
type JobProviderResult = Pick<JobEnqueueResult, "instanceId" | "accepted"> &
  Partial<
    Pick<
      JobEnqueueResult,
      | "status"
      | "profile"
      | "correlationId"
      | "duplicate"
      | "idempotencyKey"
      | "idempotencyExpiresAt"
    >
  >;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/client.types.ts#L24)

## `control-errors.ts`

### JobControlUnknownError (class)

A native control write may have committed; callers can recover by operation ID.

**Example**

```ts
new JobControlUnknownError("cancel-1", "same-key");
```

**Signature**

```ts
declare class JobControlUnknownError { constructor(
    readonly operationId: string,
    readonly idempotencyKey?: string,
    recovery: JobUnknownOutcome["recovery"] = { action: "inspect-native" },
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L6)

### toJSON (method)

Serializes the bounded recovery contract for callers.

**Example**

```ts
error.toJSON();
```

**Signature**

```ts
declare const toJSON: () => JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L31)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_CONTROL_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L7)

### outcome (property)

**Signature**

```ts
readonly outcome: "unknown"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L8)

### recovery (property)

**Signature**

```ts
readonly recovery: { readonly action: "retry-with-same-key" | "inspect-native" | "unavailable"; readonly expiresAt?: string; }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L9)

### JobObservationTimeoutError (class)

A native observation read exceeded its bounded timeout.

**Example**

```ts
new JobObservationTimeoutError(5_000);
```

**Signature**

```ts
declare class JobObservationTimeoutError { constructor(readonly timeoutMs: number) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L75)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_OBSERVATION_TIMEOUT"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L76)

### JobResultUnavailableError (class)

A completed run has no result available to this caller.

**Example**

```ts
new JobResultUnavailableError("expired");
```

**Signature**

```ts
declare class JobResultUnavailableError { constructor(
    readonly availability: string,
    message = "The requested job result is unavailable",
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L45)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_RESULT_UNAVAILABLE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L46)

### TaskBlockingWaitError (class)

Task execution cannot synchronously wait for another task result.

**Example**

```ts
new TaskBlockingWaitError();
```

**Signature**

```ts
declare class TaskBlockingWaitError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L63)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TASK_BLOCKING_WAIT_UNSUPPORTED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-errors.ts#L64)

## `control-observe.ts`

### JobObserveFailure (class)

Expected run observation failure with its original cause.

**Example**

```ts
if (error instanceof JobObserveFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobObserveFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-observe.ts#L8)

### observeWithTimeout

Compatibility async iterable with scoped iterator cleanup.

**Throws**

Original read, cancellation, or timeout error while consuming.

**Example**

```ts
for await (const frame of observeWithTimeout(source, signal, 1000)) console.log(frame);
```

**Signature**

```ts
declare const observeWithTimeout: (
  source: AsyncIterable<RunWatchFrame<RunSnapshot>>,
  signal: AbortSignal,
  timeoutMs: number,
) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-observe.ts#L31)

### observeWithTimeoutEffect

Creates a scoped run observation stream in Effect.

**Example**

```ts
Effect.runPromise(
  Effect.flatMap(observeWithTimeoutEffect(source, signal, 1000), Stream.runCollect),
);
```

**Signature**

```ts
declare const observeWithTimeoutEffect: (
  source: AsyncIterable<RunWatchFrame<RunSnapshot>>,
  signal: AbortSignal,
  timeoutMs: number,
) => Effect.Effect<
  Stream.Stream<RunWatchFrame<RunSnapshot>, JobObserveFailure, never>,
  never,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-observe.ts#L19)

## `control-result.ts`

### JobResultFailure (class)

Expected result polling failure retaining its original cause.

**Example**

```ts
if (error instanceof JobResultFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobResultFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L27)

### ReadRun

**Signature**

```ts
declare const ReadRun: ReadRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L11)

### ResultRunReader (class)

Injectable run snapshot reader for result polling.

**Example**

```ts
const service = yield * ResultRunReader;
```

**Signature**

```ts
declare class ResultRunReader
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L15)

### resultRunReaderLayer

Provides a snapshot reader for deterministic result polling.

**Example**

```ts
Effect.provide(waitForResultEffect(runtime, id, options), resultRunReaderLayer(readRun));
```

**Signature**

```ts
declare const resultRunReaderLayer: (
  readRun: ReadRun,
) => Layer.Layer<ResultRunReader, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L23)

### waitForResult

Promise compatibility result polling.

**Throws**

Original validation, cancellation, read, or availability error.

**Example**

```ts
await waitForResult(runtime, id, options, readRun);
```

**Signature**

```ts
declare const waitForResult: (
  runtime: JobsRuntime,
  runId: string,
  options: RunResultOptions,
  readRun: ReadRun,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L131)

### waitForResultEffect

Polls for a terminal result with Effect Clock and an owned abort listener.

**Example**

```ts
Effect.runPromise(
  Effect.provide(waitForResultEffect(runtime, id, options), resultRunReaderLayer(readRun)),
);
```

**Signature**

```ts
declare const waitForResultEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: RunResultOptions,
) => Effect.Effect<unknown, JobResultFailure, ResultRunReader>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.ts#L37)

## `control-result.types.ts`

### ReadRun (type alias)

Substitutable snapshot reader for result polling.

**Signature**

```ts
type ReadRun = (runtime: JobsRuntime, runId: string, signal?: AbortSignal) => Promise<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-result.types.ts#L4)

## `control-support-methods.ts`

### operationContext

Synchronous native operation context creator.

**Throws**

Original runtime context error.

**Example**

```ts
operationContext(runtime, undefined);
```

**Signature**

```ts
declare const operationContext: (
  runtime: JobsRuntime,
  signal: AbortSignal | undefined,
  operationId?: string,
) => OperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L31)

### operationContextEffect

Creates a native operation context in Effect.

**Example**

```ts
Effect.runSync(operationContextEffect(runtime, undefined));
```

**Signature**

```ts
declare const operationContextEffect: (
  runtime: JobsRuntime,
  signal: AbortSignal | undefined,
  operationId?: string | undefined,
) => Effect.Effect<OperationContext, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L17)

### requireMethod

Synchronous native method and capability assertion.

**Throws**

JobsCapabilityError when unavailable.

**Example**

```ts
requireMethod(runtime, "read", "get");
```

**Signature**

```ts
declare const requireMethod: (
  runtime: JobsRuntime,
  capability: string,
  method: keyof JobsRuntime["adapter"],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L59)

### requireMethodEffect

Requires a native adapter method and capability in Effect.

**Example**

```ts
Effect.runSync(requireMethodEffect(runtime, "read", "get"));
```

**Signature**

```ts
declare const requireMethodEffect: (
  runtime: JobsRuntime,
  capability: string,
  method: keyof JobsAdapterRuntime,
) => Effect.Effect<void, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L45)

### requireOperationId

Synchronous bounded control operation ID assertion.

**Throws**

TypeError when missing or too long.

**Example**

```ts
requireOperationId("cancel-1");
```

**Signature**

```ts
declare const requireOperationId: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L81)

### requireOperationIdEffect

Validates a bounded control operation ID in Effect.

**Example**

```ts
Effect.runSync(requireOperationIdEffect("cancel-1"));
```

**Signature**

```ts
declare const requireOperationIdEffect: (
  value: string,
) => Effect.Effect<void, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-methods.ts#L71)

## `control-support-observation.ts`

### isControlRecordEffect

Tests for a nonarray record in Effect.

**Example**

```ts
Effect.runSync(isControlRecordEffect({ id: "run" }));
```

**Signature**

```ts
declare const isControlRecordEffect: (
  value: unknown,
) => Effect.Effect<boolean, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L52)

### isRecord

Synchronous nonarray record type guard.

**Example**

```ts
isRecord({ id: "run" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L60)

### isTerminal

Synchronous terminal run status test.

**Example**

```ts
isTerminal(run);
```

**Signature**

```ts
declare const isTerminal: (run: RunSnapshot) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L24)

### isTerminalEffect

Tests whether a run is terminal in Effect.

**Example**

```ts
Effect.runSync(isTerminalEffect(run));
```

**Signature**

```ts
declare const isTerminalEffect: (
  run: RunSnapshot,
) => Effect.Effect<boolean, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L16)

### observerTimeout

Synchronous bounded native observation timeout.

**Throws**

RangeError for an unsafe duration.

**Example**

```ts
observerTimeout(runtime);
```

**Signature**

```ts
declare const observerTimeout: (runtime: JobsRuntime, authored?: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L44)

### observerTimeoutEffect

Computes a bounded native observation read timeout in Effect.

**Example**

```ts
Effect.runSync(observerTimeoutEffect(runtime));
```

**Signature**

```ts
declare const observerTimeoutEffect: (
  runtime: JobsRuntime,
  authored?:
    | `${number} second`
    | `${number} seconds`
    | `${number} minute`
    | `${number} minutes`
    | `${number} hour`
    | `${number} hours`
    | `${number} day`
    | `${number} days`
    | `${number} week`
    | `${number} weeks`
    | `${number} millisecond`
    | `${number} milliseconds`
    | undefined,
) => Effect.Effect<number, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-observation.ts#L33)

## `control-support-receipts.ts`

### isUnknown

Synchronous uncertain outcome type guard.

**Example**

```ts
if (isUnknown(response)) console.log(response.operationId);
```

**Signature**

```ts
declare const isUnknown: (value: unknown) => value is UnknownControlOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L77)

### isUnknownEffect

Tests an uncertain native outcome in Effect.

**Example**

```ts
Effect.runSync(isUnknownEffect(response));
```

**Signature**

```ts
declare const isUnknownEffect: (
  value: unknown,
) => Effect.Effect<boolean, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L69)

### normalizeCancellationReceipt

Synchronous cancellation receipt normalizer.

**Throws**

TypeError for a mismatched or malformed receipt.

**Example**

```ts
normalizeCancellationReceipt(value, "run", "cancel");
```

**Signature**

```ts
declare const normalizeCancellationReceipt: (
  value: unknown,
  runId: string,
  operationId: string,
) => RunCancellationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L37)

### normalizeCancellationReceiptEffect

Normalizes a native cancellation receipt in Effect.

**Example**

```ts
Effect.runSync(normalizeCancellationReceiptEffect(value, "run", "cancel"));
```

**Signature**

```ts
declare const normalizeCancellationReceiptEffect: (
  value: unknown,
  runId: string,
  operationId: string,
) => Effect.Effect<RunCancellationReceipt, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L23)

### normalizeRetryReceipt

Synchronous retry receipt normalizer.

**Throws**

TypeError for a mismatched or malformed receipt.

**Example**

```ts
normalizeRetryReceipt(value, "run-1");
```

**Signature**

```ts
declare const normalizeRetryReceipt: (value: unknown, originalRunId: string) => RunRetryReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L61)

### normalizeRetryReceiptEffect

Normalizes a native retry receipt in Effect.

**Example**

```ts
Effect.runSync(normalizeRetryReceiptEffect(value, "run-1"));
```

**Signature**

```ts
declare const normalizeRetryReceiptEffect: (
  value: unknown,
  originalRunId: string,
) => Effect.Effect<RunRetryReceipt, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L50)

### unknownKey

Synchronous uncertain outcome key reader.

**Example**

```ts
unknownKey(response);
```

**Signature**

```ts
declare const unknownKey: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L93)

### unknownKeyEffect

Reads an uncertain outcome's idempotency key in Effect.

**Example**

```ts
Effect.runSync(unknownKeyEffect(response));
```

**Signature**

```ts
declare const unknownKeyEffect: (
  value: unknown,
) => Effect.Effect<string | undefined, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L85)

### unknownRecovery

Synchronous uncertain outcome recovery reader.

**Example**

```ts
unknownRecovery(response);
```

**Signature**

```ts
declare const unknownRecovery: (value: unknown) => JobUnknownOutcome["recovery"] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L109)

### unknownRecoveryEffect

Reads bounded recovery guidance in Effect.

**Example**

```ts
Effect.runSync(unknownRecoveryEffect(response));
```

**Signature**

```ts
declare const unknownRecoveryEffect: (value: unknown) => Effect.Effect<
  | {
      readonly action: "retry-with-same-key" | "inspect-native" | "unavailable";
      readonly expiresAt?: string;
    }
  | undefined,
  ControlSupportFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-receipts.ts#L101)

## `control-support-run.ts`

### ControlSupportFailure (class)

Expected run control helper failure with its original cause.

**Example**

```ts
if (error instanceof ControlSupportFailure) console.log(error.message);
```

**Signature**

```ts
declare class ControlSupportFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-run.ts#L7)

### controlSupportEffect

Runs a control helper inside an observed Effect.

**Example**

```ts
controlSupportEffect("controls.read", () => receipt);
```

**Signature**

```ts
declare const controlSupportEffect: <A>(
  operation: JobsOperation,
  compute: () => A,
) => Effect.Effect<A, ControlSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-run.ts#L17)

### runControlSupport

Synchronous control helper compatibility runner.

**Throws**

The original helper error on failure.

**Example**

```ts
runControlSupport(controlSupportEffect("controls.read", () => receipt));
```

**Signature**

```ts
declare const runControlSupport: <A>(effect: Effect.Effect<A, ControlSupportFailure>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-run.ts#L32)

## `control-support-value-observation.ts`

### isTerminal

Tests whether a run has reached a terminal state.

**Example**

```ts
isTerminal(snapshot);
```

**Signature**

```ts
declare const isTerminal: (run: RunSnapshot) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value-observation.ts#L10)

### observerTimeout

Resolves a bounded per-read observation timeout.

**Throws**

RangeError for invalid or oversized timeouts.

**Example**

```ts
observerTimeout(runtime, "2 seconds");
```

**Signature**

```ts
declare const observerTimeout: (runtime: JobsRuntime, authored?: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value-observation.ts#L26)

## `control-support-value.ts`

### isRecord

Tests for a nonarray native response record.

**Example**

```ts
isRecord({ outcome: "requested" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L178)

### isTerminal

**Signature**

```ts
declare const isTerminal: (run: RunSnapshot) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L11)

### isUnknown

Recognizes an uncertain native control outcome.

**Example**

```ts
isUnknown(response);
```

**Signature**

```ts
declare const isUnknown: (value: unknown) => value is UnknownControlOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L137)

### normalizeCancellationReceipt

Validates and freezes a native cancellation receipt.

**Throws**

TypeError for mismatched identities or invalid fields.

**Example**

```ts
normalizeCancellationReceipt(receipt, "run-1", "cancel-1");
```

**Signature**

```ts
declare const normalizeCancellationReceipt: (
  value: unknown,
  runId: string,
  operationId: string,
) => RunCancellationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L75)

### normalizeRetryReceipt

Validates that a native retry created a new run from the original.

**Throws**

TypeError for missing durable identity or reused run ID.

**Example**

```ts
normalizeRetryReceipt(receipt, "run-1");
```

**Signature**

```ts
declare const normalizeRetryReceipt: (value: unknown, originalRunId: string) => RunRetryReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L108)

### observerTimeout

**Signature**

```ts
declare const observerTimeout: (runtime: JobsRuntime, authored?: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L11)

### operationContext

Builds a native context with a caller signal and optional operation ID.

**Example**

```ts
operationContext(runtime, undefined, "cancel-1");
```

**Signature**

```ts
declare const operationContext: (
  runtime: JobsRuntime,
  signal: AbortSignal | undefined,
  operationId?: string,
) => OperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L19)

### requireMethod

Requires a provider method and its reported capability.

**Throws**

JobsCapabilityError when unavailable.

**Example**

```ts
requireMethod(runtime, "read", "get");
```

**Signature**

```ts
declare const requireMethod: (
  runtime: JobsRuntime,
  capability: string,
  method: keyof JobsRuntime["adapter"],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L37)

### requireOperationId

Validates a bounded idempotent control operation identity.

**Throws**

TypeError for blank or oversized IDs.

**Example**

```ts
requireOperationId("cancel-1");
```

**Signature**

```ts
declare const requireOperationId: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L58)

### unknownKey

Reads an optional idempotency key from an uncertain outcome.

**Example**

```ts
unknownKey(response);
```

**Signature**

```ts
declare const unknownKey: (value: unknown) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L148)

### unknownRecovery

Copies a recognized native recovery action from an uncertain outcome.

**Example**

```ts
unknownRecovery(response);
```

**Signature**

```ts
declare const unknownRecovery: (value: unknown) => JobUnknownOutcome["recovery"] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support-value.ts#L158)

## `control-support.ts`

### "./control-support-methods.js" (namespace export)

Re-exports all named exports from the "./control-support-methods.js" module.

**Signature**

```ts
export * from "./control-support-methods.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L1)

### "./control-support-observation.js" (namespace export)

Re-exports all named exports from the "./control-support-observation.js" module.

**Signature**

```ts
export * from "./control-support-observation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L3)

### "./control-support-receipts.js" (namespace export)

Re-exports all named exports from the "./control-support-receipts.js" module.

**Signature**

```ts
export * from "./control-support-receipts.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L2)

### ControlSupportFailure

**Signature**

```ts
declare const ControlSupportFailure: typeof ControlSupportFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L4)

### JobObserveFailure

**Signature**

```ts
declare const JobObserveFailure: typeof JobObserveFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L8)

### JobObserveOptions

**Signature**

```ts
declare const JobObserveOptions: JobObserveOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L10)

### UnknownControlOutcome

**Signature**

```ts
declare const UnknownControlOutcome: UnknownControlOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L10)

### observeWithTimeout

**Signature**

```ts
declare const observeWithTimeout: (
  source: AsyncIterable<RunWatchFrame<RunSnapshot>>,
  signal: AbortSignal,
  timeoutMs: number,
) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L6)

### observeWithTimeoutEffect

**Signature**

```ts
declare const observeWithTimeoutEffect: (
  source: AsyncIterable<RunWatchFrame<RunSnapshot>>,
  signal: AbortSignal,
  timeoutMs: number,
) => Effect<Stream<RunWatchFrame<RunSnapshot>, JobObserveFailure, never>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.ts#L7)

## `control-support.types.ts`

### JobObserveOptions (interface)

Signal and per-read timeout for native run observation.

**Signature**

```ts
export interface JobObserveOptions {
  readonly signal?: AbortSignal;
  readonly timeout?: DurationInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.types.ts#L4)

### UnknownControlOutcome (interface)

Native control response with an uncertain outcome.

**Signature**

```ts
export interface UnknownControlOutcome {
  readonly operationId: string;
  readonly idempotencyKey?: string;
  readonly outcome: "unknown";
  readonly recovery?: JobUnknownOutcome["recovery"];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-support.types.ts#L9)

## `control-write.ts`

### JobControlWriteFailure (class)

A cancelled, uncertain, or provider-failed native control write.

**Example**

```ts
new JobControlWriteFailure({ operationId: "op", kind: "unknown", cause: new Error() });
```

**Signature**

```ts
declare class JobControlWriteFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-write.ts#L9)

### controlWrite

Promise compatibility adapter for native control writes.

**Throws**

The original cancellation, unknown-outcome, or provider error.

**Example**

```ts
await controlWrite(() => Promise.resolve("ok"), undefined, "op");
```

**Signature**

```ts
declare const controlWrite: <A>(
  call: () => Promise<A>,
  signal: AbortSignal | undefined,
  operationId: string,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-write.ts#L72)

### controlWriteEffect

Calls a native control write with an Effect-managed abort listener.
Cancellation before the provider begins prevents the call. Cancellation
after start produces an unknown outcome requiring operation-id recovery.

**Example**

```ts
Effect.runPromise(controlWriteEffect(() => Promise.resolve("ok"), undefined, "op"));
```

**Signature**

```ts
declare const controlWriteEffect: <A>(
  call: () => Promise<A>,
  signal: AbortSignal | undefined,
  operationId: string,
) => Effect.Effect<A, JobControlWriteFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-write.ts#L23)

## `control-write.types.ts`

Lifetime of one registered abort listener for a native control write.

### ControlWriteRegistration (interface)

Lifetime of one registered abort listener for a native control write.

**Signature**

```ts
export interface ControlWriteRegistration {
  readonly aborted: Promise<void>;
  readonly isAborted: () => boolean;
  readonly dispose: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/control-write.types.ts#L2)

## `controls-factory.ts`

### createJobsControls

Synchronous factory for a run controls facade.

**Example**

```ts
createJobsControls(runtime);
```

**Signature**

```ts
declare const createJobsControls: (runtime?: JobsRuntime) => JobsControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-factory.ts#L44)

### createJobsControlsEffect

Builds a run controls facade in Effect.

**Example**

```ts
Effect.runSync(createJobsControlsEffect(runtime));
```

**Signature**

```ts
declare const createJobsControlsEffect: (
  runtime: JobsRuntime,
) => Effect.Effect<JobsControls, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-factory.ts#L16)

## `controls-observe.ts`

### observeRun

Synchronous compatibility adapter for run observation.

**Throws**

The original capability or provider error during setup.

**Example**

```ts
for await (const frame of observeRun(runtime, request)) console.log(frame);
```

**Signature**

```ts
declare const observeRun: (
  runtime: JobsRuntime,
  request: NativeWatchRequest,
  options?: JobObserveOptions,
) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-observe.ts#L35)

### observeRunEffect

Acquires an async run observation iterator in Effect.
The caller owns iterator consumption and should close it on early exit.

**Example**

```ts
Effect.runSync(observeRunEffect(runtime, request));
```

**Signature**

```ts
declare const observeRunEffect: (
  runtime: JobsRuntime,
  request: NativeWatchRequest,
  options?: JobObserveOptions | undefined,
) => Effect.Effect<AsyncIterable<RunWatchFrame<RunSnapshot>>, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-observe.ts#L17)

## `controls-operations.ts`

### cancelRunValue

**Signature**

```ts
declare const cancelRunValue: (
  runtime: JobsRuntime,
  runId: string,
  options: JobCancelOptions,
) => Promise<RunCancellationReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-operations.ts#L12)

### getRunValue

**Signature**

```ts
declare const getRunValue: (
  runtime: JobsRuntime,
  locator: string,
  signal?: AbortSignal,
) => Promise<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-operations.ts#L11)

### listRunsValue

**Signature**

```ts
declare const listRunsValue: (
  runtime: JobsRuntime,
  query?: RunListQuery,
  signal?: AbortSignal,
) => Promise<RunPage<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-operations.ts#L11)

### observeRunValue

Builds a native run observation with a scoped iterator timeout.
The consumer owns the iterator and must close it on early exit.

**Throws**

The original capability or observer setup error.

**Example**

```ts
for await (const frame of observeRunValue(runtime, request)) console.log(frame);
```

**Signature**

```ts
declare const observeRunValue: (
  runtime: JobsRuntime,
  request: NativeWatchRequest,
  options?: JobObserveOptions,
) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-operations.ts#L22)

### retryRunValue

**Signature**

```ts
declare const retryRunValue: (
  runtime: JobsRuntime,
  runId: string,
  options: JobRetryOptions,
) => Promise<RunRetryReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-operations.ts#L12)

## `controls-read.ts`

### ControlReadFailure (class)

Expected native run read failure with its original compatibility cause.

**Example**

```ts
new ControlReadFailure({ cause: new Error("read unavailable") });
```

**Signature**

```ts
declare class ControlReadFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-read.ts#L8)

### getRunOperationEffect

Checks read capability and requests one native run in Effect.

**Example**

```ts
Effect.runPromise(getRunOperationEffect(runtime, "run-1"));
```

**Signature**

```ts
declare const getRunOperationEffect: (
  runtime: JobsRuntime,
  locator: string,
  signal?: AbortSignal | undefined,
) => Effect.Effect<NativeRun, ControlReadFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-read.ts#L19)

### getRunValue

Promise compatibility read for internal control consumers.

**Throws**

The original capability, context, or provider error.

**Example**

```ts
await getRunValue(runtime, "run-1");
```

**Signature**

```ts
declare const getRunValue: (
  runtime: JobsRuntime,
  locator: string,
  signal?: AbortSignal,
) => Promise<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-read.ts#L45)

### listRunsOperationEffect

Checks list capability and validates the page limit before native IO.

**Example**

```ts
Effect.runPromise(listRunsOperationEffect(runtime, { limit: 25 }));
```

**Signature**

```ts
declare const listRunsOperationEffect: (
  runtime: JobsRuntime,
  query?: RunListQuery | undefined,
  signal?: AbortSignal | undefined,
) => Effect.Effect<NativeRunPage, ControlReadFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-read.ts#L63)

### listRunsValue

Promise compatibility listing for internal control consumers.

**Throws**

The original capability, limit, context, or provider error.

**Example**

```ts
await listRunsValue(runtime, { limit: 25 });
```

**Signature**

```ts
declare const listRunsValue: (
  runtime: JobsRuntime,
  query?: RunListQuery,
  signal?: AbortSignal,
) => Promise<RunPage<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-read.ts#L94)

## `controls-write-operations.ts`

### ControlOperationFailure (class)

Expected native control operation failure with its compatibility cause.

**Example**

```ts
new ControlOperationFailure({ cause: new Error("provider rejected") });
```

**Signature**

```ts
declare class ControlOperationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-write-operations.ts#L21)

### cancelRunOperationEffect

Validates and submits an idempotent native cancellation in Effect.

**Example**

```ts
Effect.runPromise(cancelRunOperationEffect(runtime, "run", { operationId: "op" }));
```

**Signature**

```ts
declare const cancelRunOperationEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: JobCancelOptions,
) => Effect.Effect<RunCancellationReceipt, ControlOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-write-operations.ts#L32)

### cancelRunValue

Promise compatibility cancellation for internal control consumers.

**Throws**

The original capability, cancellation, provider, or receipt error.

**Example**

```ts
await cancelRunValue(runtime, "run", { operationId: "op" });
```

**Signature**

```ts
declare const cancelRunValue: (
  runtime: JobsRuntime,
  runId: string,
  options: JobCancelOptions,
) => Promise<RunCancellationReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-write-operations.ts#L81)

### retryRunOperationEffect

Reuses pinned run identity to request a fresh native retry in Effect.

**Example**

```ts
Effect.runPromise(retryRunOperationEffect(runtime, "run", { operationId: "op" }));
```

**Signature**

```ts
declare const retryRunOperationEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: JobRetryOptions,
) => Effect.Effect<RunRetryReceipt, ControlOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-write-operations.ts#L99)

### retryRunValue

Promise compatibility retry for internal control consumers.

**Throws**

The original capability, provider, cancellation, or receipt error.

**Example**

```ts
await retryRunValue(runtime, "run", { operationId: "op" });
```

**Signature**

```ts
declare const retryRunValue: (
  runtime: JobsRuntime,
  runId: string,
  options: JobRetryOptions,
) => Promise<RunRetryReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls-write-operations.ts#L175)

## `controls.ts`

### JobCancelOptions

**Signature**

```ts
declare const JobCancelOptions: JobCancelOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L19)

### JobControlFailure (class)

Expected failure while reading or changing a job run.

**Example**

```ts
if (error instanceof JobControlFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobControlFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L24)

### JobObserveOptions

**Signature**

```ts
declare const JobObserveOptions: JobObserveOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L20)

### JobRetryOptions

**Signature**

```ts
declare const JobRetryOptions: JobRetryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L19)

### JobsControls

**Signature**

```ts
declare const JobsControls: JobsControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L19)

### cancelRun

Promise compatibility adapter for cancellation.

**Throws**

The original provider or control error.

**Example**

```ts
await cancelRun(runtime, "run-1", { operationId: "op" });
```

**Signature**

```ts
declare const cancelRun: (
  runtime: JobsRuntime,
  runId: string,
  options: JobCancelOptions,
) => Promise<RunCancellationReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L119)

### cancelRunEffect

Cancels a run in Effect.

**Example**

```ts
Effect.runPromise(cancelRunEffect(runtime, "run-1", { operationId: "op" }));
```

**Signature**

```ts
declare const cancelRunEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: JobCancelOptions,
) => Effect.Effect<RunCancellationReceipt, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L101)

### createJobsControls

**Signature**

```ts
declare const createJobsControls: (runtime?: JobsRuntime) => JobsControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L28)

### createJobsControlsEffect

**Signature**

```ts
declare const createJobsControlsEffect: (
  runtime: JobsRuntime,
) => Effect.Effect<JobsControls, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L28)

### getRun

Promise compatibility adapter for native run reads.

**Throws**

The original provider or capability error.

**Example**

```ts
await getRun(runtime, "run-1");
```

**Signature**

```ts
declare const getRun: (
  runtime: JobsRuntime,
  locator: string,
  signal?: AbortSignal,
) => Promise<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L54)

### getRunEffect

Reads a native run in Effect.

**Example**

```ts
Effect.runPromise(getRunEffect(runtime, "run-1"));
```

**Signature**

```ts
declare const getRunEffect: (
  runtime: JobsRuntime,
  locator: string,
  signal?: AbortSignal | undefined,
) => Effect.Effect<NativeRun, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L36)

### listRuns

Promise compatibility adapter for native run listings.

**Throws**

The original provider, capability, or limit error.

**Example**

```ts
await listRuns(runtime);
```

**Signature**

```ts
declare const listRuns: (
  runtime: JobsRuntime,
  query?: RunListQuery,
  signal?: AbortSignal,
) => Promise<RunPage<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L86)

### listRunsEffect

Lists native runs in Effect.

**Example**

```ts
Effect.runPromise(listRunsEffect(runtime));
```

**Signature**

```ts
declare const listRunsEffect: (
  runtime: JobsRuntime,
  query?: RunListQuery | undefined,
  signal?: AbortSignal | undefined,
) => Effect.Effect<NativeRunPage, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L68)

### observeRun

**Signature**

```ts
declare const observeRun: (
  runtime: JobsRuntime,
  request: NativeWatchRequest,
  options?: JobObserveOptions,
) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L93)

### observeRunEffect

**Signature**

```ts
declare const observeRunEffect: (
  runtime: JobsRuntime,
  request: NativeWatchRequest,
  options?: JobObserveOptions | undefined,
) => Effect.Effect<AsyncIterable<RunWatchFrame<RunSnapshot>>, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L93)

### retryRun

Promise compatibility adapter for retry.

**Throws**

The original provider or control error.

**Example**

```ts
await retryRun(runtime, "run-1", { operationId: "op" });
```

**Signature**

```ts
declare const retryRun: (
  runtime: JobsRuntime,
  runId: string,
  options: JobRetryOptions,
) => Promise<RunRetryReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L151)

### retryRunEffect

Retries a run in Effect.

**Example**

```ts
Effect.runPromise(retryRunEffect(runtime, "run-1", { operationId: "op" }));
```

**Signature**

```ts
declare const retryRunEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: JobRetryOptions,
) => Effect.Effect<RunRetryReceipt, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L133)

### waitForResult

Promise compatibility adapter for result waiting.

**Throws**

The original observation or result error.

**Example**

```ts
await waitForResult(runtime, "run-1", { timeout: "1 second" });
```

**Signature**

```ts
declare const waitForResult: (
  runtime: JobsRuntime,
  runId: string,
  options: RunResultOptions,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L186)

### waitForResultEffect

Waits for a run result in Effect.

**Example**

```ts
Effect.runPromise(waitForResultEffect(runtime, "run-1", { timeout: "1 second" }));
```

**Signature**

```ts
declare const waitForResultEffect: (
  runtime: JobsRuntime,
  runId: string,
  options: RunResultOptions,
) => Effect.Effect<unknown, JobControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.ts#L165)

## `controls.types.ts`

### JobCancelOptions (interface)

Options accepted for job cancel operations.

**Signature**

```ts
export interface JobCancelOptions {
  readonly operationId: string;
  readonly reason?: string;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.types.ts#L14)

### JobRetryOptions (interface)

Options accepted for job retry operations.

**Signature**

```ts
export interface JobRetryOptions {
  readonly operationId: string;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.types.ts#L20)

### JobsControls (interface)

Run read, observation, cancellation, retry, result, and schedule operations.

**Signature**

```ts
export interface JobsControls {
  readonly get: (
    locator: string,
    options?: { readonly signal?: AbortSignal },
  ) => Promise<RunSnapshot>;
  readonly list: (
    query?: RunListQuery,
    options?: { readonly signal?: AbortSignal },
  ) => Promise<RunPage<RunSnapshot>>;
  readonly observe: (
    request: NativeWatchRequest,
    options?: JobObserveOptions,
  ) => AsyncIterable<RunWatchFrame<RunSnapshot>>;
  readonly cancel: (runId: string, options: JobCancelOptions) => Promise<RunCancellationReceipt>;
  readonly retry: (runId: string, options: JobRetryOptions) => Promise<RunRetryReceipt>;
  readonly result: (runId: string, options: RunResultOptions) => Promise<unknown>;
  readonly schedules?: JobScheduleClient;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/controls.types.ts#L25)

## `define-job-value.ts`

### defineJobValue

Binds a task to a named job with immutable scheduling and client policy metadata.

**Example**

```ts
import { defineJob } from "@relkit/app/jobs";
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
const task = defineTask({
  id: "receipts.send",
  version: "1",
  input: z.object({ orderId: z.string() }),
  output: z.object({ sent: z.boolean() }),
  handler: async () => ({ sent: true }),
});
const job = defineJob({ name: "sendReceipt", task });
void job;
```

**Signature**

```ts
declare const defineJobValue: <
  const Name extends string,
  const Task extends TaskDescriptorAny,
  const Id extends string = Name,
>(
  options: DefineJobOptions<Name, Task, Id>,
) => JobDescriptor<Name, Id, Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job-value.ts#L64)

Since v0.4.1

### JOB_PROFILE_DEPRECATED_CODE

Diagnostic code used when the one-release profile spelling is consumed as service.

**Example**

```ts
JOB_PROFILE_DEPRECATED_CODE === "RELKIT_JOB_PROFILE_DEPRECATED";
```

**Signature**

```ts
declare const JOB_PROFILE_DEPRECATED_CODE: "RELKIT_JOB_PROFILE_DEPRECATED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job-value.ts#L17)

### RetryJitter

**Signature**

```ts
declare const RetryJitter: RetryJitter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job-value.ts#L19)

### RetryPolicy

**Signature**

```ts
declare const RetryPolicy: RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job-value.ts#L19)

### isJobDescriptorValue

Checks the runtime descriptor brand and task association.

**Example**

```ts
isJobDescriptorValue(candidate);
```

**Signature**

```ts
declare const isJobDescriptorValue: (value: unknown) => value is JobDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job-value.ts#L122)

## `define-job.ts`

### defineJob

Binds a task to an immutable job descriptor.

**Throws**

Original validation error for invalid definitions.

**Example**

```ts
import { defineJob, defineTask } from "@relkit/jobs";
import { z } from "@relkit/schema";
const echo = defineTask({
  id: "echo",
  version: "1",
  input: z.string(),
  output: z.string(),
  execution: "retryable",
  handler: async (input) => input,
});
const echoJob = defineJob({ name: "echoJob", task: echo });
```

**Signature**

```ts
declare const defineJob: <
  const Name extends string,
  const Task extends TaskDescriptorAny,
  const Id extends string = Name,
>(
  options: DefineJobOptions<Name, Task, Id>,
) => JobDescriptor<Name, Id, Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L49)

Since v0.4.1

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/orders/jobs/export-orders.job.ts"
/** Registers the export task as a public job exposing trigger, get, list and watch with progress/output fields. */
import { defineJob } from "@relkit/app/jobs";
import exportOrders from "../tasks/export-orders.task.js";

const exportOrdersJob = defineJob({
  name: "exportOrders",
  id: "orders.export-orders",
  task: exportOrders,
  client: {
    public: true,
    operations: ["trigger", "get", "list", "watch"],
    fields: ["status", "progress", "output"],
  },
});

export default exportOrdersJob;
```

**Frontend**

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider. It selects this job's public `exportOrders` name:

```tsx title="src/ExportOrders.tsx"
"use client";

/** Submits one commerce export and observes the accepted run without replaying an uncertain submission. */
import { useJobRun, useJobTrigger, useRelkitClient } from "@relkit/client/react";

/** Keeps the accepted receipt separate from the task's eventual output.
 * @returns One explicit submission button and its receipt, observation, or failure state. */
export function ExportOrders() {
  const { status } = useRelkitClient();
  const submit = useJobTrigger("exportOrders");
  const run = useJobRun("exportOrders", submit.data ? { runId: submit.data.runId } : {});

  return (
    <section>
      <button
        disabled={status !== "ready" || !submit.isIdle}
        onClick={() => submit.mutate({ input: { orderIds: ["order-1"] } })}
      >
        Export orders
      </button>
      {submit.isPending && <p role="status">Submitting…</p>}
      {submit.isError && (
        <p role="alert">{String(submit.error)}. Check the outcome before submitting again.</p>
      )}
      {submit.data && <p>Run ID: {submit.data.runId}</p>}
      <p role="status">
        Connection: {run.connection}; run: {run.run?.status ?? "not accepted"}
      </p>
    </section>
  );
}
```

The task determines the `orderIds` input. The job's `client.operations` permits triggering and
observation, while `client.fields` selects public run data. The returned `runId` is an admission
receipt; completion and output arrive through the run observer. The example keeps uncertain
submissions visible instead of automatically sending them again.

Reference: [`useJobTrigger`](/docs/api/client#usejobtrigger), [`useJobRun`](/docs/api/client#usejobrun).
Continue with [job clients and recovery](/docs/modules/jobs/clients).

### JOB_PROFILE_DEPRECATED_CODE

**Signature**

```ts
declare const JOB_PROFILE_DEPRECATED_CODE: "RELKIT_JOB_PROFILE_DEPRECATED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L6)

### JobDefinitionFailure (class)

Expected job definition failure, retaining the original validation error.

**Example**

```ts
if (error instanceof JobDefinitionFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobDefinitionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L11)

### RetryJitter

**Signature**

```ts
declare const RetryJitter: RetryJitter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L7)

### RetryPolicy

**Signature**

```ts
declare const RetryPolicy: RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L7)

### assertJobDescriptor

Synchronous job descriptor assertion.

**Throws**

TypeError for an invalid descriptor.

**Example**

```ts
assertJobDescriptor(job);
```

**Signature**

```ts
declare const assertJobDescriptor: (value: unknown) => asserts value is JobDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L97)

### assertJobDescriptorEffect

Asserts a valid job descriptor in Effect.

**Example**

```ts
Effect.runSync(assertJobDescriptorEffect(job));
```

**Signature**

```ts
declare const assertJobDescriptorEffect: (
  value: unknown,
) => Effect.Effect<undefined, JobDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L82)

### defineJobEffect

Defines an immutable job descriptor in Effect.

**Example**

```ts
Effect.runSync(defineJobEffect({ name: "sendReceipt", task }));
```

**Signature**

```ts
declare const defineJobEffect: <
  const Name extends string,
  const Task extends TaskDescriptorAny,
  const Id extends string = Name,
>(
  options: DefineJobOptions<Name, Task, Id>,
) => Effect.Effect<JobDescriptor<Name, Id, Task>, JobDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L20)

### isJobDescriptor

Synchronous job descriptor type guard.

**Example**

```ts
if (isJobDescriptor(value)) console.log(value.name);
```

**Signature**

```ts
declare const isJobDescriptor: (value: unknown) => value is JobDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L74)

### isJobDescriptorEffect

Tests a value for a valid job descriptor in Effect.

**Example**

```ts
Effect.runSync(isJobDescriptorEffect(value));
```

**Signature**

```ts
declare const isJobDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-job.ts#L63)

## `define-task-support.ts`

### TaskSupportError (class)

An invalid task authoring helper input.

**Example**

```ts
new TaskSupportError({ reason: "Task tags must be unique" });
```

**Signature**

```ts
declare class TaskSupportError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L8)

### assertHook

Synchronous optional hook assertion.

**Throws**

TypeError when the hook is not a function.

**Example**

```ts
assertHook(() => {}, "onStart");
```

**Signature**

```ts
declare const assertHook: (value: unknown, name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L85)

### assertHookEffect

Validates an optional lifecycle hook in Effect.

**Example**

```ts
Effect.runPromise(assertHookEffect(() => {}, "onStart"));
```

**Signature**

```ts
declare const assertHookEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<undefined, TaskSupportError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L68)

### copyStrings

Synchronous authoring string adapter.

**Throws**

TypeError for invalid or duplicate strings.

**Example**

```ts
copyStrings(["red"], "tags");
```

**Signature**

```ts
declare const copyStrings: (value: unknown, name: string) => readonly string[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L56)

### copyStringsEffect

Copies unique, bounded authoring strings in Effect.

**Example**

```ts
Effect.runPromise(copyStringsEffect(["red"], "tags"));
```

**Signature**

```ts
declare const copyStringsEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<ReadonlyArray<string> | undefined, TaskSupportError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L19)

### hasOwn

Synchronous own-property predicate.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
hasOwn({ id: 1 }, "id");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L137)

### hasOwnEffect

Checks property ownership in Effect.

**Example**

```ts
Effect.runSync(hasOwnEffect({ id: 1 }, "id"));
```

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L123)

### isRecord

Synchronous non-array record predicate.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isRecord({ id: 1 });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L159)

### isRecordEffect

Tests for a non-array record in Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({ id: 1 }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L146)

### isSchema

Synchronous Standard Schema v1 predicate.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isSchema({ "~standard": { version: 1, validate() {} } });
```

**Signature**

```ts
declare const isSchema: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L113)

### isSchemaEffect

Detects a Standard Schema v1 value in Effect.

**Example**

```ts
Effect.runSync(isSchemaEffect({ "~standard": { version: 1, validate() {} } }));
```

**Signature**

```ts
declare const isSchemaEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-support.ts#L95)

## `define-task-value.ts`

### defineTaskValue

Declares a typed task with an immutable execution contract and handler.

**Example**

```ts
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
const exportOrders = defineTask({
  id: "orders.export",
  version: "1",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ exported: z.number() }),
  handler: async ({ orderIds }) => ({ exported: orderIds.length }),
});
void exportOrders;
```

**Signature**

```ts
declare const defineTaskValue: <
  const Id extends string,
  const Version extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Dependencies extends TaskDependencies = {},
  const Errors extends readonly ErrorDescriptorAny[] = readonly [],
  const Publishes extends readonly PublishedEventName[] = readonly [],
  const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  const Streams extends TaskStreamSchemas = {},
  const Execution extends TaskExecution = "durable",
>(
  options: DefineTaskOptions<
    Id,
    Version,
    InputSchema,
    OutputSchema,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema,
    Streams,
    Execution
  >,
) => TaskDescriptor<
  Id,
  Version,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema,
  Streams,
  Execution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-value.ts#L52)

Since v0.4.1

### isTaskDescriptorValue

Checks a candidate for the branded task descriptor shape.

**Example**

```ts
isTaskDescriptorValue(candidate);
```

**Signature**

```ts
declare const isTaskDescriptorValue: (value: unknown) => value is TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task-value.ts#L177)

## `define-task.ts`

### defineTask

Declares a typed immutable task with an execution contract and handler.

**Throws**

Original validation error for invalid definitions.

**Example**

```ts
import { defineTask } from "@relkit/jobs";
import { z } from "@relkit/schema";
const echo = defineTask({
  id: "echo",
  version: "1",
  input: z.string(),
  output: z.string(),
  execution: "retryable",
  handler: async (input) => input,
});
```

**Signature**

```ts
declare const defineTask: <
  const Id extends string,
  const Version extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Dependencies extends TaskDependencies = {},
  const Errors extends readonly ErrorDescriptorAny[] = readonly [],
  const Publishes extends readonly PublishedEventName[] = readonly [],
  const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  const Streams extends TaskStreamSchemas = {},
  const Execution extends TaskExecution = "durable",
>(
  options: DefineTaskOptions<
    Id,
    Version,
    InputSchema,
    OutputSchema,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema,
    Streams,
    Execution
  >,
) => TaskDescriptor<
  Id,
  Version,
  InputSchema,
  OutputSchema,
  Dependencies,
  Errors,
  Publishes,
  ProgressSchema,
  Streams,
  Execution
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L77)

Since v0.4.1

### TaskDefinitionFailure (class)

Expected task definition failure, retaining the original validation error.

**Example**

```ts
if (error instanceof TaskDefinitionFailure) console.log(error.message);
```

**Signature**

```ts
declare class TaskDefinitionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L18)

### assertTaskDescriptor

Synchronous task descriptor assertion.

**Throws**

TypeError for invalid descriptors.

**Example**

```ts
assertTaskDescriptor(task);
```

**Signature**

```ts
declare const assertTaskDescriptor: (value: unknown) => asserts value is TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L158)

### assertTaskDescriptorEffect

Asserts a task descriptor in Effect.

**Example**

```ts
Effect.runSync(assertTaskDescriptorEffect(task));
```

**Signature**

```ts
declare const assertTaskDescriptorEffect: (
  value: unknown,
) => Effect.Effect<undefined, TaskDefinitionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L141)

### defineTaskEffect

Defines an immutable task descriptor in Effect.

**Example**

```ts
Effect.runSync(defineTaskEffect({ id: "send", version: "1", input, output, handler }));
```

**Signature**

```ts
declare const defineTaskEffect: <
  const Id extends string,
  const Version extends string,
  const InputSchema extends StandardSchemaV1,
  const OutputSchema extends StandardSchemaV1,
  const Dependencies extends TaskDependencies = {},
  const Errors extends readonly ErrorDescriptorAny[] = readonly [],
  const Publishes extends readonly PublishedEventName[] = readonly [],
  const ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  const Streams extends Readonly<Record<string, StandardSchemaV1<unknown, unknown>>> = {},
  const Execution extends TaskExecution = "durable",
>(
  options: DefineTaskOptions<
    Id,
    Version,
    InputSchema,
    OutputSchema,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema,
    Streams,
    Execution
  >,
) => Effect.Effect<
  TaskDescriptor<
    Id,
    Version,
    InputSchema,
    OutputSchema,
    Dependencies,
    Errors,
    Publishes,
    ProgressSchema,
    Streams,
    Execution
  >,
  TaskDefinitionFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L27)

### isTaskDescriptor

Synchronous task descriptor type guard.

**Example**

```ts
if (isTaskDescriptor(value)) console.log(value.id);
```

**Signature**

```ts
declare const isTaskDescriptor: (value: unknown) => value is TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L133)

### isTaskDescriptorEffect

Checks a task descriptor candidate in Effect.

**Example**

```ts
Effect.runSync(isTaskDescriptorEffect(value));
```

**Signature**

```ts
declare const isTaskDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/define-task.ts#L122)

## `duration.ts`

### DurationInput

**Signature**

```ts
declare const DurationInput:
  | `${number} second`
  | `${number} seconds`
  | `${number} minute`
  | `${number} minutes`
  | `${number} hour`
  | `${number} hours`
  | `${number} day`
  | `${number} days`
  | `${number} week`
  | `${number} weeks`
  | `${number} millisecond`
  | `${number} milliseconds`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L5)

### DurationUnit

**Signature**

```ts
declare const DurationUnit: DurationUnit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L5)

### DurationValidationError (class)

A malformed, inexact, or unsafe authored duration.

**Example**

```ts
new DurationValidationError({ input: "1.1 milliseconds", reason: "Invalid duration" });
```

**Signature**

```ts
declare class DurationValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L10)

### durationToMillis

Compatibility adapter for authored duration parsing.

**Throws**

TypeError when the duration is invalid or cannot be represented safely.

**Example**

```ts
durationToMillis("1.5 seconds");
```

**Signature**

```ts
declare const durationToMillis: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L107)

### durationToMillisEffect

Converts an authored duration to exact, safe milliseconds.

**Example**

```ts
Effect.runPromise(durationToMillisEffect("1.5 seconds"));
```

**Signature**

```ts
declare const durationToMillisEffect: (
  value:
    | `${number} second`
    | `${number} seconds`
    | `${number} minute`
    | `${number} minutes`
    | `${number} hour`
    | `${number} hours`
    | `${number} day`
    | `${number} days`
    | `${number} week`
    | `${number} weeks`
    | `${number} millisecond`
    | `${number} milliseconds`,
) => Effect.Effect<number, DurationValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L60)

### isDurationInput

Tests authored duration syntax.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isDurationInput("1 second");
```

**Signature**

```ts
declare const isDurationInput: (value: unknown) => value is DurationInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L51)

### isDurationInputEffect

Tests authored duration syntax in the Effect path.

**Example**

```ts
Effect.runSync(isDurationInputEffect("1 second"));
```

**Signature**

```ts
declare const isDurationInputEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L38)

### parseDuration

Alias for durationToMillis.

**Throws**

TypeError when the duration is invalid or unsafe.

**Example**

```ts
parseDuration("1 second");
```

**Signature**

```ts
declare const parseDuration: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L119)

### validateDuration

Alias for durationToMillis.

**Throws**

TypeError when the duration is invalid or unsafe.

**Example**

```ts
validateDuration("1 second");
```

**Signature**

```ts
declare const validateDuration: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.ts#L127)

## `duration.types.ts`

Units accepted by the authored duration syntax.

### DurationInput (type alias)

An authored decimal amount followed by one duration unit.

**Signature**

```ts
type DurationInput = `${number} ${DurationUnit}`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.types.ts#L17)

### DurationUnit (type alias)

Units accepted by the authored duration syntax.

**Signature**

```ts
type DurationUnit =
  | "millisecond"
  | "milliseconds"
  | "second"
  | "seconds"
  | "minute"
  | "minutes"
  | "hour"
  | "hours"
  | "day"
  | "days"
  | "week"
  | "weeks";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/duration.types.ts#L2)

## `identity.ts`

### JobIdentityError (class)

An identity tuple containing a value that cannot be encoded as JSON.

**Example**

```ts
new JobIdentityError({ operation: "stableTuple", cause: new Error("invalid") });
```

**Signature**

```ts
declare class JobIdentityError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L9)

### retryOperationIdentity

Synchronous retry-operation identity adapter.

**Throws**

A JSON validation error for unsupported values.

**Example**

```ts
retryOperationIdentity("r", "op");
```

**Signature**

```ts
declare const retryOperationIdentity: (runId: string, operationId: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L87)

### retryOperationIdentityEffect

Builds a retry-operation identity in Effect.

**Example**

```ts
Effect.runPromise(retryOperationIdentityEffect("r", "op"));
```

**Signature**

```ts
declare const retryOperationIdentityEffect: (
  runId: string,
  operationId: string,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L73)

### scheduleOccurrenceIdentity

Synchronous schedule-occurrence identity adapter.

**Throws**

A JSON validation error for unsupported values.

**Example**

```ts
scheduleOccurrenceIdentity("s", "2026-01-01T00:00:00Z");
```

**Signature**

```ts
declare const scheduleOccurrenceIdentity: (scheduleId: string, scheduledFor: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L111)

### scheduleOccurrenceIdentityEffect

Builds a schedule-occurrence identity in Effect.

**Example**

```ts
Effect.runPromise(scheduleOccurrenceIdentityEffect("s", "2026-01-01T00:00:00Z"));
```

**Signature**

```ts
declare const scheduleOccurrenceIdentityEffect: (
  scheduleId: string,
  scheduledFor: string,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L97)

### stableIdentityTuple

Synchronous compatibility adapter for identity tuples.

**Throws**

The original JSON validation error for unsupported values.

**Example**

```ts
stableIdentityTuple([1, "1"]);
```

**Signature**

```ts
declare const stableIdentityTuple: (values: readonly unknown[]) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L35)

### stableIdentityTupleEffect

Encodes typed tuple members in Effect so numeric and string values differ.

**Example**

```ts
Effect.runPromise(stableIdentityTupleEffect([1, "1"]));
```

**Signature**

```ts
declare const stableIdentityTupleEffect: (
  values: ReadonlyArray<unknown>,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L19)

### taskOperationIdentity

Synchronous task-operation identity adapter.

**Throws**

A JSON validation error for unsupported values.

**Example**

```ts
taskOperationIdentity("a", "send");
```

**Signature**

```ts
declare const taskOperationIdentity: (acceptanceIdentity: string, operation: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L63)

### taskOperationIdentityEffect

Builds a task-operation identity in Effect.

**Example**

```ts
Effect.runPromise(taskOperationIdentityEffect("a", "send"));
```

**Signature**

```ts
declare const taskOperationIdentityEffect: (
  acceptanceIdentity: string,
  operation: string,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.ts#L45)

## `identity.types.ts`

### IdentityValue (type alias)

JSON-safe representation of one identity tuple component.

**Signature**

```ts
type IdentityValue = JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/identity.types.ts#L4)

## `index.ts`

### "./adapter.js" (namespace export)

Re-exports all named exports from the "./adapter.js" module.

**Signature**

```ts
export * from "./adapter.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L9)

### "./authorization.js" (namespace export)

Re-exports all named exports from the "./authorization.js" module.

**Signature**

```ts
export * from "./authorization.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L15)

### "./capabilities.js" (namespace export)

Re-exports all named exports from the "./capabilities.js" module.

**Signature**

```ts
export * from "./capabilities.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L10)

### "./control-errors.js" (namespace export)

Re-exports all named exports from the "./control-errors.js" module.

**Signature**

```ts
export * from "./control-errors.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L16)

### "./controls.js" (namespace export)

Re-exports all named exports from the "./controls.js" module.

**Signature**

```ts
export * from "./controls.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L17)

### "./define-job.js" (namespace export)

Re-exports all named exports from the "./define-job.js" module.

**Signature**

```ts
export * from "./define-job.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L2)

### "./define-task.js" (namespace export)

Re-exports all named exports from the "./define-task.js" module.

**Signature**

```ts
export * from "./define-task.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L1)

### "./identity.js" (namespace export)

Re-exports all named exports from the "./identity.js" module.

**Signature**

```ts
export * from "./identity.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L8)

### "./migration.js" (namespace export)

Re-exports all named exports from the "./migration.js" module.

**Signature**

```ts
export * from "./migration.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L21)

### "./resolve-binding.js" (namespace export)

Re-exports all named exports from the "./resolve-binding.js" module.

**Signature**

```ts
export * from "./resolve-binding.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L3)

### "./run-id-router.js" (namespace export)

Re-exports all named exports from the "./run-id-router.js" module.

**Signature**

```ts
export * from "./run-id-router.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L14)

### "./run-id.js" (namespace export)

Re-exports all named exports from the "./run-id.js" module.

**Signature**

```ts
export * from "./run-id.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L13)

### "./runtime.js" (namespace export)

Re-exports all named exports from the "./runtime.js" module.

**Signature**

```ts
export * from "./runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L11)

### "./schedule-controls.js" (namespace export)

Re-exports all named exports from the "./schedule-controls.js" module.

**Signature**

```ts
export * from "./schedule-controls.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L18)

### "./schedule-reconciliation.js" (namespace export)

Re-exports all named exports from the "./schedule-reconciliation.js" module.

**Signature**

```ts
export * from "./schedule-reconciliation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L19)

### "./service-options.js" (namespace export)

Re-exports all named exports from the "./service-options.js" module.

**Signature**

```ts
export * from "./service-options.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L20)

### "./submission.js" (namespace export)

Re-exports all named exports from the "./submission.js" module.

**Signature**

```ts
export * from "./submission.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L12)

### "./task-policy-validation.js" (namespace export)

Re-exports all named exports from the "./task-policy-validation.js" module.

**Signature**

```ts
export * from "./task-policy-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L5)

### "./task-progress.js" (namespace export)

Re-exports all named exports from the "./task-progress.js" module.

**Signature**

```ts
export * from "./task-progress.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L7)

### "./task-types.js" (namespace export)

Re-exports all named exports from the "./task-types.js" module.

**Signature**

```ts
export * from "./task-types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L4)

### "./task-wire.js" (namespace export)

Re-exports all named exports from the "./task-wire.js" module.

**Signature**

```ts
export * from "./task-wire.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L6)

### DefineJobOptions

**Signature**

```ts
declare const DefineJobOptions: DefineJobOptions<Name, Task, Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L64)

### DurationInput

**Signature**

```ts
declare const DurationInput:
  | `${number} second`
  | `${number} seconds`
  | `${number} minute`
  | `${number} minutes`
  | `${number} hour`
  | `${number} hours`
  | `${number} day`
  | `${number} days`
  | `${number} week`
  | `${number} weeks`
  | `${number} millisecond`
  | `${number} milliseconds`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L94)

### DurationUnit

**Signature**

```ts
declare const DurationUnit: DurationUnit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L94)

### DurationValidationError

**Signature**

```ts
declare const DurationValidationError: typeof DurationValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L85)

### InstantValidationError

**Signature**

```ts
declare const InstantValidationError: typeof InstantValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L25)

### JOB_NAME_MAX_LENGTH

**Signature**

```ts
declare const JOB_NAME_MAX_LENGTH: 64;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L109)

### JOB_NAME_PATTERN

**Signature**

```ts
declare const JOB_NAME_PATTERN: RegExp;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L105)

### JOB_NAME_RESERVED

**Signature**

```ts
declare const JOB_NAME_RESERVED: readonly [
  "then",
  "constructor",
  "prototype",
  "toJSON",
  "toString",
  "valueOf",
  "hasOwnProperty",
  "isPrototypeOf",
  "propertyIsEnumerable",
  "toLocaleString",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L106)

### JobAccessGrant

**Signature**

```ts
declare const JobAccessGrant: JobAccessGrant;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L39)

### JobAccessRequest

**Signature**

```ts
declare const JobAccessRequest: JobAccessRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L40)

### JobAdmission

**Signature**

```ts
declare const JobAdmission: JobAdmission<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L65)

### JobAuthorizationContext

**Signature**

```ts
declare const JobAuthorizationContext: JobAuthorizationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L66)

### JobClientAccess

**Signature**

```ts
declare const JobClientAccess: JobClientAccess<Streams>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L67)

### JobClientField

**Signature**

```ts
declare const JobClientField: JobClientField;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L68)

### JobClientOperation

**Signature**

```ts
declare const JobClientOperation: JobClientOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L41)

### JobDescriptor

**Signature**

```ts
declare const JobDescriptor: JobDescriptor<Name, Id, Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L69)

### JobDescriptorAny

**Signature**

```ts
declare const JobDescriptorAny: JobDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L70)

### JobErrorEnvelope

**Signature**

```ts
declare const JobErrorEnvelope: JobErrorEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L42)

### JobName

**Signature**

```ts
declare const JobName: JobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L108)

### JobNameValidationError

**Signature**

```ts
declare const JobNameValidationError: typeof JobNameValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L102)

### JobRunResultOptions

**Signature**

```ts
declare const JobRunResultOptions: RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L72)

### JobRunStatus

**Signature**

```ts
declare const JobRunStatus: JobRunStatus;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L43)

### JobScheduleClient

**Signature**

```ts
declare const JobScheduleClient: JobScheduleClient<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L71)

### JobServiceSelection

**Signature**

```ts
declare const JobServiceSelection: JobServiceSelection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L73)

### JobUnknownOutcome

**Signature**

```ts
declare const JobUnknownOutcome: JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L44)

### JobWireEnvelope

**Signature**

```ts
declare const JobWireEnvelope: JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L46)

### JobsTelemetry

**Signature**

```ts
declare const JobsTelemetry: typeof JobsTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L93)

### JobsTelemetryLive

**Signature**

```ts
declare const JobsTelemetryLive: Layer<JobsTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L93)

### JsonWireEnvelope

**Signature**

```ts
declare const JsonWireEnvelope: JsonWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L45)

### NamedStreamFrame

**Signature**

```ts
declare const NamedStreamFrame: NamedStreamFrame<Item>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L47)

### ProgressEmitReceipt

**Signature**

```ts
declare const ProgressEmitReceipt: ProgressEmitReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L48)

### ResultAvailability

**Signature**

```ts
declare const ResultAvailability: ResultAvailability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L49)

### RunAvailability

**Signature**

```ts
declare const RunAvailability: RunAvailability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L50)

### RunCancellationReceipt

**Signature**

```ts
declare const RunCancellationReceipt: RunCancellationReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L51)

### RunConnection

**Signature**

```ts
declare const RunConnection: RunConnection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L52)

### RunHandle

**Signature**

```ts
declare const RunHandle: RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L53)

### RunListQuery

**Signature**

```ts
declare const RunListQuery: RunListQuery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L54)

### RunPage

**Signature**

```ts
declare const RunPage: RunPage<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L55)

### RunRetryReceipt

**Signature**

```ts
declare const RunRetryReceipt: RunRetryReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L56)

### RunSnapshot

**Signature**

```ts
declare const RunSnapshot: RunSnapshot<Input, Output, Progress, Failure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L57)

### RunWatchFrame

**Signature**

```ts
declare const RunWatchFrame: RunWatchFrame<Run>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L58)

### ScheduleDefinition

**Signature**

```ts
declare const ScheduleDefinition: ScheduleDefinition<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L74)

### ScheduleListOptions

**Signature**

```ts
declare const ScheduleListOptions: ScheduleListOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L79)

### ScheduleMisfire

**Signature**

```ts
declare const ScheduleMisfire: ScheduleMisfire;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L75)

### ScheduleOverlap

**Signature**

```ts
declare const ScheduleOverlap: ScheduleOverlap;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L76)

### ScheduleReadReceipt

**Signature**

```ts
declare const ScheduleReadReceipt: ScheduleReadReceipt<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L77)

### ScheduleRecord

**Signature**

```ts
declare const ScheduleRecord: ScheduleRecord<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L78)

### ScheduleWriteOptions

**Signature**

```ts
declare const ScheduleWriteOptions: ScheduleWriteOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L80)

### ScheduleWriteOutcome

**Signature**

```ts
declare const ScheduleWriteOutcome: ScheduleWriteOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L81)

### ScheduleWriteReceipt

**Signature**

```ts
declare const ScheduleWriteReceipt: ScheduleWriteReceipt<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L82)

### StreamIdentity

**Signature**

```ts
declare const StreamIdentity: StreamIdentity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L59)

### StreamItem

**Signature**

```ts
declare const StreamItem: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L60)

### TASK_INPUT_MAX_BYTES

**Signature**

```ts
declare const TASK_INPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L31)

### TASK_ITEM_MAX_BYTES

**Signature**

```ts
declare const TASK_ITEM_MAX_BYTES: number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L33)

### TASK_KEY_MAX_BYTES

**Signature**

```ts
declare const TASK_KEY_MAX_BYTES: 256;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L34)

### TASK_MAX_TAGS

**Signature**

```ts
declare const TASK_MAX_TAGS: 20;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L36)

### TASK_OUTPUT_MAX_BYTES

**Signature**

```ts
declare const TASK_OUTPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L32)

### TASK_REASON_MAX_BYTES

**Signature**

```ts
declare const TASK_REASON_MAX_BYTES: 1024;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L35)

### ValidJobName

**Signature**

```ts
declare const ValidJobName: ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L108)

### VoidWireEnvelope

**Signature**

```ts
declare const VoidWireEnvelope: VoidWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L61)

### assertJobName

**Signature**

```ts
declare const assertJobName: (value: unknown, source?: string) => asserts value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L96)

### assertJobNameEffect

**Signature**

```ts
declare const assertJobNameEffect: (
  value: unknown,
  source?: any,
) => Effect<undefined, JobNameValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L97)

### assertRfc3339Instant

**Signature**

```ts
declare const assertRfc3339Instant: (value: unknown, name?: string) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L23)

### assertRfc3339InstantEffect

**Signature**

```ts
declare const assertRfc3339InstantEffect: (
  value: unknown,
  name?: any,
) => Effect<undefined, InstantValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L24)

### copyTriggerOptions

**Signature**

```ts
declare const copyTriggerOptions: (value: unknown) => CopiedTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L29)

### durationToMillis

**Signature**

```ts
declare const durationToMillis: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L86)

### durationToMillisEffect

**Signature**

```ts
declare const durationToMillisEffect: (
  value:
    | `${number} second`
    | `${number} seconds`
    | `${number} minute`
    | `${number} minutes`
    | `${number} hour`
    | `${number} hours`
    | `${number} day`
    | `${number} days`
    | `${number} week`
    | `${number} weeks`
    | `${number} millisecond`
    | `${number} milliseconds`,
) => Effect<number, DurationValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L87)

### isDurationInput

**Signature**

```ts
declare const isDurationInput: (value: unknown) => value is DurationInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L88)

### isDurationInputEffect

**Signature**

```ts
declare const isDurationInputEffect: (value: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L89)

### isJobName

**Signature**

```ts
declare const isJobName: (value: unknown) => value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L98)

### isJobNameEffect

**Signature**

```ts
declare const isJobNameEffect: (value: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L99)

### isRfc3339Instant

**Signature**

```ts
declare const isRfc3339Instant: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L26)

### isRfc3339InstantEffect

**Signature**

```ts
declare const isRfc3339InstantEffect: (value: unknown) => Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L27)

### isValidJobName

**Signature**

```ts
declare const isValidJobName: (value: unknown) => value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L100)

### normalizeJobName

**Signature**

```ts
declare const normalizeJobName: <const Name extends string>(value: Name) => ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L101)

### parseDuration

**Signature**

```ts
declare const parseDuration: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L90)

### validateDuration

**Signature**

```ts
declare const validateDuration: (value: DurationInput) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L91)

### validateJobName

**Signature**

```ts
declare const validateJobName: <const Name extends string>(value: Name) => ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L103)

### validateJobNameEffect

**Signature**

```ts
declare const validateJobNameEffect: <const Name extends string>(
  value: Name,
) => Effect<ValidJobName<Name>, JobNameValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L104)

### validateResultOptions

**Signature**

```ts
declare const validateResultOptions: (value: unknown) => RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/index.ts#L29)

## `instant-validation.ts`

### InstantValidationError (class)

An invalid authored RFC 3339 instant.

**Example**

```ts
new InstantValidationError({ name: "instant", reason: "invalid" });
```

**Signature**

```ts
declare class InstantValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/instant-validation.ts#L11)

### assertRfc3339Instant

Synchronous RFC 3339 assertion.

**Throws**

TypeError when the instant is invalid.

**Example**

```ts
assertRfc3339Instant("2026-01-01T00:00:00Z");
```

**Signature**

```ts
declare const assertRfc3339Instant: (value: unknown, name?: string) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/instant-validation.ts#L96)

### assertRfc3339InstantEffect

Requires an RFC 3339 instant in Effect.

**Example**

```ts
Effect.runPromise(assertRfc3339InstantEffect("2026-01-01T00:00:00Z"));
```

**Signature**

```ts
declare const assertRfc3339InstantEffect: (
  value: unknown,
  name?: any,
) => Effect.Effect<undefined, InstantValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/instant-validation.ts#L76)

### isRfc3339Instant

Synchronous RFC 3339 predicate.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isRfc3339Instant("2026-01-01T00:00:00Z");
```

**Signature**

```ts
declare const isRfc3339Instant: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/instant-validation.ts#L66)

### isRfc3339InstantEffect

Checks RFC 3339 syntax and calendar bounds in Effect.

**Example**

```ts
Effect.runSync(isRfc3339InstantEffect("2026-01-01T00:00:00Z"));
```

**Signature**

```ts
declare const isRfc3339InstantEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/instant-validation.ts#L21)

## `job-name.ts`

### JOB_NAME_PATTERN

ASCII job names start with a lowercase letter and continue with letters or digits.

**Example**

```ts
JOB_NAME_PATTERN.test("sendEmail");
```

**Signature**

```ts
declare const JOB_NAME_PATTERN: RegExp;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L11)

### JOB_NAME_RESERVED

JavaScript promise and object keys that cannot name callable jobs.

**Example**

```ts
JOB_NAME_RESERVED.includes("then");
```

**Signature**

```ts
declare const JOB_NAME_RESERVED: readonly [
  "then",
  "constructor",
  "prototype",
  "toJSON",
  "toString",
  "valueOf",
  "hasOwnProperty",
  "isPrototypeOf",
  "propertyIsEnumerable",
  "toLocaleString",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L15)

### JobName

**Signature**

```ts
declare const JobName: JobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L6)

### JobNameValidationError (class)

A rejected authored job name with a stable validation tag.

**Example**

```ts
new JobNameValidationError({ source: "job name", reason: "Invalid name" });
```

**Signature**

```ts
declare class JobNameValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L32)

### ValidJobName

**Signature**

```ts
declare const ValidJobName: ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L6)

### assertJobName

Asserts the job-name grammar for synchronous callers.

**Throws**

TypeError when the candidate is not a valid job name.

**Example**

```ts
assertJobName("sendEmail");
```

**Signature**

```ts
declare const assertJobName: (value: unknown, source?: string) => asserts value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L99)

### assertJobNameEffect

Validates a job name in the Effect error channel.

**Example**

```ts
Effect.runPromise(assertJobNameEffect("sendEmail"));
```

**Signature**

```ts
declare const assertJobNameEffect: (
  value: unknown,
  source?: any,
) => Effect.Effect<undefined, JobNameValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L79)

### isJobName

Tests a candidate against the job-name grammar.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isJobName("sendEmail");
```

**Signature**

```ts
declare const isJobName: (value: unknown) => value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L61)

### isJobNameEffect

Tests a candidate against the job-name grammar in Effect.

**Example**

```ts
Effect.runSync(isJobNameEffect("sendEmail"));
```

**Signature**

```ts
declare const isJobNameEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L42)

### isValidJobName

Alias for isJobName.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
isValidJobName("sendEmail");
```

**Signature**

```ts
declare const isValidJobName: (value: unknown) => value is JobName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L71)

### normalizeJobName

Alias for validateJobName.

**Throws**

TypeError when the name is invalid.

**Example**

```ts
normalizeJobName("sendEmail");
```

**Signature**

```ts
declare const normalizeJobName: <const Name extends string>(value: Name) => ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L135)

### validateJobName

Validates a literal job name for synchronous authors.

**Throws**

TypeError when the name is invalid.

**Example**

```ts
validateJobName("sendEmail");
```

**Signature**

```ts
declare const validateJobName: <const Name extends string>(value: Name) => ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L123)

### validateJobNameEffect

Validates a literal name in Effect while retaining its literal type.

**Example**

```ts
Effect.runPromise(validateJobNameEffect("sendEmail"));
```

**Signature**

```ts
declare const validateJobNameEffect: <const Name extends string>(
  value: Name,
) => Effect.Effect<ValidJobName<Name>, JobNameValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.ts#L109)

## `job-name.types.ts`

### JobName (type alias)

A validated job name, preserving literal types when available.

**Signature**

```ts
type JobName<Name extends string = string> = string extends Name ? string : ValidJobName<Name>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.types.ts#L63)

### ValidJobName (type alias)

Compile-time predicate for a literal job name.

**Signature**

```ts
type ValidJobName<Name extends string = string> = string extends Name
  ? never
  : Name extends (typeof JOB_NAME_RESERVED)[number]
    ? never
    : Name extends `${LowercaseLetter}${infer Rest}`
      ? ValidCharacters<Rest> extends true
        ? AtMost64<Name> extends true
          ? Name
          : never
        : never
      : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-name.types.ts#L50)

## `job-validation-value.ts`

### copyAdmission

Validates and freezes job admission policy against the canonical input schema.

**Throws**

TypeError for unsupported or unsafe admission values.

**Example**

```ts
copyAdmission({ idempotency: { key: "orderId" } }, inputSchema);
```

**Signature**

```ts
declare const copyAdmission: <Input>(
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => JobAdmission<Input> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation-value.ts#L25)

### copyClient

Validates the client operations and projected fields exposed by a job.

**Throws**

TypeError for an undeclared operation or invalid field.

**Example**

```ts
copyClient({ public: true, operations: ["status"] }, declarations);
```

**Signature**

```ts
declare const copyClient: (
  value: unknown,
  declarations: ClientDeclarations,
) => JobClientAccess | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation-value.ts#L79)

## `job-validation.ts`

### ClientDeclarations

**Signature**

```ts
declare const ClientDeclarations: ClientDeclarations;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L10)

### JobValidationFailure (class)

Expected job policy validation failure with its original cause.

**Example**

```ts
if (error instanceof JobValidationFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobValidationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L14)

### copyAdmission

Synchronous job admission policy copier.

**Throws**

Original invalid policy error.

**Example**

```ts
copyAdmission({ pastAt: "run" });
```

**Signature**

```ts
declare const copyAdmission: <Input>(
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => JobAdmission<Input> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L41)

### copyAdmissionEffect

Copies job admission policy in Effect.

**Example**

```ts
Effect.runSync(copyAdmissionEffect({ pastAt: "run" }));
```

**Signature**

```ts
declare const copyAdmissionEffect: <Input>(
  value: unknown,
  canonicalSchema?: StandardSchemaV1<unknown, unknown> | undefined,
) => Effect.Effect<JobAdmission<Input> | undefined, JobValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L24)

### copyClient

Synchronous job client access policy copier.

**Throws**

Original invalid policy error.

**Example**

```ts
copyClient({ public: true, operations: ["trigger"] }, {});
```

**Signature**

```ts
declare const copyClient: (
  value: unknown,
  declarations: ClientDeclarations,
) => JobClientAccess | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L72)

### copyClientEffect

Copies job client access policy in Effect.

**Example**

```ts
Effect.runSync(copyClientEffect({ public: true, operations: ["trigger"] }, {}));
```

**Signature**

```ts
declare const copyClientEffect: (
  value: unknown,
  declarations: ClientDeclarations,
) => Effect.Effect<JobClientAccess | undefined, JobValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.ts#L55)

## `job-validation.types.ts`

Task schemas available when authoring job client access.

### ClientDeclarations (interface)

Task schemas available when authoring job client access.

**Signature**

```ts
export interface ClientDeclarations {
  readonly progress?: unknown;
  readonly streams?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job-validation.types.ts#L2)

## `job.types.ts`

### DefineJobOptions (type alias)

Options accepted for define job operations.

**Signature**

```ts
type DefineJobOptions<
  Name extends string,
  Task extends TaskDescriptorAny,
  Id extends string = Name,
> = DescriptorMetadata &
  JobServiceSelection & {
    readonly name: Name & ValidJobName<Name>;
    readonly id?: Id;
    readonly task: Task;
    readonly default?: boolean;
    readonly schedules?: readonly ScheduleDefinition<InferInput<Task["input"]>>[];
    readonly admission?: JobAdmission<InferOutput<Task["input"]>>;
    readonly client?: JobClientAccess<StreamsOf<Task>>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L110)

### JobAdmission (interface)

Policy for late schedules and idempotent submissions.

**Signature**

```ts
export interface JobAdmission<Input = unknown> {
  readonly pastAt?: "run" | "reject";
  readonly idempotency?: {
    readonly key?: Extract<keyof Input, string>;
    readonly retention?: DurationInput;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L60)

### JobAuthorizationContext (interface)

Trusted scope and optional subject data passed to an access policy.

**Signature**

```ts
export interface JobAuthorizationContext {
  readonly application: string;
  readonly environment: string;
  readonly scope: string;
  readonly subject?: string;
  readonly auth?: unknown;
  readonly run?: import("@relkit/contracts/jobs").RunSnapshot;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L71)

### JobClientAccess (type alias)

Public or policy-guarded operations and fields exposed to clients.

**Signature**

```ts
type JobClientAccess<Streams extends TaskStreamSchemas = TaskStreamSchemas> =
  | {
      readonly public: true;
      readonly operations: readonly JobClientOperation[];
      readonly fields?: readonly JobClientField[];
      readonly streams?: readonly (keyof Streams & string)[];
    }
  | {
      readonly authorize: (
        request: JobAccessRequest,
        context: JobAuthorizationContext,
      ) => MaybePromise<JobAccessGrant>;
      readonly public?: never;
      readonly operations: readonly JobClientOperation[];
      readonly fields?: readonly JobClientField[];
      readonly streams?: readonly (keyof Streams & string)[];
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L80)

### JobClientField (type alias)

Run fields that authorization may expose to a client.

**Signature**

```ts
type JobClientField = "status" | "input" | "progress" | "output" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L69)

### JobDescriptor (type alias)

Validated job definition and its task-specific trigger operation.

**Signature**

```ts
type JobDescriptor<
  Name extends string,
  Id extends string,
  Task extends TaskDescriptorAny,
> = DescriptorBase<"job", Id> &
  JobRef<Id, Task["input"], Task["output"], Task> & {
    readonly name: Name;
    readonly task: Task;
    readonly input: Task["input"];
    readonly output: Task["output"];
    readonly errors?: Task["errors"];
    readonly progress?: Task["progress"];
    readonly streams?: Task["streams"];
    readonly execution: Task["execution"];
    readonly observation?: TaskObservation<
      Task["streams"] extends TaskStreamSchemas ? Task["streams"] : {}
    >;
    readonly service?: string;
    readonly default?: boolean;
    readonly schedules?: readonly ScheduleDefinition<InferOutput<Task["input"]>>[];
    readonly admission?: JobAdmission<InferOutput<Task["input"]>>;
    readonly client?: JobClientAccess<StreamsOf<Task>>;
    readonly trigger: (
      input: InferInput<Task["input"]>,
      options?: ServerTriggerOptions,
    ) => Promise<RunHandle>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L126)

### JobDescriptorAny (type alias)

Erases task-specific admission keys at runtime boundaries without making concrete jobs invariant.

**Signature**

```ts
type JobDescriptorAny = Omit<
  JobDescriptor<string, string, TaskDescriptorAny>,
  "admission" | "trigger"
> & {
  readonly admission?: JobAdmission<any>;
  readonly trigger: (input: any, options?: ServerTriggerOptions) => Promise<RunHandle>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L158)

### JobRunResultOptions (type alias)

Options accepted for job run result operations.

**Signature**

```ts
type JobRunResultOptions = RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L155)

### JobScheduleClient

**Signature**

```ts
declare const JobScheduleClient: JobScheduleClient<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L34)

### JobServiceSelection (type alias)

Mutually exclusive service and deprecated profile selectors.

**Signature**

```ts
type JobServiceSelection =
  | { readonly service?: string; readonly profile?: never }
  | { readonly service?: never; readonly profile?: string };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L99)

### RetryJitter (type alias)

Jitter strategy for the compatibility retry policy.

**Signature**

```ts
type RetryJitter = "none" | "full" | "equal";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L49)

### RetryPolicy (interface)

Compatibility retry attempts, delays, multiplier, and jitter.

**Signature**

```ts
export interface RetryPolicy {
  readonly maxAttempts: number;
  readonly initialDelayMs: number;
  readonly maxDelayMs: number;
  readonly multiplier: number;
  readonly jitter: RetryJitter;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L51)

### RunResultOptions

**Signature**

```ts
declare const RunResultOptions: RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L46)

### ScheduleDefinition

**Signature**

```ts
declare const ScheduleDefinition: ScheduleDefinition<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L35)

### ScheduleListOptions

**Signature**

```ts
declare const ScheduleListOptions: ScheduleListOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L36)

### ScheduleMisfire

**Signature**

```ts
declare const ScheduleMisfire: ScheduleMisfire;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L37)

### ScheduleOverlap

**Signature**

```ts
declare const ScheduleOverlap: ScheduleOverlap;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L38)

### ScheduleReadReceipt

**Signature**

```ts
declare const ScheduleReadReceipt: ScheduleReadReceipt<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L39)

### ScheduleRecord

**Signature**

```ts
declare const ScheduleRecord: ScheduleRecord<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L40)

### ScheduleWriteOptions

**Signature**

```ts
declare const ScheduleWriteOptions: ScheduleWriteOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L41)

### ScheduleWriteOutcome

**Signature**

```ts
declare const ScheduleWriteOutcome: ScheduleWriteOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L42)

### ScheduleWriteReceipt

**Signature**

```ts
declare const ScheduleWriteReceipt: ScheduleWriteReceipt<Definition>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L43)

### ServerTriggerOptions

**Signature**

```ts
declare const ServerTriggerOptions: ServerTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L46)

### TriggerOptions

**Signature**

```ts
declare const TriggerOptions: TriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/job.types.ts#L46)

## `jobs-observability.ts`

### JobsTelemetry (class)

Injectable observer for jobs Effect operations.

**Example**

```ts
Effect.provide(durationToMillisEffect("1 second"), JobsTelemetryLive);
```

**Signature**

```ts
declare class JobsTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/jobs-observability.ts#L7)

### JobsTelemetryLive

Live spans and bounded jobs operation metrics.

**Example**

```ts
Effect.provide(durationToMillisEffect("1 second"), JobsTelemetryLive);
```

**Signature**

```ts
declare const JobsTelemetryLive: Layer.Layer<JobsTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/jobs-observability.ts#L14)

### observeJobs

Observes an operation with a supplied service or the live observer.

**Example**

```ts
observeJobs("duration.toMillis", Effect.succeed(1000));
```

**Signature**

```ts
declare const observeJobs: <A, E, R>(
  operation: JobsOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/jobs-observability.ts#L28)

## `jobs-observability.types.ts`

### JobsOperation (type alias)

Stable, bounded operation labels recorded in spans and metrics.

**Example**

```ts
const operation: JobsOperation = "submission.write";
```

**Signature**

```ts
type JobsOperation =
  | "duration.isInput"
  | "duration.toMillis"
  | "jobName.is"
  | "jobName.assert"
  | "jobName.validate"
  | "identity.stableTuple"
  | "identity.taskOperation"
  | "identity.retryOperation"
  | "identity.scheduleOccurrence"
  | "instant.is"
  | "instant.assert"
  | "retry.validate"
  | "control.write"
  | "canonical.assertProjection"
  | "taskSupport.copyStrings"
  | "taskSupport.assertHook"
  | "taskSupport.isSchema"
  | "taskSupport.hasOwn"
  | "taskSupport.isRecord"
  | "taskObservation.copy"
  | "migration.diagnose"
  | "migration.legacy"
  | "authorization.authorize"
  | "authorization.grant"
  | "authorization.operation"
  | "server.readManifest"
  | "server.run"
  | "server.runtimeOptions"
  | "capability.assert"
  | "capability.validateReport"
  | "adapter.assertMethods"
  | "authorization.projectSnapshot"
  | "authorization.projectPage"
  | "adapter.assertRuntime"
  | "adapter.isRuntime"
  | "runtime.create"
  | "runtime.current"
  | "runtime.require"
  | "runtime.validateManifest"
  | "runtime.runIn"
  | "serviceOptions.validate"
  | "serviceOptions.serialize"
  | "serviceOptions.deserialize"
  | "serviceOptions.assertSupported"
  | "submission.write"
  | "submission.prepare"
  | "submission.prepareCanonical"
  | "submission.createPipeline"
  | "submission.submitTask"
  | "submission.submitJob"
  | "submission.submitCanonical"
  | "schedule.createControls"
  | "schedule.list"
  | "schedule.get"
  | "schedule.write"
  | "control.create"
  | "control.get"
  | "control.list"
  | "control.observe"
  | "control.cancel"
  | "control.retry"
  | "control.result"
  | "legacy.defineJob"
  | "authorization.createCursor"
  | "authorization.readCursor"
  | "runLocator.create"
  | "runLocator.namespaceHash"
  | "runLocator.validateKeyRing"
  | "runLocator.verify"
  | "runLocator.rotate"
  | "runLocator.routerLoad"
  | "runLocator.routerRegister"
  | "runLocator.routerSnapshot"
  | "runLocator.routerPersist"
  | "runLocator.routerRoute"
  | "trigger.copyOptions"
  | "trigger.resultOptions"
  | "schedule.copyDefinitions"
  | "binding.resolve"
  | "runtime.resolveBinding"
  | "client.runAbortable"
  | "client.create"
  | "client.enqueue"
  | "task.createProgressEmitter"
  | "task.createStreamEmitter"
  | "task.emitProgress"
  | "task.emitStream"
  | "schedule.reconcile"
  | "schedule.owner"
  | "schedule.operationId"
  | "schedule.writeRecovery"
  | "control.pollResult"
  | "taskWire.encodeJob"
  | "taskWire.encodeInput"
  | "taskWire.encodeOutput"
  | "taskWire.decodeJob"
  | "taskWire.validateInput"
  | "taskWire.validateCanonicalInput"
  | "taskWire.validateOutput"
  | "taskWire.validateCanonicalOutput"
  | "job.define"
  | "job.isDescriptor"
  | "job.assertDescriptor"
  | "task.define"
  | "task.isDescriptor"
  | "task.assertDescriptor"
  | "client.resolveProvider"
  | "client.parseInput"
  | "client.assertOptions"
  | "client.assertOptionalText"
  | "client.normalizeResult"
  | "client.notify"
  | "client.resolveCorrelation"
  | "taskValidation.assertSchema"
  | "taskValidation.normalizeVersion"
  | "taskValidation.inputWire"
  | "taskValidation.canonicalSchema"
  | "taskValidation.canonicalStreams"
  | "taskValidation.retry"
  | "taskValidation.dependencies"
  | "taskValidation.errors"
  | "taskValidation.streams"
  | "taskValidation.duration"
  | "taskPolicy.utf8Bytes"
  | "taskPolicy.boundedString"
  | "taskPolicy.fieldName"
  | "taskPolicy.memoryBytes"
  | "taskPolicy.scalarKey"
  | "taskPolicy.tags"
  | "taskPolicy.resources"
  | "taskPolicy.concurrency"
  | "taskPolicy.logging"
  | "taskPolicy.retryDelay"
  | "jobValidation.admission"
  | "jobValidation.client"
  | "submission.admission"
  | "submission.submitPrepared"
  | "control.observeSetup"
  | "control.observeNext"
  | "controlSupport.context"
  | "controlSupport.requireMethod"
  | "controlSupport.operationId"
  | "controlSupport.cancelReceipt"
  | "controlSupport.retryReceipt"
  | "controlSupport.isUnknown"
  | "controlSupport.unknownKey"
  | "controlSupport.unknownRecovery"
  | "controlSupport.isTerminal"
  | "controlSupport.timeout"
  | "controlSupport.isRecord"
  | "submissionSupport.error"
  | "submissionSupport.receipt"
  | "submissionSupport.envelope"
  | "submissionSupport.isUnknown"
  | "submissionSupport.isRecord"
  | "submissionSupport.idempotency"
  | "submissionSupport.boundedKey"
  | "submissionSupport.scheduledTime"
  | "submissionSupport.correlation"
  | "submissionSupport.propagation"
  | "submissionSupport.parentRun"
  | "submissionSupport.hashWire"
  | "binding.selectProfile"
  | "binding.taskId";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/jobs-observability.types.ts#L6)

### JobsTelemetryService (interface)

Substitutable observer used by jobs Effect operations.

**Example**

```ts
const observer: JobsTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface JobsTelemetryService {
  /** Surrounds an operation while preserving its success and error channels.
   * @param operation - A stable operation name.
   * @param effect - The operation to observe.
   * @returns The observed Effect with unchanged success and error types.
   * @example observer.observe("duration.toMillis", Effect.succeed(1000));
   */
  readonly observe: <A, E, R>(
    operation: JobsOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/jobs-observability.types.ts#L176)

## `legacy-define-job.ts`

### DefineJobOptions

**Signature**

```ts
declare const DefineJobOptions: DefineJobOptions<Id, InputSchema, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L25)

### IdempotencyDefinition

**Signature**

```ts
declare const IdempotencyDefinition: IdempotencyDefinition<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L23)

### JobDescriptor

**Signature**

```ts
declare const JobDescriptor: JobDescriptor<Id, Input, InputSchema, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L24)

### LegacyJobValidationError (class)

Invalid legacy job authoring options.

**Example**

```ts
if (error instanceof LegacyJobValidationError) console.log(error.message);
```

**Signature**

```ts
declare class LegacyJobValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L32)

### RetryJitter

**Signature**

```ts
declare const RetryJitter: RetryJitter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L19)

### RetryPolicy

**Signature**

```ts
declare const RetryPolicy: RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L20)

### ScheduleDefinition

**Signature**

```ts
declare const ScheduleDefinition: ScheduleDefinition<Input>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L22)

### ScheduleOverlap

**Signature**

```ts
declare const ScheduleOverlap: ScheduleOverlap;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L21)

### defineJob

Synchronous compatibility adapter for legacy job authoring.

**Throws**

TypeError when the authored job is invalid.

**Example**

```ts
defineJob(options);
```

**Signature**

```ts
declare const defineJob: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const Target extends FunctionRefAny,
>(
  options: DefineJobOptions<Id, InputSchema, Target>,
) => JobDescriptor<Id, InferInput<InputSchema>, InputSchema, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L67)

### defineJobEffect

Defines a legacy function backed job in Effect.

**Example**

```ts
Effect.runSync(defineJobEffect(options));
```

**Signature**

```ts
declare const defineJobEffect: <
  const Id extends string,
  const InputSchema extends StandardSchemaV1,
  const Target extends FunctionRefAny,
>(
  options: DefineJobOptions<Id, InputSchema, Target>,
) => Effect.Effect<
  JobDescriptor<Id, InferInput<InputSchema>, InputSchema, Target>,
  LegacyJobValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.ts#L41)

## `legacy-define-job.types.ts`

### DefineJobOptions (interface)

Options accepted for define job operations.

**Signature**

```ts
export interface DefineJobOptions<
  Id extends string,
  InputSchema extends StandardSchemaV1,
  Target extends FunctionRefAny,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly input: InputSchema;
  readonly target: Target;
  readonly profile?: string;
  readonly retry: RetryPolicy;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly schedule?: readonly ScheduleDefinition<InferInput<InputSchema>>[];
  readonly idempotency?: IdempotencyDefinition<InferInput<InputSchema>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L49)

### IdempotencyDefinition (interface)

Legacy deduplication key and retention policy.

**Signature**

```ts
export interface IdempotencyDefinition<Input = unknown> {
  readonly key: IdempotencyKey<Input>;
  readonly retentionMs: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L28)

### JobDescriptor (interface)

Validated job definition and its task-specific trigger operation.

**Signature**

```ts
export interface JobDescriptor<
  Id extends string,
  Input,
  InputSchema extends StandardSchemaV1 = StandardSchemaV1,
  Target extends FunctionRefAny = FunctionRefAny,
> extends DescriptorBase<"job", Id> {
  readonly input: InputSchema;
  readonly target: Target;
  readonly profile?: string;
  readonly retry: RetryPolicy;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly schedule?: readonly ScheduleDefinition<Input>[];
  readonly idempotency?: IdempotencyDefinition<Input>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L33)

### RetryJitter (type alias)

Jitter strategy retained for legacy job retry policy.

**Signature**

```ts
type RetryJitter = "none" | "full" | "equal";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L5)

### RetryPolicy (interface)

Legacy retry attempts, backoff, and jitter settings.

**Signature**

```ts
export interface RetryPolicy {
  readonly maxAttempts: number;
  readonly initialDelayMs: number;
  readonly maxDelayMs: number;
  readonly multiplier: number;
  readonly jitter: RetryJitter;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L7)

### ScheduleDefinition (interface)

Legacy schedule timing and overlap configuration.

**Signature**

```ts
export interface ScheduleDefinition<Input = JsonValue> {
  readonly id: string;
  readonly cron: string;
  readonly timezone: string;
  readonly input: Input;
  readonly overlap: ScheduleOverlap;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L17)

### ScheduleOverlap (type alias)

Legacy policy for simultaneous schedule occurrences.

**Signature**

```ts
type ScheduleOverlap = "skip" | "allow";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy-define-job.types.ts#L15)

## `legacy.ts`

Explicit one-release compatibility surface for function-target enqueue jobs.

### "./client.js" (namespace export)

Re-exports all named exports from the "./client.js" module.

**Signature**

```ts
export * from "./client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy.ts#L3)

### "./legacy-define-job.js" (namespace export)

Re-exports all named exports from the "./legacy-define-job.js" module.

**Signature**

```ts
export * from "./legacy-define-job.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/legacy.ts#L2)

## `migration-support.ts`

### breakingEffect

Constructs one breaking diagnostic within a migration Effect.

**Example**

```ts
Effect.runSync(breakingEffect("TASK_ID_CHANGED", "Task changed"));
```

**Signature**

```ts
declare const breakingEffect: (
  code:
    | "TASK_ID_CHANGED"
    | "TASK_VERSION_CHANGED"
    | "TASK_INPUT_SCHEMA_CHANGED"
    | "DEDUPE_SCOPE_CHANGED"
    | "PUBLIC_CLIENT_FINGERPRINT_CHANGED"
    | "LEGACY_JOBS_DISABLED"
    | "LEGACY_ALIAS_CONFLICT",
  message: string,
) => Effect.Effect<JobMigrationDiagnostic, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration-support.ts#L10)

### sameEffect

Compares schedule identifiers in authored order.

**Example**

```ts
Effect.runSync(sameEffect(["daily"], ["daily"]));
```

**Signature**

```ts
declare const sameEffect: (
  left: ReadonlyArray<string> | undefined,
  right: ReadonlyArray<string> | undefined,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration-support.ts#L32)

## `migration.ts`

### JobBindingMigration

**Signature**

```ts
declare const JobBindingMigration: JobBindingMigration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L11)

### JobMigrationDiagnostic

**Signature**

```ts
declare const JobMigrationDiagnostic: JobMigrationDiagnostic;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L12)

### JobMigrationSeverity

**Signature**

```ts
declare const JobMigrationSeverity: JobMigrationSeverity;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L13)

### JobMigrationSnapshot

**Signature**

```ts
declare const JobMigrationSnapshot: JobMigrationSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L14)

### LegacyCompatibilitySnapshot

**Signature**

```ts
declare const LegacyCompatibilitySnapshot: LegacyCompatibilitySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L15)

### diagnoseJobMigration

Synchronous migration diagnostic adapter.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
diagnoseJobMigration(previous, next);
```

**Signature**

```ts
declare const diagnoseJobMigration: (
  previous: JobMigrationSnapshot,
  next: JobMigrationSnapshot,
) => readonly JobMigrationDiagnostic[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L116)

### diagnoseJobMigrationEffect

Diagnoses identity and contract changes between two job snapshots in Effect.

**Example**

```ts
Effect.runSync(diagnoseJobMigrationEffect(previous, next));
```

**Signature**

```ts
declare const diagnoseJobMigrationEffect: (
  previous: JobMigrationSnapshot,
  next: JobMigrationSnapshot,
) => Effect.Effect<ReadonlyArray<JobMigrationDiagnostic>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L24)

### diagnoseLegacyCompatibility

Synchronous legacy compatibility diagnostic adapter.

**Throws**

A runtime defect if the Effect cannot execute synchronously.

**Example**

```ts
diagnoseLegacyCompatibility(snapshot);
```

**Signature**

```ts
declare const diagnoseLegacyCompatibility: (
  snapshot: LegacyCompatibilitySnapshot,
) => readonly JobMigrationDiagnostic[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L176)

### diagnoseLegacyCompatibilityEffect

Diagnoses legacy configuration aliases in Effect.

**Example**

```ts
Effect.runSync(diagnoseLegacyCompatibilityEffect(snapshot));
```

**Signature**

```ts
declare const diagnoseLegacyCompatibilityEffect: (
  snapshot: LegacyCompatibilitySnapshot,
) => Effect.Effect<ReadonlyArray<JobMigrationDiagnostic>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.ts#L128)

## `migration.types.ts`

Binding mode recorded in a job migration snapshot.

### JobBindingMigration (type alias)

Binding mode recorded in a job migration snapshot.

**Signature**

```ts
type JobBindingMigration = "implicit" | "default" | "explicit";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.types.ts#L2)

### JobMigrationDiagnostic (interface)

Actionable compatibility finding for an authored job change.

**Signature**

```ts
export interface JobMigrationDiagnostic {
  readonly code:
    | "DEFAULT_DERIVED_JOB_ID_RENAME"
    | "PINNED_JOB_ID_CHANGED"
    | "IMPLICIT_TO_EXPLICIT_BINDING"
    | "TASK_ID_CHANGED"
    | "TASK_VERSION_CHANGED"
    | "TASK_INPUT_SCHEMA_CHANGED"
    | "HISTORICAL_RUNS_PINNED"
    | "SCHEDULE_TARGET_CHANGED"
    | "DEDUPE_SCOPE_CHANGED"
    | "PUBLIC_CLIENT_FINGERPRINT_CHANGED"
    | "LEGACY_JOBS_DISABLED"
    | "LEGACY_ALIAS_CONFLICT"
    | "LEGACY_ALIAS_DEPRECATED";
  readonly severity: JobMigrationSeverity;
  readonly breaking: boolean;
  readonly message: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.types.ts#L25)

### JobMigrationSeverity (type alias)

Severity assigned to one compatibility diagnostic.

**Signature**

```ts
type JobMigrationSeverity = "warning" | "error";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.types.ts#L5)

### JobMigrationSnapshot (interface)

Versioned job identity and public contract facts used by migration checks.

**Signature**

```ts
export interface JobMigrationSnapshot {
  readonly name: string;
  readonly id: string;
  readonly idSource?: "explicit" | "name";
  readonly taskId: string;
  readonly taskVersion: string;
  readonly inputSchemaHash?: string;
  readonly binding: JobBindingMigration;
  readonly publicFingerprint?: string;
  readonly clientFingerprint?: string;
  readonly service?: string;
  readonly hasHistoricalRuns?: boolean;
  readonly scheduleIds?: readonly string[];
  readonly dedupeScope?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.types.ts#L8)

### LegacyCompatibilitySnapshot (interface)

Legacy and replacement configuration keys involved in migration.

**Signature**

```ts
export interface LegacyCompatibilitySnapshot {
  readonly usesFunctionTarget: boolean;
  readonly legacyJobsEnabled: boolean;
  readonly legacyKeys?: readonly ("job" | "defaults.job" | "profile")[];
  readonly newKeys?: readonly ("jobs" | "defaults.jobs" | "service")[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/migration.types.ts#L46)

## `resolve-binding-error.ts`

### JobBindingResolutionError (class)

A deterministic task-to-job binding resolution failure.

**Example**

```ts
new JobBindingResolutionError("UNKNOWN_JOB_SELECTOR", "Unknown job");
```

**Signature**

```ts
declare class JobBindingResolutionError {
  constructor(code: JobBindingErrorCode, message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-error.ts#L6)

### code (property)

**Signature**

```ts
readonly code: JobBindingErrorCode
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-error.ts#L7)

## `resolve-binding-support.ts`

### JobBindingSupportFailure (class)

A provider profile selection failure with a stable resolution code.

**Example**

```ts
new JobBindingSupportFailure({ code: "UNKNOWN_JOB_PROFILE", reason: "Unknown profile" });
```

**Signature**

```ts
declare class JobBindingSupportFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-support.ts#L9)

### selectProfile

Synchronous provider profile selector.

**Throws**

JobBindingResolutionError for missing or unknown profiles.

**Example**

```ts
selectProfile(undefined, ["default"], "send");
```

**Signature**

```ts
declare const selectProfile: (
  requested: string | undefined,
  profiles: ResolveBindingOptions["profiles"],
  jobId: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-support.ts#L42)

### selectProfileEffect

Selects a provider profile in Effect.

**Example**

```ts
Effect.runSync(selectProfileEffect(undefined, ["default"], "send"));
```

**Signature**

```ts
declare const selectProfileEffect: (
  requested: string | undefined,
  profiles: ReadonlyArray<string> | Readonly<Record<string, unknown>> | undefined,
  jobId: string,
) => Effect.Effect<string, JobBindingSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-support.ts#L20)

### taskIdOf

Synchronous task reference id reader.

**Example**

```ts
taskIdOf(taskRef);
```

**Signature**

```ts
declare const taskIdOf: (value: TaskRefAny | undefined) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-support.ts#L71)

### taskIdOfEffect

Reads a task reference id in Effect.

**Example**

```ts
Effect.runSync(taskIdOfEffect(taskRef));
```

**Signature**

```ts
declare const taskIdOfEffect: (
  value: TaskRefAny | undefined,
) => Effect.Effect<string, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding-support.ts#L60)

## `resolve-binding.ts`

### BindingSource

**Signature**

```ts
declare const BindingSource: BindingSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L16)

### JobBindingErrorCode

**Signature**

```ts
declare const JobBindingErrorCode: JobBindingErrorCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L17)

### JobBindingFailure (class)

A typed task-to-job binding resolution failure.

**Example**

```ts
if (error instanceof JobBindingFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobBindingFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L25)

### JobBindingResolutionError

**Signature**

```ts
declare const JobBindingResolutionError: typeof JobBindingResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L21)

### ResolveBindingOptions

**Signature**

```ts
declare const ResolveBindingOptions: ResolveBindingOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L18)

### ResolvedTaskBinding

**Signature**

```ts
declare const ResolvedTaskBinding: ResolvedTaskBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L19)

### resolveBinding

Compatibility alias for task-to-job binding resolution.

**Throws**

JobBindingResolutionError for invalid or ambiguous bindings.

**Example**

```ts
resolveBinding({ task, implicitName: "send" });
```

**Signature**

```ts
declare const resolveBinding: (options: ResolveBindingOptions) => ResolvedTaskBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L118)

### resolveTaskBinding

Synchronous compatibility resolver for one task.

**Throws**

JobBindingResolutionError on ambiguity or invalid selector.

**Example**

```ts
resolveTaskBinding(options);
```

**Signature**

```ts
declare const resolveTaskBinding: (options: ResolveBindingOptions) => ResolvedTaskBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L54)

### resolveTaskBindingEffect

Resolves an explicit, default, or private implicit job in Effect.

**Example**

```ts
Effect.runSync(resolveTaskBindingEffect(options));
```

**Signature**

```ts
declare const resolveTaskBindingEffect: (
  options: ResolveBindingOptions,
) => Effect.Effect<ResolvedTaskBinding, JobBindingFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.ts#L34)

## `resolve-binding.types.ts`

### BindingSource (type alias)

How a task selected its job binding.

**Signature**

```ts
type BindingSource = "explicit" | "default" | "implicit";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.types.ts#L5)

### JobBindingErrorCode (type alias)

Machine-readable reason for a binding resolution failure.

**Signature**

```ts
type JobBindingErrorCode =
  | "MISSING_IMPLICIT_NAME"
  | "INVALID_IMPLICIT_NAME"
  | "TASK_SELECTOR_MISMATCH"
  | "UNKNOWN_JOB_SELECTOR"
  | "AMBIGUOUS_JOB"
  | "DUPLICATE_JOB_ID"
  | "MULTIPLE_DEFAULT_JOBS"
  | "MISSING_JOB_PROFILE"
  | "AMBIGUOUS_JOB_PROFILE"
  | "UNKNOWN_JOB_PROFILE";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.types.ts#L33)

### ResolveBindingOptions (interface)

Inputs for resolving one task to its executable job.

**Signature**

```ts
export interface ResolveBindingOptions {
  readonly task: TaskRefAny;
  readonly jobs?: readonly JobDescriptorAny[];
  readonly selector?: JobDescriptorAny | JobRefAny;
  readonly implicitName?: string;
  readonly profiles?: readonly string[] | Readonly<Record<string, unknown>>;
  readonly defaultProfile?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.types.ts#L8)

### ResolvedTaskBinding (interface)

Canonical task-to-job selection returned by the binding resolver.

**Signature**

```ts
export interface ResolvedTaskBinding {
  readonly taskId: string;
  readonly taskVersion?: string;
  readonly jobId: string;
  readonly name: string;
  readonly service?: string;
  readonly profile: string;
  readonly source: BindingSource;
  readonly implicit: boolean;
  readonly default: boolean;
  readonly private: boolean;
  readonly job?: JobDescriptorAny;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/resolve-binding.types.ts#L18)

## `retry-policy.ts`

### RetryPolicyValidationError (class)

An invalid authored legacy retry policy.

**Example**

```ts
new RetryPolicyValidationError({ reason: "retry.maxAttempts must be positive" });
```

**Signature**

```ts
declare class RetryPolicyValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/retry-policy.ts#L8)

### validateRetry

Synchronous legacy retry policy validator.

**Throws**

TypeError when any retry field is invalid.

**Example**

```ts
validateRetry({ maxAttempts: 2, initialDelayMs: 0, maxDelayMs: 0, multiplier: 1, jitter: "none" });
```

**Signature**

```ts
declare const validateRetry: (value: LegacyRetryPolicy) => LegacyRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/retry-policy.ts#L46)

### validateRetryEffect

Validates legacy retry policy fields in Effect.

**Example**

```ts
Effect.runPromise(
  validateRetryEffect({
    maxAttempts: 2,
    initialDelayMs: 0,
    maxDelayMs: 0,
    multiplier: 1,
    jitter: "none",
  }),
);
```

**Signature**

```ts
declare const validateRetryEffect: (value: RetryPolicy) => Effect.Effect<
  Readonly<{
    maxAttempts: number;
    initialDelayMs: number;
    maxDelayMs: number;
    multiplier: number;
    jitter: RetryJitter;
  }>,
  RetryPolicyValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/retry-policy.ts#L18)

## `retry-policy.types.ts`

### LegacyRetryPolicy (type alias)

Legacy authored retry policy accepted by the validation boundary.

**Signature**

```ts
type LegacyRetryPolicy = RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/retry-policy.types.ts#L4)

## `run-id-codec.ts`

### createRunLocatorValue

Serializes and signs a validated run locator payload.

**Throws**

RunLocatorError when keys, payload, or encoded length are invalid.

**Example**

```ts
createRunLocatorValue({ keyRing, payload });
```

**Signature**

```ts
declare const createRunLocatorValue: (options: RunLocatorCreateOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-codec.ts#L25)

### rotateRunLocatorKeysValue

Adds a signing key while retaining prior keys for existing locators.

**Throws**

RunLocatorError when the ring or new key identifier is invalid.

**Example**

```ts
rotateRunLocatorKeysValue(keyRing, "v2", "new-secret");
```

**Signature**

```ts
declare const rotateRunLocatorKeysValue: (
  ring: RunLocatorKeyRing,
  keyId: string,
  secret: string | Uint8Array,
) => RunLocatorKeyRing;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-codec.ts#L98)

### verifyRunLocatorValue

Verifies a locator signature, payload, and requested deployment namespace.

**Throws**

RunLocatorError on malformed encoding, signature, or namespace.

**Example**

```ts
verifyRunLocatorValue(locator, { keyRing, application: "shop" });
```

**Signature**

```ts
declare const verifyRunLocatorValue: (
  locator: string,
  options: RunLocatorVerifyOptions,
) => VerifiedRunLocator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-codec.ts#L46)

## `run-id-errors.ts`

Compatibility error for an invalid, unauthenticated, or unroutable locator.

**Example**

```ts
throw new RunLocatorError();
```

### RunLocatorError (class)

Compatibility error for an invalid, unauthenticated, or unroutable locator.

**Example**

```ts
throw new RunLocatorError();
```

**Signature**

```ts
declare class RunLocatorError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-errors.ts#L4)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_LOCATOR_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-errors.ts#L5)

## `run-id-router-store.ts`

### RunLocatorGenerationStorage (class)

Injectable persistence service for historical run locator generations.

**Example**

```ts
Effect.provide(RunLocatorRouter.fromStoreEffect(), runLocatorStoreLayer(store));
```

**Signature**

```ts
declare class RunLocatorGenerationStorage
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router-store.ts#L6)

### RunLocatorStoreFailure (class)

Failure from generation persistence, preserving the original cause.

**Example**

```ts
if (error instanceof RunLocatorStoreFailure) console.log(error.message);
```

**Signature**

```ts
declare class RunLocatorStoreFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router-store.ts#L21)

### runLocatorStoreLayer

Provides a concrete generation store to Effect operations.

**Example**

```ts
runLocatorStoreLayer(memoryStore);
```

**Signature**

```ts
declare const runLocatorStoreLayer: (
  store: RunLocatorGenerationStore,
) => Layer.Layer<RunLocatorGenerationStorage, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router-store.ts#L15)

## `run-id-router.ts`

### RunLocatorGeneration

**Signature**

```ts
declare const RunLocatorGeneration: RunLocatorGeneration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L16)

### RunLocatorGenerationStorage

**Signature**

```ts
declare const RunLocatorGenerationStorage: typeof RunLocatorGenerationStorage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L18)

### RunLocatorGenerationStore

**Signature**

```ts
declare const RunLocatorGenerationStore: RunLocatorGenerationStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L16)

### RunLocatorRouter (class)

Routes signed run locators through retained service generations.

**Example**

```ts
new RunLocatorRouter([{ generation: "v1", keyRing }]);
```

**Signature**

```ts
declare class RunLocatorRouter {
  constructor(generations: readonly RunLocatorGeneration[] = []);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L25)

### fromStore (static method)

Promise compatibility loader.

**Throws**

The original storage error.

**Example**

```ts
await RunLocatorRouter.fromStore(store);
```

**Signature**

```ts
declare const fromStore: (store: RunLocatorGenerationStore) => Promise<RunLocatorRouter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L59)

### register (method)

Synchronous generation registration.

**Throws**

RunLocatorError for invalid generation or keys.

**Example**

```ts
router.register("v2", ring);
```

**Signature**

```ts
declare const register: (generation: string, keyRing: RunLocatorKeyRing) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L99)

### snapshot (method)

Synchronous snapshot of retained generations.

**Example**

```ts
router.snapshot();
```

**Signature**

```ts
declare const snapshot: () => readonly RunLocatorGeneration[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L123)

### persist (method)

Promise compatibility persistence.

**Throws**

The original storage error.

**Example**

```ts
await router.persist(store);
```

**Signature**

```ts
declare const persist: (store: RunLocatorGenerationStore) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L151)

### route (method)

Synchronously routes a signed locator.

**Throws**

RunLocatorError when no retained generation matches.

**Example**

```ts
router.route(locator);
```

**Signature**

```ts
declare const route: (
  locator: string,
  options?: Omit<RunLocatorVerifyOptions, "keyRing">,
) => VerifiedRunLocator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L188)

### registerEffect (property)

Registers a generation in Effect.

**Example**

```ts
Effect.runSync(router.registerEffect("v2", ring));
```

**Signature**

```ts
readonly registerEffect: (generation: string, keyRing: RunLocatorKeyRing) => Effect.Effect<void, RunLocatorFailure, never>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L74)

### snapshotEffect (property)

Returns a sorted frozen snapshot in Effect.

**Example**

```ts
Effect.runSync(router.snapshotEffect());
```

**Signature**

```ts
readonly snapshotEffect: () => Effect.Effect<ReadonlyArray<Readonly<{ generation: string; keyRing: RunLocatorKeyRing; }>>, never, never>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L107)

### persistEffect (property)

Persists the current snapshot through the storage service.

**Example**

```ts
Effect.runPromise(Effect.provide(router.persistEffect(), runLocatorStoreLayer(store)));
```

**Signature**

```ts
readonly persistEffect: () => Effect.Effect<void, RunLocatorStoreFailure, RunLocatorGenerationStorage>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L130)

### routeEffect (property)

Routes a locator through retained generations in Effect.

**Example**

```ts
Effect.runSync(router.routeEffect(locator));
```

**Signature**

```ts
readonly routeEffect: (locator: string, options?: Omit<RunLocatorVerifyOptions, "keyRing"> | undefined) => Effect.Effect<VerifiedRunLocator, RunLocatorFailure, never>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L163)

### RunLocatorStoreFailure

**Signature**

```ts
declare const RunLocatorStoreFailure: typeof RunLocatorStoreFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L19)

### runLocatorStoreLayer

**Signature**

```ts
declare const runLocatorStoreLayer: (
  store: RunLocatorGenerationStore,
) => Layer<RunLocatorGenerationStorage, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.ts#L20)

## `run-id-router.types.ts`

### RunLocatorGeneration (interface)

One retained service generation and its locator verification keys.

**Signature**

```ts
export interface RunLocatorGeneration {
  readonly generation: string;
  readonly keyRing: RunLocatorKeyRing;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.types.ts#L3)

### RunLocatorGenerationStore (interface)

Replaceable persistence boundary for locator generations.

**Signature**

```ts
export interface RunLocatorGenerationStore {
  readonly load: () => readonly RunLocatorGeneration[] | Promise<readonly RunLocatorGeneration[]>;
  readonly save: (generations: readonly RunLocatorGeneration[]) => void | Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-router.types.ts#L8)

## `run-id-support.ts`

### assertSegment

Validates a bounded printable locator key identifier.

**Throws**

RunLocatorError for unsupported characters or length.

**Example**

```ts
assertSegment("key-v1");
```

**Signature**

```ts
declare const assertSegment: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-support.ts#L102)

### isBase64Url

Checks canonical unpadded base64url encoding for one locator segment.

**Example**

```ts
isBase64Url("YQ");
```

**Signature**

```ts
declare const isBase64Url: (value: string | undefined) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-support.ts#L87)

### namespaceHash

Hashes the trusted deployment namespace used to bind durable run locators.

**Throws**

RunLocatorError when an identity is empty or exceeds its byte limit.

**Example**

```ts
namespaceHash("shop", "production", "orders");
```

**Signature**

```ts
declare const namespaceHash: (application: string, environment: string, scope: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-support.ts#L13)

### normalizePayload

Validates and freezes the payload before it is signed or returned to callers.

**Throws**

RunLocatorError for malformed identities or a mismatched namespace.

**Example**

```ts
normalizePayload(payload);
```

**Signature**

```ts
declare const normalizePayload: (value: RunLocatorPayload) => RunLocatorPayload;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-support.ts#L26)

### validateRunLocatorKeyRing

Verifies the active key and every key identifier and secret in a key ring.

**Throws**

RunLocatorError for missing, oversized, or malformed keys.

**Example**

```ts
validateRunLocatorKeyRing({ activeKeyId: "v1", keys: { v1: "secret" } });
```

**Signature**

```ts
declare const validateRunLocatorKeyRing: (ring: RunLocatorKeyRing) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id-support.ts#L71)

## `run-id.ts`

### RUN_LOCATOR_MAX_BYTES

Maximum encoded locator size accepted at the jobs boundary.

**Example**

```ts
locator.length <= RUN_LOCATOR_MAX_BYTES;
```

**Signature**

```ts
declare const RUN_LOCATOR_MAX_BYTES: 4096;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L36)

### RUN_LOCATOR_VERSION

Wire format version for signed run locators.

**Example**

```ts
RUN_LOCATOR_VERSION === 1;
```

**Signature**

```ts
declare const RUN_LOCATOR_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L32)

### RunLocatorCreateOptions

**Signature**

```ts
declare const RunLocatorCreateOptions: RunLocatorCreateOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L14)

### RunLocatorError

**Signature**

```ts
declare const RunLocatorError: typeof RunLocatorError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L28)

### RunLocatorFailure (class)

Invalid signed run locator or key rotation.

**Example**

```ts
if (error instanceof RunLocatorFailure) console.log(error.message);
```

**Signature**

```ts
declare class RunLocatorFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L40)

### RunLocatorKeyRing

**Signature**

```ts
declare const RunLocatorKeyRing: RunLocatorKeyRing;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L12)

### RunLocatorKeyRingStore

**Signature**

```ts
declare const RunLocatorKeyRingStore: RunLocatorKeyRingStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L13)

### RunLocatorPayload

**Signature**

```ts
declare const RunLocatorPayload: RunLocatorPayload;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L11)

### RunLocatorVerifyOptions

**Signature**

```ts
declare const RunLocatorVerifyOptions: RunLocatorVerifyOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L15)

### VerifiedRunLocator

**Signature**

```ts
declare const VerifiedRunLocator: VerifiedRunLocator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L16)

### createRunLocator

Synchronously signs a run locator.

**Throws**

RunLocatorError when the payload or key ring is invalid.

**Example**

```ts
createRunLocator({ payload, keyRing });
```

**Signature**

```ts
declare const createRunLocator: (options: RunLocatorCreateOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L108)

### createRunLocatorEffect

Signs a run locator in Effect.

**Example**

```ts
Effect.runSync(createRunLocatorEffect({ payload, keyRing }));
```

**Signature**

```ts
declare const createRunLocatorEffect: (
  options: RunLocatorCreateOptions,
) => Effect.Effect<string, RunLocatorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L95)

### decodeRunLocator

Compatibility alias for verifyRunLocator.

**Example**

```ts
decodeRunLocator(locator, { keyRing });
```

**Signature**

```ts
declare const decodeRunLocator: (
  locator: string,
  options: RunLocatorVerifyOptions,
) => VerifiedRunLocator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L144)

### encodeRunLocator

Compatibility alias for createRunLocator.

**Example**

```ts
encodeRunLocator({ payload, keyRing });
```

**Signature**

```ts
declare const encodeRunLocator: (options: RunLocatorCreateOptions) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L140)

### namespaceHash

Synchronously hashes a trusted deployment namespace.

**Throws**

RunLocatorError for invalid identities.

**Example**

```ts
namespaceHash("shop", "production", "orders");
```

**Signature**

```ts
declare const namespaceHash: (application: string, environment: string, scope: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L66)

### namespaceHashEffect

Hashes a trusted deployment namespace in Effect.

**Example**

```ts
Effect.runSync(namespaceHashEffect("shop", "production", "orders"));
```

**Signature**

```ts
declare const namespaceHashEffect: (
  application: string,
  environment: string,
  scope: string,
) => Effect.Effect<string, RunLocatorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L51)

### rotateRunLocatorKeys

Synchronously rotates a locator signing key.

**Throws**

RunLocatorError when the ring or key identifier is invalid.

**Example**

```ts
rotateRunLocatorKeys(ring, "v2", secret);
```

**Signature**

```ts
declare const rotateRunLocatorKeys: (
  ring: RunLocatorKeyRing,
  keyId: string,
  secret: string | Uint8Array,
) => RunLocatorKeyRing;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L167)

### rotateRunLocatorKeysEffect

Rotates the active locator signing key in Effect.

**Example**

```ts
Effect.runSync(rotateRunLocatorKeysEffect(ring, "v2", secret));
```

**Signature**

```ts
declare const rotateRunLocatorKeysEffect: (
  ring: RunLocatorKeyRing,
  keyId: string,
  secret: string | Uint8Array<ArrayBufferLike>,
) => Effect.Effect<RunLocatorKeyRing, RunLocatorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L152)

### validateRunLocatorKeyRing

Synchronously validates a locator key ring.

**Throws**

RunLocatorError for invalid keys or IDs.

**Example**

```ts
validateRunLocatorKeyRing(ring);
```

**Signature**

```ts
declare const validateRunLocatorKeyRing: (ring: RunLocatorKeyRing) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L87)

### validateRunLocatorKeyRingEffect

Validates a locator key ring in Effect.

**Example**

```ts
Effect.runSync(validateRunLocatorKeyRingEffect(ring));
```

**Signature**

```ts
declare const validateRunLocatorKeyRingEffect: (
  ring: RunLocatorKeyRing,
) => Effect.Effect<void, RunLocatorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L74)

### verifyRunLocator

Synchronously verifies a signed run locator.

**Throws**

RunLocatorError when the locator is invalid or has another namespace.

**Example**

```ts
verifyRunLocator(locator, { keyRing });
```

**Signature**

```ts
declare const verifyRunLocator: (
  locator: string,
  options: RunLocatorVerifyOptions,
) => VerifiedRunLocator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L131)

### verifyRunLocatorEffect

Verifies a run locator in Effect.

**Example**

```ts
Effect.runSync(verifyRunLocatorEffect(locator, { keyRing }));
```

**Signature**

```ts
declare const verifyRunLocatorEffect: (
  locator: string,
  options: RunLocatorVerifyOptions,
) => Effect.Effect<VerifiedRunLocator, RunLocatorFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.ts#L117)

## `run-id.types.ts`

Signed run identity and namespace fields carried by a locator.

### RunLocatorCreateOptions (interface)

Options accepted for run locator create operations.

**Signature**

```ts
export interface RunLocatorCreateOptions {
  readonly payload: RunLocatorPayload;
  readonly keyRing: RunLocatorKeyRing;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L27)

### RunLocatorKeyRing (interface)

Signing and verification keys for run locators.

**Signature**

```ts
export interface RunLocatorKeyRing {
  readonly activeKeyId: string;
  readonly keys: Readonly<Record<string, string | Uint8Array>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L17)

### RunLocatorKeyRingStore (interface)

Store of key rings used during locator rotation.

**Signature**

```ts
export interface RunLocatorKeyRingStore {
  readonly load: () => RunLocatorKeyRing | Promise<RunLocatorKeyRing>;
  readonly save: (ring: RunLocatorKeyRing) => void | Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L22)

### RunLocatorPayload (interface)

Signed run identity and namespace fields carried by a locator.

**Signature**

```ts
export interface RunLocatorPayload {
  readonly application: string;
  readonly environment: string;
  readonly serviceGeneration: string;
  readonly jobId: string;
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  /** Accepted only while creating a locator; the clear-text scope is never encoded. */
  readonly scope?: string;
  readonly namespaceHash?: string;
  readonly schemaHash?: string;
  readonly native: { readonly kind: string; readonly value: string };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L2)

### RunLocatorVerifyOptions (interface)

Options accepted for run locator verify operations.

**Signature**

```ts
export interface RunLocatorVerifyOptions {
  readonly keyRing: RunLocatorKeyRing;
  readonly application?: string;
  readonly environment?: string;
  readonly scope?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L32)

### VerifiedRunLocator (interface)

Decoded signed locator with trusted namespace and run identity.

**Signature**

```ts
export interface VerifiedRunLocator extends RunLocatorPayload {
  readonly keyId: string;
  readonly version: 1;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/run-id.types.ts#L39)

## `runtime-context.ts`

### JobsRuntimeCallbackError (class)

Failure raised by a callback executed inside an ambient runtime.

**Example**

```ts
if (error instanceof JobsRuntimeCallbackError) console.log(error.message);
```

**Signature**

```ts
declare class JobsRuntimeCallbackError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L15)

### JobsRuntimeError (class)

Invalid runtime configuration or missing ambient runtime.

**Example**

```ts
if (error instanceof JobsRuntimeError) console.log(error.message);
```

**Signature**

```ts
declare class JobsRuntimeError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L9)

### currentJobsRuntime

Reads the ambient runtime synchronously.

**Example**

```ts
currentJobsRuntime();
```

**Signature**

```ts
declare const currentJobsRuntime: () => JobsRuntime | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L33)

### currentJobsRuntimeEffect

Reads the ambient runtime in Effect.

**Example**

```ts
Effect.runSync(currentJobsRuntimeEffect());
```

**Signature**

```ts
declare const currentJobsRuntimeEffect: () => Effect.Effect<JobsRuntime | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L23)

### requireJobsRuntime

Requires an ambient runtime synchronously.

**Throws**

Error when no runtime is bound.

**Example**

```ts
requireJobsRuntime();
```

**Signature**

```ts
declare const requireJobsRuntime: () => JobsRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L54)

### requireJobsRuntimeEffect

Requires an ambient runtime in Effect.

**Example**

```ts
Effect.runSync(requireJobsRuntimeEffect());
```

**Signature**

```ts
declare const requireJobsRuntimeEffect: () => Effect.Effect<JobsRuntime, JobsRuntimeError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L40)

### runInJobsRuntime

Runs a callback with a runtime bound to its async context.

**Throws**

The original callback error, if it throws.

**Example**

```ts
runInJobsRuntime(runtime, () => requireJobsRuntime());
```

**Signature**

```ts
declare const runInJobsRuntime: <A>(runtime: JobsRuntime, callback: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L82)

### runInJobsRuntimeEffect

Runs a callback with the given ambient runtime in Effect.

**Example**

```ts
Effect.runSync(runInJobsRuntimeEffect(runtime, () => requireJobsRuntime()));
```

**Signature**

```ts
declare const runInJobsRuntimeEffect: <A>(
  runtime: JobsRuntime,
  callback: () => A,
) => Effect.Effect<A, JobsRuntimeCallbackError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L65)

### runWithJobsRuntime

Alias of runInJobsRuntime.

**Throws**

The original callback error.

**Example**

```ts
runWithJobsRuntime(runtime, () => 1);
```

**Signature**

```ts
declare const runWithJobsRuntime: <A>(runtime: JobsRuntime, callback: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L101)

### runWithJobsRuntimeEffect

Alias of runInJobsRuntimeEffect.

**Example**

```ts
Effect.runSync(runWithJobsRuntimeEffect(runtime, () => 1));
```

**Signature**

```ts
declare const runWithJobsRuntimeEffect: <A>(
  runtime: JobsRuntime,
  callback: () => A,
) => Effect.Effect<A, JobsRuntimeCallbackError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-context.ts#L93)

## `runtime-selection-value.ts`

### resolveBindingValue

Selects a task's job from the runtime manifest and validates its build binding.

**Throws**

TypeError for missing, ambiguous, or mismatched bindings.

**Example**

```ts
resolveBindingValue(task, undefined, options);
```

**Signature**

```ts
declare const resolveBindingValue: (
  task: TaskRefAny,
  selector: JobRefAny | undefined,
  options: JobsRuntimeOptions,
) => JobsRuntimeBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-selection-value.ts#L12)

## `runtime-selection.ts`

### RuntimeBindingFailure (class)

Invalid manifest or selector resolution for a runtime binding.

**Example**

```ts
if (error instanceof RuntimeBindingFailure) console.log(error.message);
```

**Signature**

```ts
declare class RuntimeBindingFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-selection.ts#L9)

### resolveBinding

Synchronous runtime binding resolver.

**Throws**

TypeError for ambiguous or unknown jobs.

**Example**

```ts
resolveBinding(task, undefined, options);
```

**Signature**

```ts
declare const resolveBinding: (
  task: TaskRefAny,
  selector: JobRefAny | undefined,
  options: JobsRuntimeOptions,
) => JobsRuntimeBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-selection.ts#L42)

### resolveBindingEffect

Resolves a task's runtime binding in Effect.

**Example**

```ts
Effect.runSync(resolveBindingEffect(task, undefined, options));
```

**Signature**

```ts
declare const resolveBindingEffect: (
  task: TaskRefAny,
  selector: JobRefAny | undefined,
  options: JobsRuntimeOptions,
) => Effect.Effect<JobsRuntimeBinding, RuntimeBindingFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime-selection.ts#L20)

## `runtime.ts`

### JobsManifestLike

**Signature**

```ts
declare const JobsManifestLike: JobsManifestLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L37)

### JobsOperationOptions

**Signature**

```ts
declare const JobsOperationOptions: JobsOperationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L38)

### JobsRuntime

**Signature**

```ts
declare const JobsRuntime: JobsRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L39)

### JobsRuntimeBinding

**Signature**

```ts
declare const JobsRuntimeBinding: JobsRuntimeBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L41)

### JobsRuntimeCallbackError

**Signature**

```ts
declare const JobsRuntimeCallbackError: typeof JobsRuntimeCallbackError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L19)

### JobsRuntimeError

**Signature**

```ts
declare const JobsRuntimeError: typeof JobsRuntimeError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L18)

### JobsRuntimeOptions

**Signature**

```ts
declare const JobsRuntimeOptions: JobsRuntimeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L40)

### NativeLocator

**Signature**

```ts
declare const NativeLocator: string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L129)

### TaskDescriptorAny

**Signature**

```ts
declare const TaskDescriptorAny: TaskDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L130)

### createJobsRuntime

Synchronously creates a validated jobs runtime.

**Throws**

TypeError or JobsCapabilityError for invalid configuration.

**Example**

```ts
createJobsRuntime({ adapter });
```

**Signature**

```ts
declare const createJobsRuntime: (options: JobsRuntimeOptions) => JobsRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L66)

### createJobsRuntimeEffect

Creates a validated jobs runtime in Effect.

**Example**

```ts
Effect.runSync(createJobsRuntimeEffect({ adapter }));
```

**Signature**

```ts
declare const createJobsRuntimeEffect: (
  options: JobsRuntimeOptions,
) => Effect.Effect<
  JobsRuntime,
  JobsCapabilityFailure | JobsAdapterValidationError | JobsRuntimeError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L48)

### currentJobsRuntime

**Signature**

```ts
declare const currentJobsRuntime: () => JobsRuntime | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L20)

### currentJobsRuntimeEffect

**Signature**

```ts
declare const currentJobsRuntimeEffect: () => Effect.Effect<JobsRuntime | undefined, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L21)

### requireJobsRuntime

**Signature**

```ts
declare const requireJobsRuntime: () => JobsRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L22)

### requireJobsRuntimeEffect

**Signature**

```ts
declare const requireJobsRuntimeEffect: () => Effect.Effect<JobsRuntime, JobsRuntimeError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L23)

### runInJobsRuntime

**Signature**

```ts
declare const runInJobsRuntime: <A>(runtime: JobsRuntime, callback: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L24)

### runInJobsRuntimeEffect

**Signature**

```ts
declare const runInJobsRuntimeEffect: <A>(
  runtime: JobsRuntime,
  callback: () => A,
) => Effect.Effect<A, JobsRuntimeCallbackError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L25)

### runWithJobsRuntime

**Signature**

```ts
declare const runWithJobsRuntime: <A>(runtime: JobsRuntime, callback: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L26)

### runWithJobsRuntimeEffect

**Signature**

```ts
declare const runWithJobsRuntimeEffect: <A>(
  runtime: JobsRuntime,
  callback: () => A,
) => Effect.Effect<A, JobsRuntimeCallbackError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.ts#L27)

## `runtime.types.ts`

### JobsManifestLike (interface)

Minimal manifest fields used to resolve authored jobs and tasks.

**Signature**

```ts
export interface JobsManifestLike {
  readonly protocol?: string;
  readonly version?: number;
  readonly app?: string;
  readonly environment?: string;
  readonly jobsProtocolVersion?: number;
  readonly tasks?: readonly {
    readonly id: string;
    readonly version?: string;
    readonly buildId?: string;
    readonly schemaHashes?: unknown;
    readonly policy?: unknown;
  }[];
  readonly jobs?: readonly {
    readonly id: string;
    readonly name: string;
    readonly taskId: string;
    readonly taskVersion?: string;
    readonly buildId?: string;
    readonly profile?: string;
    readonly serviceGeneration?: string;
    readonly default?: boolean;
  }[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.types.ts#L12)

### JobsOperationOptions (type alias)

Caller signal and trusted metadata passed to a native jobs operation.

**Signature**

```ts
type JobsOperationOptions = Pick<OperationContext, "signal"> &
  Partial<
    Pick<
      OperationContext,
      | "scope"
      | "operationId"
      | "deadlineMs"
      | "correlationId"
      | "parentRunId"
      | "propagation"
      | "acceptanceIdentity"
      | "occurrenceIdentity"
      | "inputSchemaHash"
      | "retryOfRunId"
    >
  >;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.types.ts#L67)

### JobsRuntime (interface)

Validated runtime bindings and provider access for job operations.

**Signature**

```ts
export interface JobsRuntime {
  readonly adapter: JobsAdapterRuntime;
  readonly capabilities: JobsCapabilityReport;
  readonly application: string;
  readonly environment: string;
  readonly scope: string;
  readonly service: string;
  readonly serviceGeneration: string;
  readonly manifest?: JobsManifestLike;
  readonly jobs?: readonly JobDescriptorAny[];
  readonly taskExecutor?: TaskExecutor;
  readonly tasks?: readonly TaskDescriptorAny[];
  readonly resolveBinding: (task: TaskRefAny, selector?: JobRefAny) => JobsRuntimeBinding;
  readonly operationContext: (options: JobsOperationOptions) => OperationContext;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.types.ts#L84)

### JobsRuntimeBinding (interface)

Resolved task, job, service, and build identity pinned for one run.

**Signature**

```ts
export interface JobsRuntimeBinding {
  readonly taskId: string;
  readonly taskVersion: string;
  readonly jobId: string;
  readonly name: string;
  readonly profile: string;
  readonly service: string;
  readonly serviceGeneration: string;
  readonly buildId: string;
  readonly inputSchemaHash?: string;
  readonly scope?: string;
  readonly policy?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.types.ts#L37)

### JobsRuntimeOptions (interface)

Provider, manifest, and authored descriptors used to create a jobs runtime.

**Signature**

```ts
export interface JobsRuntimeOptions {
  readonly adapter?: unknown;
  readonly provider?: unknown;
  readonly providerHandle?: { readonly value: unknown };
  readonly capabilities?: JobsCapabilityReport;
  readonly application?: string;
  readonly environment?: string;
  readonly scope?: string;
  readonly service?: string;
  readonly serviceGeneration?: string;
  readonly manifest?: JobsManifestLike;
  readonly jobs?: readonly JobDescriptorAny[];
  readonly taskExecutor?: TaskExecutor;
  readonly tasks?: readonly TaskDescriptorAny[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/runtime.types.ts#L51)

## `schedule-controls-operations.ts`

### ScheduleOperationFailure (class)

Expected native schedule operation failure with its compatibility cause.

**Example**

```ts
new ScheduleOperationFailure({ cause: new Error("provider rejected") });
```

**Signature**

```ts
declare class ScheduleOperationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-operations.ts#L27)

### getScheduleOperationEffect

Reads one bounded native schedule in Effect.

**Example**

```ts
Effect.runPromise(getScheduleOperationEffect(runtime, schedule, "hourly"));
```

**Signature**

```ts
declare const getScheduleOperationEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  id: string,
  signal?: AbortSignal | undefined,
) => Effect.Effect<
  ScheduleReadReceipt<ScheduleDefinition<unknown>>,
  ScheduleOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-operations.ts#L74)

### listSchedulesOperationEffect

Lists bounded native schedules in Effect.

**Example**

```ts
Effect.runPromise(listSchedulesOperationEffect(runtime, schedule));
```

**Signature**

```ts
declare const listSchedulesOperationEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  options?: ScheduleListOptions | undefined,
) => Effect.Effect<
  ScheduleReadReceipt<ScheduleDefinition<unknown>>,
  ScheduleOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-operations.ts#L38)

### writeScheduleOperationEffect

Validates and performs one idempotent native schedule write in Effect.

**Example**

```ts
Effect.runPromise(writeScheduleOperationEffect(runtime, schedule, definition, options, "upsert"));
```

**Signature**

```ts
declare const writeScheduleOperationEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  value: string | ScheduleDefinition,
  options: ScheduleWriteOptions,
  operation: "delete" | "upsert" | "pause" | "resume",
) => Effect.Effect<Readonly<ScheduleWriteReceipt>, ScheduleOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-operations.ts#L104)

## `schedule-controls-value.ts`

### boundedCursor

Validates a native schedule pagination cursor byte limit.

**Throws**

RangeError when the cursor exceeds 4096 UTF-8 bytes.

**Example**

```ts
boundedCursor("next-page");
```

**Signature**

```ts
declare const boundedCursor: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L68)

### boundedId

Validates schedule and operation identifiers against the byte limit.

**Throws**

TypeError for missing or oversized identifiers.

**Example**

```ts
boundedId("hourly");
```

**Signature**

```ts
declare const boundedId: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L53)

### idleSignal

Creates a nonaborted signal when a caller did not supply one.

**Example**

```ts
idleSignal().aborted;
```

**Signature**

```ts
declare const idleSignal: () => AbortSignal;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L77)

### isOutcome

Checks the known native schedule write outcomes.

**Example**

```ts
isOutcome("paused");
```

**Signature**

```ts
declare const isOutcome: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L20)

### isRecord

Tests for a nonarray native response record.

**Example**

```ts
isRecord({ outcome: "available" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L44)

### isUnknown

Recognizes an uncertain native schedule write for recovery.

**Example**

```ts
isUnknown({ operationId: "op", outcome: "unknown" });
```

**Signature**

```ts
declare const isUnknown: (value: unknown) => value is UnknownControlOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L36)

### normalizeRead

Freezes a valid native schedule read receipt.

**Throws**

TypeError for an unrecognized outcome.

**Example**

```ts
normalizeRead({ outcome: "unavailable" });
```

**Signature**

```ts
declare const normalizeRead: (value: unknown) => ScheduleReadReceipt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls-value.ts#L9)

## `schedule-controls.ts`

### JobScheduleControlFailure (class)

A native schedule operation failed or returned an invalid receipt.

**Example**

```ts
if (error instanceof JobScheduleControlFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobScheduleControlFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L22)

### createScheduleControls

Synchronous schedule facade factory.

**Throws**

JobsCapabilityError when native schedules are unavailable.

**Example**

```ts
createScheduleControls(runtime);
```

**Signature**

```ts
declare const createScheduleControls: (runtime?: JobsRuntime) => JobScheduleClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L64)

### createScheduleControlsEffect

Creates a schedule facade in Effect.

**Example**

```ts
Effect.runSync(createScheduleControlsEffect(runtime));
```

**Signature**

```ts
declare const createScheduleControlsEffect: (
  runtime: JobsRuntime,
) => Effect.Effect<
  JobScheduleClient<ScheduleDefinition<unknown>>,
  JobScheduleControlFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L31)

### getScheduleEffect

Reads a single native schedule in Effect.

**Example**

```ts
Effect.runPromise(getScheduleEffect(runtime, schedule, "hourly"));
```

**Signature**

```ts
declare const getScheduleEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  id: string,
  signal?: AbortSignal | undefined,
) => Effect.Effect<
  ScheduleReadReceipt<ScheduleDefinition<unknown>>,
  JobScheduleControlFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L94)

### listSchedulesEffect

Lists native schedules in Effect.

**Example**

```ts
Effect.runPromise(listSchedulesEffect(runtime, schedule));
```

**Signature**

```ts
declare const listSchedulesEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  options?: ScheduleListOptions | undefined,
) => Effect.Effect<
  ScheduleReadReceipt<ScheduleDefinition<unknown>>,
  JobScheduleControlFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L76)

### writeScheduleEffect

Writes or changes a native schedule in Effect.

**Example**

```ts
Effect.runPromise(writeScheduleEffect(runtime, schedule, definition, options, "upsert"));
```

**Signature**

```ts
declare const writeScheduleEffect: (
  runtime: JobsRuntime,
  schedule: NativeScheduleOperations,
  value: string | ScheduleDefinition,
  options: ScheduleWriteOptions,
  operation: "delete" | "upsert" | "pause" | "resume",
) => Effect.Effect<Readonly<ScheduleWriteReceipt>, JobScheduleControlFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-controls.ts#L113)

## `schedule-reconciliation-identity.ts`

### scheduleOperationId

Synchronous idempotent native operation identity.

**Example**

```ts
scheduleOperationId(options, "hourly");
```

**Signature**

```ts
declare const scheduleOperationId: (
  options: Pick<ScheduleReconciliationOptions, "context" | "jobId" | "buildId">,
  scheduleId: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-identity.ts#L63)

### scheduleOperationIdEffect

Builds an idempotent native operation identity in Effect.

**Example**

```ts
Effect.runSync(scheduleOperationIdEffect(options, "hourly"));
```

**Signature**

```ts
declare const scheduleOperationIdEffect: (
  options: Pick<ScheduleReconciliationOptions, "jobId" | "context" | "buildId">,
  scheduleId: string,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-identity.ts#L39)

### scheduleOwner

Synchronous stable schedule owner identity.

**Example**

```ts
scheduleOwner({ context, jobId: "send" });
```

**Signature**

```ts
declare const scheduleOwner: (
  options: Pick<ScheduleReconciliationOptions, "context" | "jobId">,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-identity.ts#L28)

### scheduleOwnerEffect

Builds a stable owner identity in Effect.

**Example**

```ts
Effect.runSync(scheduleOwnerEffect({ context, jobId: "send" }));
```

**Signature**

```ts
declare const scheduleOwnerEffect: (
  options: Pick<ScheduleReconciliationOptions, "jobId" | "context">,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-identity.ts#L10)

## `schedule-reconciliation-service.ts`

### NativeScheduleService (class)

Injectable native provider for schedule reconciliation.

**Example**

```ts
const service = yield * NativeScheduleService;
```

**Signature**

```ts
declare class NativeScheduleService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-service.ts#L6)

### ScheduleReconciliationFailure (class)

Expected native schedule reconciliation failure with original cause.

**Example**

```ts
if (error instanceof ScheduleReconciliationFailure) console.log(error.message);
```

**Signature**

```ts
declare class ScheduleReconciliationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-service.ts#L20)

### nativeScheduleLayer

Provides a native schedule implementation to the Effect reconciler.

**Example**

```ts
nativeScheduleLayer(adapter.nativeSchedules);
```

**Signature**

```ts
declare const nativeScheduleLayer: (
  native: NativeScheduleOperations,
) => Layer.Layer<NativeScheduleService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-service.ts#L15)

## `schedule-reconciliation-support.ts`

### isRecord

Tests for a nonarray provider record.

**Example**

```ts
isRecord({ id: "hourly" });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L133)

### isScheduleRecord

Recognizes a native schedule record with an identifier.

**Example**

```ts
isScheduleRecord({ id: "hourly" });
```

**Signature**

```ts
declare const isScheduleRecord: (value: unknown) => value is NativeOwnedScheduleRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L85)

### nativeDefinition

Adds ownership and canonical input metadata to a desired native schedule.

**Throws**

TypeError for non-JSON schedule input.

**Example**

```ts
nativeDefinition(schedule, options, "owner-1");
```

**Signature**

```ts
declare const nativeDefinition: (
  schedule: ScheduleReconciliationOptions["desired"][number],
  options: Omit<ScheduleReconciliationOptions, "native">,
  owner: string,
) => Readonly<
  | {
      metadata: Readonly<{
        buildId: string;
        serviceGeneration: string;
        canonicalInput: string;
        taskVersion?: string;
        taskId?: string;
        owner: string;
        application: string;
        environment: string;
        service: string;
        scope: string;
        jobId: string;
      }>;
      id: string;
      input: unknown;
      overlap?: ScheduleOverlap;
      misfire?: ScheduleMisfire;
      cron: string;
      timezone: string;
      every?: never;
    }
  | {
      metadata: Readonly<{
        buildId: string;
        serviceGeneration: string;
        canonicalInput: string;
        taskVersion?: string;
        taskId?: string;
        owner: string;
        application: string;
        environment: string;
        service: string;
        scope: string;
        jobId: string;
      }>;
      id: string;
      input: unknown;
      overlap?: ScheduleOverlap;
      misfire?: ScheduleMisfire;
      every: DurationInput;
      cron?: never;
      timezone?: never;
    }
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L105)

### writeContext

Binds one stable operation identity to a native schedule write.

**Example**

```ts
writeContext(context, "schedule-upsert-1");
```

**Signature**

```ts
declare const writeContext: (
  context: OperationContext,
  operationIdValue: string,
) => OperationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L74)

### writeWithRecovery

Promise compatibility native write retry.

**Throws**

Original terminal write error or unknown outcome error.

**Example**

```ts
await writeWithRecovery(() => native.upsert(value, context), context);
```

**Signature**

```ts
declare const writeWithRecovery: (
  write: () => Promise<unknown>,
  context: OperationContext,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L60)

### writeWithRecoveryEffect

Retries an ambiguous native write once in Effect.

**Example**

```ts
Effect.runPromise(writeWithRecoveryEffect(() => native.upsert(value, context), context));
```

**Signature**

```ts
declare const writeWithRecoveryEffect: (
  write: () => Promise<unknown>,
  context: OperationContext,
) => Effect.Effect<unknown, ScheduleReconciliationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation-support.ts#L16)

## `schedule-reconciliation.ts`

### NativeOwnedScheduleRecord

**Signature**

```ts
declare const NativeOwnedScheduleRecord: NativeOwnedScheduleRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L23)

### NativeScheduleService

**Signature**

```ts
declare const NativeScheduleService: typeof NativeScheduleService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L28)

### ScheduleReconciliationFailure

**Signature**

```ts
declare const ScheduleReconciliationFailure: typeof ScheduleReconciliationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L30)

### ScheduleReconciliationOptions

**Signature**

```ts
declare const ScheduleReconciliationOptions: ScheduleReconciliationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L24)

### ScheduleReconciliationResult

**Signature**

```ts
declare const ScheduleReconciliationResult: ScheduleReconciliationResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L25)

### nativeScheduleLayer

**Signature**

```ts
declare const nativeScheduleLayer: (
  native: NativeScheduleOperations,
) => Layer<NativeScheduleService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L29)

### reconcileNativeSchedules

Promise compatibility reconciler.

**Throws**

The original native, validation, or ownership error.

**Example**

```ts
await reconcileNativeSchedules(options);
```

**Signature**

```ts
declare const reconcileNativeSchedules: (
  options: ScheduleReconciliationOptions,
) => Promise<ScheduleReconciliationResult>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L146)

### reconcileNativeSchedulesEffect

Reconciles owned schedules with ordered native writes in Effect.

**Example**

```ts
Effect.runPromise(
  Effect.provide(reconcileNativeSchedulesEffect(options), nativeScheduleLayer(native)),
);
```

**Signature**

```ts
declare const reconcileNativeSchedulesEffect: (
  options: Omit<ScheduleReconciliationOptions, "native">,
) => Effect.Effect<
  Readonly<{ upserted: Array<string>; deleted: Array<string>; preserved: Array<string> }>,
  ScheduleReconciliationFailure,
  NativeScheduleService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L43)

### scheduleOperationId

**Signature**

```ts
declare const scheduleOperationId: (
  options: Pick<ScheduleReconciliationOptions, "context" | "jobId" | "buildId">,
  scheduleId: string,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L35)

### scheduleOperationIdEffect

**Signature**

```ts
declare const scheduleOperationIdEffect: (
  options: Pick<ScheduleReconciliationOptions, "jobId" | "context" | "buildId">,
  scheduleId: string,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L36)

### scheduleOwner

**Signature**

```ts
declare const scheduleOwner: (
  options: Pick<ScheduleReconciliationOptions, "context" | "jobId">,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L33)

### scheduleOwnerEffect

**Signature**

```ts
declare const scheduleOwnerEffect: (
  options: Pick<ScheduleReconciliationOptions, "jobId" | "context">,
) => Effect.Effect<string, JobIdentityError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.ts#L34)

## `schedule-reconciliation.types.ts`

### NativeOwnedScheduleRecord (interface)

Native schedule visible to reconciliation, including ownership metadata.

**Signature**

```ts
export interface NativeOwnedScheduleRecord {
  readonly id: string;
  readonly state?: "active" | "paused" | "missing" | "unknown";
  readonly definition?: ScheduleDefinition;
  readonly metadata?: Readonly<Record<string, unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.types.ts#L4)

### ScheduleReconciliationOptions (interface)

Existing Promise API options, including the native provider.

**Signature**

```ts
export interface ScheduleReconciliationOptions {
  readonly native: NativeScheduleOperations;
  readonly desired: readonly ScheduleDefinition[];
  readonly existing?: readonly NativeOwnedScheduleRecord[];
  readonly context: OperationContext;
  readonly jobId: string;
  readonly taskId?: string;
  readonly taskVersion?: string;
  readonly buildId: string;
  readonly workerReady?: (() => Promise<void>) | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.types.ts#L17)

### ScheduleReconciliationResult (interface)

Ordered changes made by a reconciliation pass.

**Signature**

```ts
export interface ScheduleReconciliationResult {
  readonly upserted: readonly string[];
  readonly deleted: readonly string[];
  readonly preserved: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-reconciliation.types.ts#L11)

## `schedule-validation.ts`

### ScheduleValidationError (class)

Invalid authored schedule definitions.

**Example**

```ts
if (error instanceof ScheduleValidationError) console.log(error.message);
```

**Signature**

```ts
declare class ScheduleValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-validation.ts#L12)

### ScheduleValidationOptions

**Signature**

```ts
declare const ScheduleValidationOptions: ScheduleValidationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-validation.ts#L8)

### copySchedules

Synchronous schedule validation adapter.

**Throws**

TypeError when a schedule is invalid.

**Example**

```ts
copySchedules([{ id: "hourly", every: "1 hour", input: null }]);
```

**Signature**

```ts
declare const copySchedules: <CanonicalInput>(
  value: unknown,
  options?: ScheduleValidationOptions,
) => readonly ScheduleDefinition<CanonicalInput>[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-validation.ts#L42)

### copySchedulesEffect

Copies and validates authored schedules in Effect.

**Example**

```ts
Effect.runSync(copySchedulesEffect([{ id: "hourly", every: "1 hour", input: null }]));
```

**Signature**

```ts
declare const copySchedulesEffect: <CanonicalInput>(
  value: unknown,
  options?: ScheduleValidationOptions | undefined,
) => Effect.Effect<
  ReadonlyArray<ScheduleDefinition<CanonicalInput>> | undefined,
  ScheduleValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-validation.ts#L22)

## `schedule-validation.types.ts`

### ScheduleValidationOptions (interface)

Schemas used to validate and canonicalize authored schedule input.

**Signature**

```ts
export interface ScheduleValidationOptions {
  readonly callerSchema?: StandardSchemaV1;
  readonly canonicalSchema?: StandardSchemaV1;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule-validation.types.ts#L3)

## `schedule.types.ts`

### JobScheduleClient (interface)

Read and write operations available for a job's schedules.

**Signature**

```ts
export interface JobScheduleClient<Definition = ScheduleDefinition> {
  readonly list: (options?: ScheduleListOptions) => Promise<ScheduleReadReceipt<Definition>>;
  readonly get: (
    id: string,
    options?: { readonly signal?: AbortSignal },
  ) => Promise<ScheduleReadReceipt<Definition>>;
  readonly upsert: (
    definition: Definition,
    options: ScheduleWriteOptions,
  ) => Promise<ScheduleWriteReceipt<Definition>>;
  readonly pause: (
    id: string,
    options: ScheduleWriteOptions,
  ) => Promise<ScheduleWriteReceipt<Definition>>;
  readonly resume: (
    id: string,
    options: ScheduleWriteOptions,
  ) => Promise<ScheduleWriteReceipt<Definition>>;
  readonly delete: (
    id: string,
    options: ScheduleWriteOptions,
  ) => Promise<ScheduleWriteReceipt<Definition>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L67)

### ScheduleDefinition (type alias)

Authored schedule target, timing, and admission policy.

**Signature**

```ts
type ScheduleDefinition<Input = unknown> = {
  readonly id: string;
  readonly input: Input;
  readonly overlap?: ScheduleOverlap;
  readonly misfire?: ScheduleMisfire;
} & (
  | { readonly cron: string; readonly timezone: string; readonly every?: never }
  | { readonly every: DurationInput; readonly cron?: never; readonly timezone?: never }
);
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L10)

### ScheduleListOptions (interface)

Options accepted for schedule list operations.

**Signature**

```ts
export interface ScheduleListOptions {
  readonly limit?: number;
  readonly cursor?: string;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L44)

### ScheduleMisfire (type alias)

How missed occurrences are handled after downtime.

**Signature**

```ts
type ScheduleMisfire = "skip" | "latest" | "all";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L7)

### ScheduleOverlap (type alias)

Whether simultaneous occurrences are skipped or allowed.

**Signature**

```ts
type ScheduleOverlap = "allow" | "skip";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L5)

### ScheduleReadReceipt (interface)

Receipt returned after a schedule read operation.

**Signature**

```ts
export interface ScheduleReadReceipt<Definition = ScheduleDefinition> {
  readonly outcome: "available" | "unavailable";
  readonly schedule?: ScheduleRecord<Definition>;
  readonly schedules?: readonly ScheduleRecord<Definition>[];
  readonly nextCursor?: string;
  readonly hasMore?: boolean;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L30)

### ScheduleRecord (interface)

Provider read model for a persisted schedule.

**Signature**

```ts
export interface ScheduleRecord<Definition = ScheduleDefinition> {
  readonly id: string;
  readonly jobId: string;
  readonly state: "active" | "paused" | "missing" | "unknown";
  readonly definition: Definition;
  readonly observedAt?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L21)

### ScheduleWriteOptions (interface)

Options accepted for schedule write operations.

**Signature**

```ts
export interface ScheduleWriteOptions {
  readonly operationId: string;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L51)

### ScheduleWriteOutcome (type alias)

Result category for a native schedule mutation.

**Signature**

```ts
type ScheduleWriteOutcome =
  "created" | "updated" | "paused" | "resumed" | "deleted" | "requested" | "unsupported";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L40)

### ScheduleWriteReceipt (type alias)

Receipt returned after a schedule write operation.

**Signature**

```ts
type ScheduleWriteReceipt<Definition = ScheduleDefinition> =
  | {
      readonly operationId: string;
      readonly scheduleId: string;
      readonly outcome: ScheduleWriteOutcome;
      readonly schedule?: ScheduleRecord<Definition>;
    }
  | (JobUnknownOutcome & { readonly scheduleId: string });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/schedule.types.ts#L57)

## `server-manifest.ts`

### JobsManifestReader (class)

Substitutable manifest file reader.

**Example**

```ts
Effect.provide(readJobsManifestEffect(config), JobsManifestReaderLive);
```

**Signature**

```ts
declare class JobsManifestReader
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server-manifest.ts#L22)

### JobsManifestReaderLive

Live UTF-8 reader backed by Node's file system.

**Example**

```ts
Effect.provide(readJobsManifestEffect(config), JobsManifestReaderLive);
```

**Signature**

```ts
declare const JobsManifestReaderLive: Layer.Layer<JobsManifestReader, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server-manifest.ts#L30)

### JobsServerError (class)

A typed file, manifest, runtime, or callback failure.

**Example**

```ts
new JobsServerError({ operation: "readManifest", cause: new Error("missing") });
```

**Signature**

```ts
declare class JobsServerError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server-manifest.ts#L14)

### readJobsManifestEffect

Reads and validates the optional generated jobs manifest.

**Example**

```ts
Effect.provide(readJobsManifestEffect({ projectRoot: "." }), JobsManifestReaderLive);
```

**Signature**

```ts
declare const readJobsManifestEffect: (
  config: RunWithJobsConfig,
) => Effect.Effect<Readonly<JobsManifestLike> | undefined, JobsServerError, JobsManifestReader>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server-manifest.ts#L47)

## `server.ts`

### JobsManifestReader

**Signature**

```ts
declare const JobsManifestReader: typeof JobsManifestReader;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L14)

### JobsManifestReaderLive

**Signature**

```ts
declare const JobsManifestReaderLive: Layer<JobsManifestReader, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L14)

### JobsServerError

**Signature**

```ts
declare const JobsServerError: typeof JobsServerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L14)

### RunResultOptions

**Signature**

```ts
declare const RunResultOptions: RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L100)

### RunWithJobsConfig

**Signature**

```ts
declare const RunWithJobsConfig: RunWithJobsConfig;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L13)

### ServerTriggerOptions

**Signature**

```ts
declare const ServerTriggerOptions: ServerTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L100)

### TriggerOptions

**Signature**

```ts
declare const TriggerOptions: TriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L100)

### runWithJobs

Promise compatibility adapter for server invocation.

**Throws**

The original manifest, runtime, callback, or close error.

**Example**

```ts
await runWithJobs({ projectRoot: "." }, () => "ok");
```

**Signature**

```ts
declare const runWithJobs: <A>(
  config: RunWithJobsConfig,
  callback: () => A | PromiseLike<A>,
) => Promise<Awaited<A>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L63)

### runWithJobsEffect

Runs a server callback inside an owned or borrowed jobs runtime.
An owned runtime closes after success, typed failure, or interruption.

**Example**

```ts
Effect.provide(
  runWithJobsEffect({ projectRoot: "." }, () => "ok"),
  JobsManifestReaderLive,
);
```

**Signature**

```ts
declare const runWithJobsEffect: <A>(
  config: RunWithJobsConfig,
  callback: () => A | PromiseLike<A>,
) => Effect.Effect<A, JobsServerError, JobsManifestReader>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.ts#L23)

## `server.types.ts`

### JobsManifestLike

**Signature**

```ts
declare const JobsManifestLike: JobsManifestLike;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.types.ts#L5)

### JobsManifestReaderService (interface)

Injectable file reader for manifest loading.

**Example**

```ts
const reader: JobsManifestReaderService = { read: () => Effect.succeed("{}") };
```

**Signature**

```ts
export interface JobsManifestReaderService {
  /** Reads UTF-8 manifest data.
   * @param path - Resolved manifest path.
   * @returns File contents or JobsServerError.
   * @example reader.read("/project/.relkit/generated/jobs.manifest.json");
   */
  readonly read: (path: string) => Effect.Effect<string, JobsServerError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.types.ts#L31)

### JobsRuntimeOptions

**Signature**

```ts
declare const JobsRuntimeOptions: JobsRuntimeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.types.ts#L5)

### RunWithJobsConfig (interface)

Options for a server invocation with a jobs runtime.
The caller retains ownership when runtime is supplied.

**Example**

```ts
const config: RunWithJobsConfig = { projectRoot: process.cwd() };
```

**Signature**

```ts
export interface RunWithJobsConfig {
  readonly projectRoot: string;
  readonly environment?: string;
  readonly manifestPath?: string;
  readonly runtime?: JobsRuntime;
  readonly adapter?: unknown;
  readonly provider?: unknown;
  readonly providerHandle?: { readonly value: unknown };
  readonly application?: string;
  readonly scope?: string;
  readonly service?: string;
  readonly serviceGeneration?: string;
  readonly capabilities?: JobsRuntimeOptions["capabilities"];
  readonly jobs?: JobsRuntimeOptions["jobs"];
  readonly taskExecutor?: JobsRuntimeOptions["taskExecutor"];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/server.types.ts#L11)

## `service-options-validation.ts`

### JobsServiceOptionsError (class)

Invalid authored jobs service options.

**Example**

```ts
if (error instanceof JobsServiceOptionsError) console.log(error.message);
```

**Signature**

```ts
declare class JobsServiceOptionsError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options-validation.ts#L15)

### validateJobsServiceOptions

Synchronously validates jobs service options.

**Throws**

TypeError when any option is invalid.

**Example**

```ts
validateJobsServiceOptions({});
```

**Signature**

```ts
declare const validateJobsServiceOptions: (value: JobsServiceOptions | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options-validation.ts#L43)

### validateJobsServiceOptionsEffect

Validates jobs service limits, durations, and worker classes in Effect.

**Example**

```ts
Effect.runSync(validateJobsServiceOptionsEffect({}));
```

**Signature**

```ts
declare const validateJobsServiceOptionsEffect: (
  value: JobsServiceOptions | undefined,
) => Effect.Effect<void, JobsServiceOptionsError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options-validation.ts#L24)

## `service-options.ts`

### JobsServiceBehavior

**Signature**

```ts
declare const JobsServiceBehavior: Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L11)

### JobsServiceOptionName

**Signature**

```ts
declare const JobsServiceOptionName: JobsServiceOptionName;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L12)

### JobsServiceOptions

**Signature**

```ts
declare const JobsServiceOptions: JobsServiceOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L10)

### JobsServiceOptionsError

**Signature**

```ts
declare const JobsServiceOptionsError: typeof JobsServiceOptionsError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L17)

### assertSupportedJobsServiceOptions

Synchronously checks a provider's supported option names.

**Throws**

Error with the unsupported option name.

**Example**

```ts
assertSupportedJobsServiceOptions({}, []);
```

**Signature**

```ts
declare const assertSupportedJobsServiceOptions: (
  value: JobsServiceOptions,
  supported: readonly JobsServiceOptionName[],
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L132)

### assertSupportedJobsServiceOptionsEffect

Checks a provider's supported service option names in Effect.

**Example**

```ts
Effect.runSync(assertSupportedJobsServiceOptionsEffect({}, []));
```

**Signature**

```ts
declare const assertSupportedJobsServiceOptionsEffect: (
  value: JobsServiceOptions,
  supported: ReadonlyArray<JobsServiceOptionName>,
) => Effect.Effect<undefined, JobsServiceOptionsError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L106)

### deserializeJobsServiceOptions

Synchronously reads common options from stored service behavior.

**Throws**

TypeError when the record or an option is invalid.

**Example**

```ts
deserializeJobsServiceOptions({});
```

**Signature**

```ts
declare const deserializeJobsServiceOptions: (value: unknown) => JobsServiceOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L95)

### deserializeJobsServiceOptionsEffect

Parses common options from a stored service behavior record.

**Example**

```ts
Effect.runSync(deserializeJobsServiceOptionsEffect({}));
```

**Signature**

```ts
declare const deserializeJobsServiceOptionsEffect: (
  value: unknown,
) => Effect.Effect<Readonly<JobsServiceOptions>, JobsServiceOptionsError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L75)

### serializeJobsServiceOptions

Synchronously serializes service options.

**Throws**

TypeError when a field is not JSON.

**Example**

```ts
serializeJobsServiceOptions({}, undefined);
```

**Signature**

```ts
declare const serializeJobsServiceOptions: (
  value: JobsServiceOptions | undefined,
  native: JsonValue | undefined,
) => Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L45)

### serializeJobsServiceOptionsEffect

Serializes validated service options into a provider neutral record.

**Example**

```ts
Effect.runSync(serializeJobsServiceOptionsEffect({}, undefined));
```

**Signature**

```ts
declare const serializeJobsServiceOptionsEffect: (
  value: JobsServiceOptions | undefined,
  native: JsonValue | undefined,
) => Effect.Effect<Readonly<Record<string, JsonValue>>, JobsServiceOptionsError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L25)

### validateJobsServiceOptions

**Signature**

```ts
declare const validateJobsServiceOptions: (value: JobsServiceOptions | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L15)

### validateJobsServiceOptionsEffect

**Signature**

```ts
declare const validateJobsServiceOptionsEffect: (
  value: JobsServiceOptions | undefined,
) => Effect.Effect<void, JobsServiceOptionsError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.ts#L16)

## `service-options.types.ts`

### JobsServiceBehavior (type alias)

JSON configuration passed to a jobs service provider.

**Signature**

```ts
type JobsServiceBehavior = Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.types.ts#L28)

### JobsServiceOptionName (type alias)

Recognized top-level jobs service configuration keys.

**Signature**

```ts
type JobsServiceOptionName =
  "limits" | "workers" | "observation" | "maxElapsed" | "hookTimeout" | "shutdownGrace";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.types.ts#L30)

### JobsServiceOptions (interface)

Options accepted for jobs service operations.

**Signature**

```ts
export interface JobsServiceOptions {
  readonly limits?: {
    readonly inputBytes?: number;
    readonly outputBytes?: number;
    readonly progressItemBytes?: number;
    readonly streamItemBytes?: number;
  };
  readonly workers?: {
    readonly classes: readonly {
      readonly id: string;
      readonly cpu: number;
      readonly memory: MemoryInput;
      readonly nativeClass?: string;
    }[];
  };
  readonly observation?: {
    readonly pollInterval?: DurationInput;
    readonly readTimeout?: DurationInput;
  };
  readonly maxElapsed?: DurationInput;
  readonly hookTimeout?: DurationInput;
  readonly shutdownGrace?: DurationInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/service-options.types.ts#L4)

## `submission-admission.ts`

### AdmissionIdentity (class)

Substitutable operation ID generator for admitted submissions.

**Example**

```ts
const service = yield * AdmissionIdentity;
```

**Signature**

```ts
declare class AdmissionIdentity
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-admission.ts#L24)

### admissionIdentityLayer

Provides deterministic admission operation IDs.

**Example**

```ts
admissionIdentityLayer(() => "operation-1");
```

**Signature**

```ts
declare const admissionIdentityLayer: (
  next: () => string,
) => Layer.Layer<AdmissionIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-admission.ts#L33)

### boundedKey

**Signature**

```ts
declare const boundedKey: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-admission.ts#L161)

### prepareAdmission

Promise compatibility admission preparation.

**Throws**

Original binding, validation, or hashing error.

**Example**

```ts
await prepareAdmission(runtime, task, wire, copied);
```

**Signature**

```ts
declare const prepareAdmission: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  wire: JobWireEnvelope,
  copied: ReturnType<typeof copyTriggerOptions>,
  job?: JobDescriptorAny,
) => Promise<SubmissionAdmission>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-admission.ts#L141)

### prepareAdmissionEffect

Prepares binding, identity, scheduling, and input hash in Effect.

**Example**

```ts
Effect.runPromise(prepareAdmissionEffect(runtime, task, wire, copied));
```

**Signature**

```ts
declare const prepareAdmissionEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  wire: JobWireEnvelope,
  copied: CopiedTriggerOptions,
  job?: JobDescriptorAny | undefined,
) => Effect.Effect<
  Readonly<{
    binding: JobsRuntimeBinding;
    input: JsonValue;
    canonicalInput: JsonValue | undefined;
    inputHash: string;
    metadata: TaskSubmissionMetadata;
    job?: JobDescriptorAny;
    task: TaskDescriptorAny;
  }>,
  JobSubmissionPipelineFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-admission.ts#L44)

## `submission-canonical.ts`

### submitCanonicalTask

Promise compatibility adapter for canonical submission.

**Throws**

The original validation, cancellation, or provider error.

**Example**

```ts
await submitCanonicalTask(runtime, task, options);
```

**Signature**

```ts
declare const submitCanonicalTask: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  options: CanonicalTaskSubmissionOptions,
) => Promise<import("@relkit/contracts/jobs").RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-canonical.ts#L39)

### submitCanonicalTaskEffect

Submits an already canonical task input in Effect.

**Example**

```ts
Effect.runPromise(submitCanonicalTaskEffect(runtime, task, options));
```

**Signature**

```ts
declare const submitCanonicalTaskEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  options: CanonicalTaskSubmissionOptions,
) => Effect.Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-canonical.ts#L27)

## `submission-errors.ts`

### JobReceiptError (class)

A native accepted receipt failed durable identity validation.

**Example**

```ts
new JobReceiptError("Receipt is missing run ID");
```

**Signature**

```ts
declare class JobReceiptError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L36)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_RECEIPT_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L37)

### JobSubmissionCancelledError (class)

Caller cancellation happened before native acceptance began.

**Example**

```ts
new JobSubmissionCancelledError();
```

**Signature**

```ts
declare class JobSubmissionCancelledError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L24)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_SUBMISSION_CANCELLED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L25)

### JobSubmissionError (class)

A canonical job submission could not be accepted.

**Example**

```ts
new JobSubmissionError("Input hash mismatch");
```

**Signature**

```ts
declare class JobSubmissionError { constructor(
    message: string,
    readonly cause?: unknown,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L6)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_SUBMISSION_FAILED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L7)

### JobSubmissionUnknownError (class)

Native acceptance may have committed and needs idempotent recovery.

**Example**

```ts
new JobSubmissionUnknownError("submit-1", "same-key");
```

**Signature**

```ts
declare class JobSubmissionUnknownError { constructor(
    readonly operationId: string,
    readonly idempotencyKey: string | undefined,
    recovery: JobUnknownOutcome["recovery"] = { action: "inspect-native" },
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L49)

### toJSON (method)

Serializes the bounded recovery contract for callers.

**Example**

```ts
error.toJSON();
```

**Signature**

```ts
declare const toJSON: () => JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L74)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_SUBMISSION_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L50)

### outcome (property)

**Signature**

```ts
readonly outcome: "unknown"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L51)

### recovery (property)

**Signature**

```ts
readonly recovery: { readonly action: "retry-with-same-key" | "inspect-native" | "unavailable"; readonly expiresAt?: string; }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-errors.ts#L52)

## `submission-failure.ts`

### JobSubmissionPipelineFailure (class)

Expected failure at the jobs submission pipeline boundary.

**Example**

```ts
if (error instanceof JobSubmissionPipelineFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobSubmissionPipelineFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-failure.ts#L5)

## `submission-pipeline.ts`

### createSubmissionPipeline

Synchronous facade factory for the jobs submission pipeline.

**Example**

```ts
createSubmissionPipeline(runtime);
```

**Signature**

```ts
declare const createSubmissionPipeline: (runtime: JobsRuntime) => SubmissionPipeline;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L38)

### createSubmissionPipelineEffect

Builds a task and job submission facade in Effect.

**Example**

```ts
Effect.runSync(createSubmissionPipelineEffect(runtime));
```

**Signature**

```ts
declare const createSubmissionPipelineEffect: (
  runtime: JobsRuntime,
) => Effect.Effect<SubmissionPipeline, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L18)

### submitJob

Promise compatibility job submission.

**Throws**

The original capability, validation, cancellation, or provider error.

**Example**

```ts
await submitJob(job, "hello", {}, runtime);
```

**Signature**

```ts
declare const submitJob: (
  job: JobDescriptorAny,
  input: unknown,
  options?: unknown,
  runtime?: JobsRuntime,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L94)

### submitJobEffect

Submits an authored job in Effect.

**Example**

```ts
Effect.runPromise(submitJobEffect(job, "hello", {}, runtime));
```

**Signature**

```ts
declare const submitJobEffect: (
  job: JobDescriptorAny,
  input: unknown,
  options: unknown,
  runtime: JobsRuntime,
) => Effect.Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L78)

### submitTask

Promise compatibility task submission.

**Throws**

The original capability, validation, cancellation, or provider error.

**Example**

```ts
await submitTask(task, "hello", {}, runtime);
```

**Signature**

```ts
declare const submitTask: (
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  runtime?: JobsRuntime,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L62)

### submitTaskEffect

Submits an authored task in Effect.

**Example**

```ts
Effect.runPromise(submitTaskEffect(task, "hello", {}, runtime));
```

**Signature**

```ts
declare const submitTaskEffect: (
  task: TaskDescriptorAny,
  input: unknown,
  options: unknown,
  runtime: JobsRuntime,
) => Effect.Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-pipeline.ts#L49)

## `submission-prepare.ts`

### prepareCanonicalSubmission

Promise compatibility adapter for canonical admission.

**Throws**

The original trigger or preparation error.

**Example**

```ts
await prepareCanonicalSubmission(runtime, task, wire);
```

**Signature**

```ts
declare const prepareCanonicalSubmission: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  canonicalInput: ReturnType<typeof encodeJobWire>,
  options?: unknown,
  job?: JobDescriptorAny,
) => Promise<SubmissionAdmission>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepare.ts#L99)

### prepareCanonicalSubmissionEffect

Builds an admission from already canonical input in Effect.

**Example**

```ts
Effect.runPromise(prepareCanonicalSubmissionEffect(runtime, task, wire));
```

**Signature**

```ts
declare const prepareCanonicalSubmissionEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  canonicalInput: JobWireEnvelope,
  options?: unknown,
  job?: JobDescriptorAny | undefined,
) => Effect.Effect<
  Readonly<{
    binding: JobsRuntimeBinding;
    input: JsonValue;
    canonicalInput: JsonValue | undefined;
    inputHash: string;
    metadata: TaskSubmissionMetadata;
    job?: JobDescriptorAny;
    task: TaskDescriptorAny;
  }>,
  JobSubmissionPipelineFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepare.ts#L73)

### prepareSubmission

Promise compatibility adapter for authored input admission.

**Throws**

The original validation or preparation error.

**Example**

```ts
await prepareSubmission(runtime, task, "hello");
```

**Signature**

```ts
declare const prepareSubmission: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  job?: JobDescriptorAny,
) => Promise<SubmissionAdmission>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepare.ts#L51)

### prepareSubmissionEffect

Validates authored input and builds a durable admission in Effect.

**Example**

```ts
Effect.runPromise(prepareSubmissionEffect(runtime, task, "hello"));
```

**Signature**

```ts
declare const prepareSubmissionEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  job?: JobDescriptorAny | undefined,
) => Effect.Effect<
  Readonly<{
    binding: JobsRuntimeBinding;
    input: JsonValue;
    canonicalInput: JsonValue | undefined;
    inputHash: string;
    metadata: TaskSubmissionMetadata;
    job?: JobDescriptorAny;
    task: TaskDescriptorAny;
  }>,
  JobSubmissionPipelineFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepare.ts#L21)

## `submission-prepared.ts`

### submitPreparedSubmission

Promise compatibility prepared submission.

**Throws**

Original capability, cancellation, or provider error.

**Example**

```ts
await submitPreparedSubmission(runtime, admission);
```

**Signature**

```ts
declare const submitPreparedSubmission: (
  runtime: JobsRuntime,
  admission: SubmissionAdmission,
  signal?: AbortSignal,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepared.ts#L56)

### submitPreparedSubmissionEffect

Submits prepared canonical input in Effect.

**Example**

```ts
Effect.runPromise(submitPreparedSubmissionEffect(runtime, admission));
```

**Signature**

```ts
declare const submitPreparedSubmissionEffect: (
  runtime: JobsRuntime,
  admission: SubmissionAdmission,
  signal?: any,
) => Effect.Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-prepared.ts#L19)

## `submission-support-hash.ts`

### SubmissionDigest (class)

Substitutable SHA-256 digest provider for canonical submission input.

**Example**

```ts
const service = yield * SubmissionDigest;
```

**Signature**

```ts
declare class SubmissionDigest
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-hash.ts#L8)

### hashWire

Promise compatibility canonical wire hasher.

**Throws**

Original canonical JSON or digest error.

**Example**

```ts
await hashWire({ version: 1, kind: "void" });
```

**Signature**

```ts
declare const hashWire: (value: unknown) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-hash.ts#L52)

### hashWireEffect

Hashes a canonical wire envelope in Effect.

**Example**

```ts
Effect.runPromise(hashWireEffect({ version: 1, kind: "void" }));
```

**Signature**

```ts
declare const hashWireEffect: (
  value: unknown,
) => Effect.Effect<string, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-hash.ts#L26)

### submissionDigestLayer

Provides a deterministic SHA-256 digest implementation.

**Example**

```ts
submissionDigestLayer(async () => new ArrayBuffer(32));
```

**Signature**

```ts
declare const submissionDigestLayer: (
  digest: (bytes: Uint8Array) => Promise<ArrayBuffer>,
) => Layer.Layer<SubmissionDigest, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-hash.ts#L19)

## `submission-support-identity.ts`

### boundedKey

Synchronous bounded idempotency key.

**Throws**

TypeError when over 256 UTF-8 bytes.

**Example**

```ts
boundedKey("order-1");
```

**Signature**

```ts
declare const boundedKey: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L57)

### boundedKeyEffect

Checks an idempotency key's encoded byte limit in Effect.

**Example**

```ts
Effect.runSync(boundedKeyEffect("order-1"));
```

**Signature**

```ts
declare const boundedKeyEffect: (
  value: string,
) => Effect.Effect<string, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L48)

### currentCorrelation

Synchronous request correlation reader.

**Example**

```ts
currentCorrelation();
```

**Signature**

```ts
declare const currentCorrelation: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L91)

### currentCorrelationEffect

Reads request correlation from the invocation scope in Effect.

**Example**

```ts
Effect.runSync(currentCorrelationEffect());
```

**Signature**

```ts
declare const currentCorrelationEffect: () => Effect.Effect<
  string | undefined,
  SubmissionSupportFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L84)

### currentTaskRunId

Synchronous current parent task run id reader.

**Example**

```ts
currentTaskRunId();
```

**Signature**

```ts
declare const currentTaskRunId: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L122)

### currentTaskRunIdEffect

Reads the current parent task run id in Effect.

**Example**

```ts
Effect.runSync(currentTaskRunIdEffect());
```

**Signature**

```ts
declare const currentTaskRunIdEffect: () => Effect.Effect<
  string | undefined,
  SubmissionSupportFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L115)

### explicitOrDerivedKey

Synchronous idempotency key resolver.

**Throws**

TypeError for a mismatched or invalid scalar key.

**Example**

```ts
explicitOrDerivedKey(job, options, input);
```

**Signature**

```ts
declare const explicitOrDerivedKey: (
  job: { readonly admission?: { readonly idempotency?: { readonly key?: string } } } | undefined,
  options: CopiedTriggerOptions,
  input: JsonValue | undefined,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L36)

### explicitOrDerivedKeyEffect

Resolves an explicit or declared input idempotency key in Effect.

**Example**

```ts
Effect.runSync(explicitOrDerivedKeyEffect(job, options, input));
```

**Signature**

```ts
declare const explicitOrDerivedKeyEffect: (
  job: { readonly admission?: { readonly idempotency?: { readonly key?: string } } } | undefined,
  options: CopiedTriggerOptions,
  input: JsonValue | undefined,
) => Effect.Effect<string | undefined, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L20)

### propagationFor

Synchronous correlated trace propagation reader.

**Example**

```ts
propagationFor("request-1");
```

**Signature**

```ts
declare const propagationFor: (correlationId: string | undefined) => TracePropagation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L108)

### propagationForEffect

Extends trace propagation with request correlation in Effect.

**Example**

```ts
Effect.runSync(propagationForEffect("request-1"));
```

**Signature**

```ts
declare const propagationForEffect: (
  correlationId: string | undefined,
) => Effect.Effect<TracePropagation | undefined, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L99)

### scheduledTime

Synchronous absolute scheduled time calculator.

**Throws**

Original invalid duration error.

**Example**

```ts
scheduledTime(options, Date.now());
```

**Signature**

```ts
declare const scheduledTime: (options: CopiedTriggerOptions, now: number) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L77)

### scheduledTimeEffect

Calculates an absolute scheduled submission time in Effect.

**Example**

```ts
Effect.runSync(scheduledTimeEffect(options, Date.now()));
```

**Signature**

```ts
declare const scheduledTimeEffect: (
  options: CopiedTriggerOptions,
  now: number,
) => Effect.Effect<string | undefined, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-identity.ts#L66)

## `submission-support-receipts.ts`

### isRecord

Synchronous nonarray record guard.

**Example**

```ts
isRecord({ accepted: true });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L109)

### isSubmissionRecordEffect

Tests for a nonarray submission record in Effect.

**Example**

```ts
Effect.runSync(isSubmissionRecordEffect({ accepted: true }));
```

**Signature**

```ts
declare const isSubmissionRecordEffect: (
  value: unknown,
) => Effect.Effect<boolean, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L101)

### isUnknown

Synchronous uncertain submission type guard.

**Example**

```ts
if (isUnknown(response)) console.log(response.operationId);
```

**Signature**

```ts
declare const isUnknown: (value: unknown) => value is UnknownSubmissionOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L93)

### isUnknownSubmissionEffect

Tests an uncertain native submission outcome in Effect.

**Example**

```ts
Effect.runSync(isUnknownSubmissionEffect(response));
```

**Signature**

```ts
declare const isUnknownSubmissionEffect: (
  value: unknown,
) => Effect.Effect<boolean, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L85)

### normalizeReceipt

Synchronous accepted receipt normalizer.

**Throws**

JobReceiptError or JobSubmissionUnknownError for invalid outcomes.

**Example**

```ts
normalizeReceipt(receipt, binding, metadata);
```

**Signature**

```ts
declare const normalizeReceipt: (
  value: NativeReceipt | unknown,
  binding: JobsRuntimeBinding,
  metadata: TaskSubmissionMetadata,
) => RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L56)

### normalizeReceiptEffect

Validates a native accepted receipt in Effect.

**Example**

```ts
Effect.runSync(normalizeReceiptEffect(receipt, binding, metadata));
```

**Signature**

```ts
declare const normalizeReceiptEffect: (
  value: unknown,
  binding: JobsRuntimeBinding,
  metadata: TaskSubmissionMetadata,
) => Effect.Effect<RunHandle, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L42)

### normalizeSubmissionError

Synchronous provider error normalizer.

**Throws**

Original constructor defect when normalization fails.

**Example**

```ts
normalizeSubmissionError(cause, metadata);
```

**Signature**

```ts
declare const normalizeSubmissionError: (cause: unknown, metadata: TaskSubmissionMetadata) => Error;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L32)

### normalizeSubmissionErrorEffect

Normalizes an uncertain provider error in Effect.

**Example**

```ts
Effect.runSync(normalizeSubmissionErrorEffect(cause, metadata));
```

**Signature**

```ts
declare const normalizeSubmissionErrorEffect: (
  cause: unknown,
  metadata: TaskSubmissionMetadata,
) => Effect.Effect<Error, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L21)

### validatedEnvelope

Synchronous canonical envelope rebuilder.

**Example**

```ts
validatedEnvelope(admission);
```

**Signature**

```ts
declare const validatedEnvelope: (
  admission: SubmissionAdmission,
) => { version: 1; kind: "void"; value?: never } | { version: 1; kind: "json"; value: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L77)

### validatedEnvelopeEffect

Rebuilds a validated canonical envelope in Effect.

**Example**

```ts
Effect.runSync(validatedEnvelopeEffect(admission));
```

**Signature**

```ts
declare const validatedEnvelopeEffect: (
  admission: SubmissionAdmission,
) => Effect.Effect<
  { version: 1; kind: "void"; value?: never } | { version: 1; kind: "json"; value: JsonValue },
  SubmissionSupportFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-receipts.ts#L68)

## `submission-support-run.ts`

### SubmissionSupportFailure (class)

Expected submission helper failure with its original cause.

**Example**

```ts
if (error instanceof SubmissionSupportFailure) console.log(error.message);
```

**Signature**

```ts
declare class SubmissionSupportFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-run.ts#L7)

### runSubmissionSupport

Synchronous submission helper compatibility runner.

**Throws**

The original helper error on failure.

**Example**

```ts
runSubmissionSupport(submissionSupportEffect("submission.prepare", () => receipt));
```

**Signature**

```ts
declare const runSubmissionSupport: <A>(effect: Effect.Effect<A, SubmissionSupportFailure>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-run.ts#L32)

### submissionSupportEffect

Runs a submission helper inside an observed Effect.

**Example**

```ts
submissionSupportEffect("submission.prepare", () => receipt);
```

**Signature**

```ts
declare const submissionSupportEffect: <A>(
  operation: JobsOperation,
  compute: () => A,
) => Effect.Effect<A, SubmissionSupportFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-run.ts#L17)

## `submission-support-value-context.ts`

### currentCorrelation

Reads the parent invocation's correlation identity.

**Example**

```ts
currentCorrelation();
```

**Signature**

```ts
declare const currentCorrelation: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value-context.ts#L12)

### currentTaskRunId

Reads the current parent task run from invocation ancestry.

**Example**

```ts
currentTaskRunId();
```

**Signature**

```ts
declare const currentTaskRunId: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value-context.ts#L34)

### propagationFor

Extends current trace propagation with an optional correlation identity.

**Example**

```ts
propagationFor("request-1");
```

**Signature**

```ts
declare const propagationFor: (correlationId: string | undefined) => TracePropagation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value-context.ts#L23)

## `submission-support-value.ts`

### boundedKey

Checks the 256-byte idempotency key limit.

**Throws**

TypeError for oversized keys.

**Example**

```ts
boundedKey("order-1");
```

**Signature**

```ts
declare const boundedKey: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L127)

### currentCorrelation

**Signature**

```ts
declare const currentCorrelation: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L16)

### currentTaskRunId

**Signature**

```ts
declare const currentTaskRunId: () => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L18)

### explicitOrDerivedKey

Resolves explicit or input-derived idempotency and checks agreement.

**Throws**

TypeError for mismatched or nonscalar keys.

**Example**

```ts
explicitOrDerivedKey(job, options, { orderId: "one" });
```

**Signature**

```ts
declare const explicitOrDerivedKey: (
  job: { readonly admission?: { readonly idempotency?: { readonly key?: string } } } | undefined,
  options: CopiedTriggerOptions,
  input: JsonValue | undefined,
) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L92)

### isRecord

Tests for a nonarray provider record.

**Example**

```ts
isRecord({ accepted: true });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L175)

### isUnknown

Recognizes a native unknown submission response with recovery data.

**Example**

```ts
isUnknown(response);
```

**Signature**

```ts
declare const isUnknown: (value: unknown) => value is UnknownSubmissionOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L159)

### normalizeReceipt

Validates that native acceptance matches the pinned task and job binding.

**Throws**

JobReceiptError or JobSubmissionUnknownError for invalid outcomes.

**Example**

```ts
normalizeReceipt(receipt, binding, metadata);
```

**Signature**

```ts
declare const normalizeReceipt: (
  value: NativeReceipt | unknown,
  binding: JobsRuntimeBinding,
  metadata: TaskSubmissionMetadata,
) => RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L45)

### normalizeSubmissionError

Normalizes provider rejection and uncertain acceptance into public errors.

**Example**

```ts
normalizeSubmissionError(cause, metadata);
```

**Signature**

```ts
declare const normalizeSubmissionError: (cause: unknown, metadata: TaskSubmissionMetadata) => Error;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L26)

### propagationFor

**Signature**

```ts
declare const propagationFor: (correlationId: string | undefined) => TracePropagation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L17)

### scheduledTime

Resolves a trigger's absolute time or delay against a supplied clock.

**Throws**

TypeError for an invalid duration.

**Example**

```ts
scheduledTime({ delay: "1 second" }, 0);
```

**Signature**

```ts
declare const scheduledTime: (options: CopiedTriggerOptions, now: number) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L139)

### validatedEnvelope

Rebuilds a canonical wire envelope from admitted input.

**Example**

```ts
validatedEnvelope(admission);
```

**Signature**

```ts
declare const validatedEnvelope: (
  admission: SubmissionAdmission,
) => { version: 1; kind: "void"; value?: never } | { version: 1; kind: "json"; value: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support-value.ts#L149)

## `submission-support.ts`

### "./submission-support-hash.js" (namespace export)

Re-exports all named exports from the "./submission-support-hash.js" module.

**Signature**

```ts
export * from "./submission-support-hash.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L3)

### "./submission-support-identity.js" (namespace export)

Re-exports all named exports from the "./submission-support-identity.js" module.

**Signature**

```ts
export * from "./submission-support-identity.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L2)

### "./submission-support-receipts.js" (namespace export)

Re-exports all named exports from the "./submission-support-receipts.js" module.

**Signature**

```ts
export * from "./submission-support-receipts.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L1)

### JobSubmissionWriteFailure

**Signature**

```ts
declare const JobSubmissionWriteFailure: typeof JobSubmissionWriteFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L9)

### SubmissionSupportFailure

**Signature**

```ts
declare const SubmissionSupportFailure: typeof SubmissionSupportFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L4)

### UnknownSubmissionOutcome

**Signature**

```ts
declare const UnknownSubmissionOutcome: UnknownSubmissionOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L5)

### submitAbortable

**Signature**

```ts
declare const submitAbortable: (
  adapter: JobsAdapterRuntime,
  request: Parameters<JobsAdapterRuntime["submit"]>[0],
  context: OperationContext,
  signal: AbortSignal,
  metadata: TaskSubmissionMetadata,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L7)

### submitAbortableEffect

**Signature**

```ts
declare const submitAbortableEffect: (
  adapter: JobsAdapterRuntime,
  request: NativeSubmission,
  context: OperationContext,
  signal: AbortSignal,
  metadata: TaskSubmissionMetadata,
) => Effect<NativeReceipt, JobSubmissionWriteFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.ts#L8)

## `submission-support.types.ts`

### UnknownSubmissionOutcome (type alias)

Submission response that requires recovery after an uncertain native write.

**Signature**

```ts
type UnknownSubmissionOutcome = JobUnknownOutcome & {
  readonly recovery: JobUnknownOutcome["recovery"];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-support.types.ts#L4)

## `submission-write.ts`

### JobSubmissionWriteFailure (class)

Cancelled, uncertain, or provider failed native submission.

**Example**

```ts
if (error instanceof JobSubmissionWriteFailure) console.log(error.message);
```

**Signature**

```ts
declare class JobSubmissionWriteFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-write.ts#L11)

### submitAbortable

Promise compatibility adapter for native submission.

**Throws**

The original cancellation, unknown outcome, or provider error.

**Example**

```ts
await submitAbortable(adapter, request, context, signal, metadata);
```

**Signature**

```ts
declare const submitAbortable: (
  adapter: JobsAdapterRuntime,
  request: Parameters<JobsAdapterRuntime["submit"]>[0],
  context: OperationContext,
  signal: AbortSignal,
  metadata: TaskSubmissionMetadata,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-write.ts#L84)

### submitAbortableEffect

Submits with an Effect owned abort listener and uncertain outcome semantics.

**Example**

```ts
Effect.runPromise(submitAbortableEffect(adapter, request, context, signal, metadata));
```

**Signature**

```ts
declare const submitAbortableEffect: (
  adapter: JobsAdapterRuntime,
  request: NativeSubmission,
  context: OperationContext,
  signal: AbortSignal,
  metadata: TaskSubmissionMetadata,
) => Effect.Effect<NativeReceipt, JobSubmissionWriteFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-write.ts#L24)

## `submission-write.types.ts`

Listener and abort state owned for one native submission.

### SubmissionWriteRegistration (interface)

Listener and abort state owned for one native submission.

**Signature**

```ts
export interface SubmissionWriteRegistration {
  readonly aborted: Promise<void>;
  readonly isAborted: () => boolean;
  readonly dispose: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission-write.types.ts#L2)

## `submission.ts`

### CanonicalTaskSubmissionOptions

**Signature**

```ts
declare const CanonicalTaskSubmissionOptions: CanonicalTaskSubmissionOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L2)

### JobReceiptError

**Signature**

```ts
declare const JobReceiptError: typeof JobReceiptError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L24)

### JobSubmissionCancelledError

**Signature**

```ts
declare const JobSubmissionCancelledError: typeof JobSubmissionCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L25)

### JobSubmissionError

**Signature**

```ts
declare const JobSubmissionError: typeof JobSubmissionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L26)

### JobSubmissionPipelineFailure

**Signature**

```ts
declare const JobSubmissionPipelineFailure: typeof JobSubmissionPipelineFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L29)

### JobSubmissionUnknownError

**Signature**

```ts
declare const JobSubmissionUnknownError: typeof JobSubmissionUnknownError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L27)

### SubmissionAdmission

**Signature**

```ts
declare const SubmissionAdmission: SubmissionAdmission;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L3)

### SubmissionPipeline

**Signature**

```ts
declare const SubmissionPipeline: SubmissionPipeline;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L4)

### TaskSubmissionMetadata

**Signature**

```ts
declare const TaskSubmissionMetadata: TaskSubmissionMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L5)

### createSubmissionPipeline

**Signature**

```ts
declare const createSubmissionPipeline: (runtime: JobsRuntime) => SubmissionPipeline;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L10)

### createSubmissionPipelineEffect

**Signature**

```ts
declare const createSubmissionPipelineEffect: (
  runtime: JobsRuntime,
) => Effect<SubmissionPipeline, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L11)

### prepareCanonicalSubmission

**Signature**

```ts
declare const prepareCanonicalSubmission: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  canonicalInput: ReturnType<typeof encodeJobWire>,
  options?: unknown,
  job?: JobDescriptorAny,
) => Promise<SubmissionAdmission>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L20)

### prepareCanonicalSubmissionEffect

**Signature**

```ts
declare const prepareCanonicalSubmissionEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  canonicalInput: JobWireEnvelope,
  options?: unknown,
  job?: JobDescriptorAny | undefined,
) => Effect<
  Readonly<{
    binding: JobsRuntimeBinding;
    input: JsonValue;
    canonicalInput: JsonValue | undefined;
    inputHash: string;
    metadata: TaskSubmissionMetadata;
    job?: JobDescriptorAny;
    task: TaskDescriptorAny;
  }>,
  JobSubmissionPipelineFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L21)

### prepareSubmission

**Signature**

```ts
declare const prepareSubmission: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  job?: JobDescriptorAny,
) => Promise<SubmissionAdmission>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L18)

### prepareSubmissionEffect

**Signature**

```ts
declare const prepareSubmissionEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  job?: JobDescriptorAny | undefined,
) => Effect<
  Readonly<{
    binding: JobsRuntimeBinding;
    input: JsonValue;
    canonicalInput: JsonValue | undefined;
    inputHash: string;
    metadata: TaskSubmissionMetadata;
    job?: JobDescriptorAny;
    task: TaskDescriptorAny;
  }>,
  JobSubmissionPipelineFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L19)

### submitCanonicalTask

**Signature**

```ts
declare const submitCanonicalTask: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  options: CanonicalTaskSubmissionOptions,
) => Promise<import("@relkit/contracts/jobs").RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L7)

### submitCanonicalTaskEffect

**Signature**

```ts
declare const submitCanonicalTaskEffect: (
  runtime: JobsRuntime,
  task: TaskDescriptorAny,
  options: CanonicalTaskSubmissionOptions,
) => Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L7)

### submitJob

**Signature**

```ts
declare const submitJob: (
  job: JobDescriptorAny,
  input: unknown,
  options?: unknown,
  runtime?: JobsRuntime,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L14)

### submitJobEffect

**Signature**

```ts
declare const submitJobEffect: (
  job: JobDescriptorAny,
  input: unknown,
  options: unknown,
  runtime: JobsRuntime,
) => Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L15)

### submitPreparedSubmission

**Signature**

```ts
declare const submitPreparedSubmission: (
  runtime: JobsRuntime,
  admission: SubmissionAdmission,
  signal?: AbortSignal,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L8)

### submitTask

**Signature**

```ts
declare const submitTask: (
  task: TaskDescriptorAny,
  input: unknown,
  options?: unknown,
  runtime?: JobsRuntime,
) => Promise<RunHandle>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L12)

### submitTaskEffect

**Signature**

```ts
declare const submitTaskEffect: (
  task: TaskDescriptorAny,
  input: unknown,
  options: unknown,
  runtime: JobsRuntime,
) => Effect<RunHandle, JobSubmissionPipelineFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.ts#L13)

## `submission.types.ts`

### CanonicalTaskSubmissionOptions (interface)

Options accepted for canonical task submission operations.

**Signature**

```ts
export interface CanonicalTaskSubmissionOptions {
  readonly canonicalInput: JobWireEnvelope;
  readonly operationId: string;
  readonly idempotencyKey?: string;
  readonly signal?: AbortSignal;
  readonly scheduledFor?: string;
  readonly occurrenceIdentity?: string;
  readonly acceptanceIdentity?: string;
  readonly retryOfRunId?: string;
  readonly inputHash?: string;
  readonly inputSchemaHash?: string;
  readonly job?: JobDescriptorAny;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.types.ts#L23)

### SubmissionAdmission (interface)

Prepared admission identity and timing for one submission.

**Signature**

```ts
export interface SubmissionAdmission {
  readonly task: TaskDescriptorAny;
  readonly job?: JobDescriptorAny;
  readonly binding: JobsRuntimeBinding;
  readonly input: JsonValue;
  readonly canonicalInput: JsonValue | undefined;
  readonly inputHash: string;
  readonly metadata: TaskSubmissionMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.types.ts#L38)

### SubmissionPipeline (interface)

Validated submission stages and their prepared values.

**Signature**

```ts
export interface SubmissionPipeline {
  readonly submitTask: (
    task: TaskDescriptorAny,
    input: unknown,
    options?: unknown,
  ) => Promise<RunHandle>;
  readonly submitJob: (
    job: JobDescriptorAny,
    input: unknown,
    options?: unknown,
  ) => Promise<RunHandle>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.types.ts#L49)

### TaskSubmissionMetadata (interface)

Task identity, build, and tracing facts sent with a submission.

**Signature**

```ts
export interface TaskSubmissionMetadata {
  readonly operationId: string;
  readonly idempotencyKey?: string;
  readonly scheduledFor?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
  readonly parentRunId?: string;
  readonly propagation?: TracePropagation;
  readonly acceptanceIdentity?: string;
  readonly occurrenceIdentity?: string;
  readonly inputSchemaHash?: string;
  readonly retryOfRunId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/submission.types.ts#L8)

## `task-client.types.ts`

### InputOf (type alias)

Caller input inferred from a task or job schema.

**Signature**

```ts
type InputOf<T> = T extends { readonly input: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferInput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-client.types.ts#L6)

### JobTriggerClients (type alias)

Named job trigger clients mapped from declared dependencies.

**Signature**

```ts
type JobTriggerClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: TaskJobClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-client.types.ts#L34)

### OutputOf (type alias)

Validated output inferred from a task or job schema.

**Signature**

```ts
type OutputOf<T> = T extends { readonly output: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferOutput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-client.types.ts#L13)

### TaskClientFor (type alias)

Typed trigger operation for one task reference.

**Signature**

```ts
type TaskClientFor<T> = {
  readonly trigger: (input: InputOf<T>, options?: ServerTriggerOptions) => Promise<RunHandle>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-client.types.ts#L20)

### TaskClients (type alias)

Named task trigger clients mapped from declared dependencies.

**Signature**

```ts
type TaskClients<M> = {
  readonly [Name in keyof NonNullable<M> & string]: TaskClientFor<NonNullable<M>[Name]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-client.types.ts#L25)

## `task-context-policy.types.ts`

### NormalizedTaskRetryPolicy (interface)

Fully populated retry policy used by the runtime.

**Signature**

```ts
export interface NormalizedTaskRetryPolicy {
  readonly maxAttempts: number;
  readonly initialDelay: DurationInput;
  readonly maxDelay: DurationInput;
  readonly factor: number;
  readonly jitter: "none" | "full";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L19)

### TaskAuthContext (interface)

Session lookup supplied to a task through its auth dependency.

**Signature**

```ts
export interface TaskAuthContext<Session = unknown> {
  readonly getSession: () => Promise<Session | null>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L5)

### TaskConcurrency (interface)

Limit and optional input key for task execution concurrency.

**Signature**

```ts
export interface TaskConcurrency<InputKey extends string = string> {
  readonly limit: number;
  readonly key?: InputKey;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L34)

### TaskResources (interface)

CPU and memory resources requested for task execution.

**Signature**

```ts
export interface TaskResources {
  readonly cpu: number;
  readonly memory: MemoryInput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L28)

### TaskRetryPolicy (interface)

Authoring policy for task retry attempts and backoff.

**Signature**

```ts
export interface TaskRetryPolicy {
  readonly maxAttempts: number;
  readonly initialDelay?: DurationInput;
  readonly maxDelay?: DurationInput;
  readonly factor?: number;
  readonly jitter?: "none" | "full";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L10)

### TaskSleepOptions (interface)

Stable sleep key used when a durable task suspends.

**Signature**

```ts
export interface TaskSleepOptions {
  readonly key: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-context-policy.types.ts#L40)

## `task-core.types.ts`

### DurationInput

**Signature**

```ts
declare const DurationInput:
  | `${number} second`
  | `${number} seconds`
  | `${number} minute`
  | `${number} minutes`
  | `${number} hour`
  | `${number} hours`
  | `${number} day`
  | `${number} days`
  | `${number} week`
  | `${number} weeks`
  | `${number} millisecond`
  | `${number} milliseconds`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L31)

### InputOf

**Signature**

```ts
declare const InputOf: InputOf<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L53)

### JobDescriptorForThisTask

**Signature**

```ts
declare const JobDescriptorForThisTask: JobDescriptorForThisTask<Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L24)

### JobTriggerClients

**Signature**

```ts
declare const JobTriggerClients: JobTriggerClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L54)

### MemoryInput (type alias)

Human-readable MiB or GiB memory quantity for task resources.

**Signature**

```ts
type MemoryInput = `${number} MiB` | `${number} GiB`;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L63)

### NormalizedTaskRetryPolicy

**Signature**

```ts
declare const NormalizedTaskRetryPolicy: NormalizedTaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L35)

### OutputOf

**Signature**

```ts
declare const OutputOf: OutputOf<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L55)

### PublishedEventName (type alias)

Event names registered for the application.

**Signature**

```ts
type PublishedEventName = Extract<keyof Relkit.EventRegistry, string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L65)

### RunResultOptions

**Signature**

```ts
declare const RunResultOptions: RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L25)

### ServerTriggerOptions

**Signature**

```ts
declare const ServerTriggerOptions: ServerTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L26)

### TaskAuthContext

**Signature**

```ts
declare const TaskAuthContext: TaskAuthContext<Session>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L33)

### TaskClientFor

**Signature**

```ts
declare const TaskClientFor: TaskClientFor<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L56)

### TaskClients

**Signature**

```ts
declare const TaskClients: TaskClients<M>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L57)

### TaskConcurrency

**Signature**

```ts
declare const TaskConcurrency: TaskConcurrency<InputKey>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L37)

### TaskContext (type alias)

Execution context assembled from the task's declared dependencies and capabilities.

**Signature**

```ts
type TaskContext<
  Execution extends TaskExecution = TaskExecution,
  Dependencies extends TaskDependencies = {},
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  Streams extends TaskStreamSchemas = {},
  Publishes extends readonly string[] = readonly [],
> = TaskContextBase<Dependencies, Publishes> &
  (Execution extends "durable"
    ? {
        readonly sleep: (duration: DurationInput, options: TaskSleepOptions) => Promise<void>;
        readonly sleepUntil: (instant: string, options: TaskSleepOptions) => Promise<void>;
      }
    : {}) &
  ([ProgressSchema] extends [StandardSchemaV1]
    ? { readonly progress: TaskProgressEmitter<InferInput<ProgressSchema>> }
    : {}) &
  ([keyof Streams] extends [never] ? {} : { readonly streams: TaskStreamEmitters<Streams> });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L131)

### TaskContextBase (interface)

Common invocation context shared by task handlers and hooks.

**Signature**

```ts
export interface TaskContextBase<
  Dependencies extends TaskDependencies = {},
  Publishes extends readonly string[] = readonly [],
> {
  readonly run: TaskRunContext;
  readonly invocation: InvocationMetadata;
  readonly signal: AbortSignal;
  readonly env: ResolvedApplicationEnv;
  readonly log: PublicLogger;
  readonly trace: PublicTrace;
  readonly time: PublicClock;
  readonly tasks: TaskClients<Dependencies["tasks"]>;
  readonly jobs: JobTriggerClients<Dependencies["jobs"]>;
  readonly agents: AgentClients<Dependencies["agents"]>;
  readonly buckets: BucketClients<Dependencies["buckets"]>;
  readonly cache: CacheClients<Dependencies["cache"]>;
  readonly events: EventClients<PublishedEventMap<Publishes>>;
  readonly database: RegisteredContext<"database", Readonly<Record<string, never>>>;
  readonly auth: RegisteredContext<"auth", TaskAuthContext>;
  readonly constants: RegisteredContext<"constants", Readonly<Record<string, never>>>;
  readonly prompts: RegisteredContext<"prompts", Readonly<Record<string, never>>>;
  readonly idempotencyKey: (operation: string) => string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L103)

### TaskDependencies (interface)

Resources a task explicitly declares before it can be executed.

**Signature**

```ts
export interface TaskDependencies {
  readonly tasks?: Readonly<Record<string, TaskRefAny>>;
  readonly jobs?: Readonly<Record<string, JobRefAny>>;
  readonly agents?: Readonly<Record<string, AgentRefAny>>;
  readonly buckets?: Readonly<Record<string, BucketRefAny>>;
  readonly cache?: Readonly<Record<string, CacheRefAny>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L79)

### TaskExecution (type alias)

Whether a task uses durable or retryable execution.

**Signature**

```ts
type TaskExecution = "durable" | "retryable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L61)

### TaskHookContext (type alias)

Invocation context visible to task lifecycle hooks.

**Signature**

```ts
type TaskHookContext<
  Dependencies extends TaskDependencies = {},
  Publishes extends readonly string[] = readonly [],
> = TaskContextBase<Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L150)

### TaskProgressEmitter

**Signature**

```ts
declare const TaskProgressEmitter: TaskProgressEmitter<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L41)

### TaskProgressInput

**Signature**

```ts
declare const TaskProgressInput: TaskProgressInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L44)

### TaskProgressOutput

**Signature**

```ts
declare const TaskProgressOutput: TaskProgressOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L45)

### TaskResources

**Signature**

```ts
declare const TaskResources: TaskResources;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L36)

### TaskRetryPolicy

**Signature**

```ts
declare const TaskRetryPolicy: TaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L34)

### TaskRunContext (interface)

Stable run identity and attempt metadata available to a task.

**Signature**

```ts
export interface TaskRunContext {
  readonly runId: string;
  readonly jobId: string;
  readonly taskId: string;
  readonly taskVersion: string;
  readonly buildId: string;
  readonly service: string;
  readonly attempt: number;
  readonly acceptedAt: string;
  readonly scheduledFor?: string;
  readonly parentRunId?: string;
  readonly acceptanceIdentity?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L88)

### TaskSleepOptions

**Signature**

```ts
declare const TaskSleepOptions: TaskSleepOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L38)

### TaskStreamEmitter

**Signature**

```ts
declare const TaskStreamEmitter: TaskStreamEmitter<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L42)

### TaskStreamEmitters

**Signature**

```ts
declare const TaskStreamEmitters: TaskStreamEmitters<Streams>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L48)

### TaskStreamFrames

**Signature**

```ts
declare const TaskStreamFrames: TaskStreamFrames<Streams>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L49)

### TaskStreamInput

**Signature**

```ts
declare const TaskStreamInput: TaskStreamInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L46)

### TaskStreamItem

**Signature**

```ts
declare const TaskStreamItem: TaskStreamItem<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L43)

### TaskStreamOutput

**Signature**

```ts
declare const TaskStreamOutput: TaskStreamOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L47)

### TaskStreamSchemas (type alias)

Named item schemas used to validate task stream emissions.

**Signature**

```ts
type TaskStreamSchemas = Readonly<Record<string, StandardSchemaV1>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L128)

### TaskTriggerOptions

**Signature**

```ts
declare const TaskTriggerOptions: TaskTriggerOptions<Task>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L27)

### TriggerOptions

**Signature**

```ts
declare const TriggerOptions: TriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-core.types.ts#L28)

## `task-definition-inference.types.ts`

### TaskCallerInput (type alias)

Caller-facing input alias for a task reference.

**Signature**

```ts
type TaskCallerInput<T extends TaskRef> = TaskInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L18)

### TaskCanonicalInput (type alias)

Parsed canonical input inferred from a task's input schema.

**Signature**

```ts
type TaskCanonicalInput<T extends TaskRef> = T extends { readonly input: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferOutput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L20)

### TaskInput (type alias)

Caller input inferred from a task's input schema.

**Signature**

```ts
type TaskInput<T extends TaskRef> = T extends { readonly input: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferInput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L5)

### TaskOutput (type alias)

Validated output inferred from a task's output schema.

**Signature**

```ts
type TaskOutput<T extends TaskRef> = T extends { readonly output: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferOutput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L11)

### TaskRawHandlerOutput (type alias)

Handler return value accepted by a task's output schema.

**Signature**

```ts
type TaskRawHandlerOutput<T extends TaskRef> = T extends { readonly output: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferInput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L26)

### TaskValidatedOutput (type alias)

Output after validation through a task's output schema.

**Signature**

```ts
type TaskValidatedOutput<T extends TaskRef> = TaskOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-inference.types.ts#L32)

## `task-definition-support.types.ts`

### TaskFailureHook (type alias)

Hook invoked after task execution fails.

**Signature**

```ts
type TaskFailureHook<
  Dependencies extends TaskDependencies,
  Publishes extends readonly string[] = readonly [],
> = (error: unknown, context: TaskHookContext<Dependencies, Publishes>) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L52)

### TaskHandler (type alias)

Handler receives validated input and scoped context, then returns output or a declared failure.

**Signature**

```ts
type TaskHandler<
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Execution extends TaskExecution,
  Dependencies extends TaskDependencies,
  Errors extends readonly ErrorDescriptorAny[],
  ProgressSchema extends StandardSchemaV1 | undefined,
  Streams extends TaskStreamSchemas,
  Publishes extends readonly string[],
> = (
  input: InferOutput<InputSchema>,
  context: TaskContext<Execution, Dependencies, ProgressSchema, Streams, Publishes>,
) => MaybePromise<TaskHandlerResult<InferInput<OutputSchema>, Errors>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L13)

### TaskHandlerResult (type alias)

Allowed output and declared failure forms returned by a task handler.

**Signature**

```ts
type TaskHandlerResult<Output, Errors extends readonly ErrorDescriptorAny[]> =
  Output | DeclaredErrorsOf<Errors> | FunctionFailure<DeclaredErrorsOf<Errors>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L28)

### TaskLogging (interface)

Log level and fields to redact during task execution.

**Signature**

```ts
export interface TaskLogging {
  readonly level?: "trace" | "debug" | "info" | "warn" | "error";
  readonly redact?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L67)

### TaskObservation (interface)

Visibility settings for progress and named streams.

**Signature**

```ts
export interface TaskObservation<
  Streams extends TaskStreamSchemas = TaskStreamSchemas,
  ProgressSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,
> {
  readonly progress?: [ProgressSchema] extends [undefined] ? never : "live" | "durable";
  readonly streams?: Readonly<{ [Name in keyof Streams & string]?: "live" | "history" }>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L58)

### TaskStartHook (type alias)

Hook invoked before task execution begins.

**Signature**

```ts
type TaskStartHook<
  InputSchema extends StandardSchemaV1,
  Dependencies extends TaskDependencies,
  Publishes extends readonly string[] = readonly [],
> = (
  input: InferOutput<InputSchema>,
  context: TaskHookContext<Dependencies, Publishes>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L32)

### TaskSuccessHook (type alias)

Hook invoked after a task completes successfully.

**Signature**

```ts
type TaskSuccessHook<
  OutputSchema extends StandardSchemaV1,
  Dependencies extends TaskDependencies,
  Publishes extends readonly string[] = readonly [],
> = (
  output: InferOutput<OutputSchema>,
  context: TaskHookContext<Dependencies, Publishes>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition-support.types.ts#L42)

## `task-definition.types.ts`

### DefineTaskOptions (interface)

Authoring contract for task schemas, dependencies, hooks, and execution policy.

**Signature**

```ts
export interface DefineTaskOptions<
  Id extends string,
  Version extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Dependencies extends TaskDependencies = {},
  Errors extends readonly ErrorDescriptorAny[] = readonly [],
  Publishes extends readonly PublishedEventName[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  Streams extends TaskStreamSchemas = {},
  Execution extends TaskExecution = "durable",
> extends DescriptorMetadata {
  readonly id: Id;
  readonly version: Version;
  readonly input: InputSchema;
  readonly inputWire?: StandardSchemaV1<InferOutput<InputSchema>, InferOutput<InputSchema>>;
  readonly output: OutputSchema;
  readonly errors?: Errors;
  readonly execution?: Execution;
  readonly dependencies?: ValidTaskDependencies<Dependencies>;
  readonly publishes?: Publishes;
  readonly progress?: ProgressSchema;
  readonly streams?: Streams;
  readonly observation?: TaskObservation<Streams, ProgressSchema>;
  readonly retry?: TaskRetryPolicy;
  readonly resources?: TaskResources;
  readonly concurrency?: TaskConcurrency<CanonicalInputKey<InputSchema>>;
  readonly maxDuration?: DurationInput;
  readonly maxElapsed?: DurationInput;
  readonly logging?: TaskLogging;
  readonly onStart?: TaskStartHook<InputSchema, Dependencies, Publishes>;
  readonly onSuccess?: TaskSuccessHook<OutputSchema, Dependencies, Publishes>;
  readonly onFailure?: TaskFailureHook<Dependencies, Publishes>;
  readonly handler: TaskHandler<
    InputSchema,
    OutputSchema,
    Execution,
    Dependencies,
    Errors,
    ProgressSchema,
    Streams,
    Publishes
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L60)

### TaskCallerInput

**Signature**

```ts
declare const TaskCallerInput: TaskCallerInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L32)

### TaskCanonicalInput

**Signature**

```ts
declare const TaskCanonicalInput: TaskCanonicalInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L33)

### TaskDescriptor (interface)

Validated task definition with an attached trigger operation.

**Signature**

```ts
export interface TaskDescriptor<
  Id extends string,
  Version extends string,
  InputSchema extends StandardSchemaV1,
  OutputSchema extends StandardSchemaV1,
  Dependencies extends TaskDependencies = {},
  Errors extends readonly ErrorDescriptorAny[] = readonly [],
  Publishes extends readonly string[] = readonly [],
  ProgressSchema extends StandardSchemaV1 | undefined = undefined,
  Streams extends TaskStreamSchemas = {},
  Execution extends TaskExecution = TaskExecution,
>
  extends DescriptorBase<"task", Id>, TaskRef<Id, InputSchema, OutputSchema, Errors> {
  readonly version: Version;
  readonly execution: Execution;
  readonly inputWire?: StandardSchemaV1<InferOutput<InputSchema>, InferOutput<InputSchema>>;
  readonly dependencies?: Dependencies;
  readonly publishes?: Publishes;
  readonly progress?: ProgressSchema;
  readonly streams?: Streams;
  readonly observation?: TaskObservation<Streams, ProgressSchema>;
  readonly retry: NormalizedTaskRetryPolicy;
  readonly resources?: TaskResources;
  readonly concurrency?: TaskConcurrency<CanonicalInputKey<InputSchema>>;
  readonly maxDuration?: DurationInput;
  readonly maxElapsed?: DurationInput;
  readonly logging?: TaskLogging;
  readonly onStart?: TaskStartHook<InputSchema, Dependencies, Publishes>;
  readonly onSuccess?: TaskSuccessHook<OutputSchema, Dependencies, Publishes>;
  readonly onFailure?: TaskFailureHook<Dependencies, Publishes>;
  readonly handler: TaskHandler<
    InputSchema,
    OutputSchema,
    Execution,
    Dependencies,
    Errors,
    ProgressSchema,
    Streams,
    Publishes
  >;
  readonly trigger: (
    input: InferInput<InputSchema>,
    options?: TaskTriggerOptions<TaskRef<Id, InputSchema, OutputSchema, Errors>>,
  ) => Promise<RunHandle>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L106)

### TaskDescriptorAny (type alias)

Task descriptor widened for registry and runtime boundaries.

**Signature**

```ts
type TaskDescriptorAny = DescriptorBase<"task", string> &
  TaskRef<string, StandardSchemaV1, StandardSchemaV1, readonly ErrorDescriptorAny[]> & {
    readonly version: string;
    readonly execution: TaskExecution;
    readonly inputWire?: StandardSchemaV1 | undefined;
    readonly dependencies?: TaskDependencies | undefined;
    readonly publishes?: readonly string[] | undefined;
    readonly progress?: StandardSchemaV1 | undefined;
    readonly streams?: TaskStreamSchemas | undefined;
    readonly observation?: TaskObservation | undefined;
    readonly retry: NormalizedTaskRetryPolicy;
    readonly resources?: TaskResources | undefined;
    readonly concurrency?: TaskConcurrency | undefined;
    readonly maxDuration?: DurationInput | undefined;
    readonly maxElapsed?: DurationInput | undefined;
    readonly logging?: TaskLogging | undefined;
    readonly onStart?: (...args: never[]) => Promise<void>;
    readonly onSuccess?: (...args: never[]) => Promise<void>;
    readonly onFailure?: (...args: never[]) => Promise<void>;
    readonly handler: (...args: never[]) => unknown;
    readonly trigger: (...args: never[]) => Promise<RunHandle>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L153)

### TaskFailureHook

**Signature**

```ts
declare const TaskFailureHook: TaskFailureHook<Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L39)

### TaskHandler

**Signature**

```ts
declare const TaskHandler: TaskHandler<
  InputSchema,
  OutputSchema,
  Execution,
  Dependencies,
  Errors,
  ProgressSchema,
  Streams,
  Publishes
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L40)

### TaskHandlerResult

**Signature**

```ts
declare const TaskHandlerResult: TaskHandlerResult<Output, Errors>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L41)

### TaskInput

**Signature**

```ts
declare const TaskInput: TaskInput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L30)

### TaskLogging

**Signature**

```ts
declare const TaskLogging: TaskLogging;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L42)

### TaskObservation

**Signature**

```ts
declare const TaskObservation: TaskObservation<Streams, ProgressSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L43)

### TaskOutput

**Signature**

```ts
declare const TaskOutput: TaskOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L31)

### TaskRawHandlerOutput

**Signature**

```ts
declare const TaskRawHandlerOutput: TaskRawHandlerOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L34)

### TaskStartHook

**Signature**

```ts
declare const TaskStartHook: TaskStartHook<InputSchema, Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L44)

### TaskSuccessHook

**Signature**

```ts
declare const TaskSuccessHook: TaskSuccessHook<OutputSchema, Dependencies, Publishes>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L45)

### TaskValidatedOutput

**Signature**

```ts
declare const TaskValidatedOutput: TaskValidatedOutput<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-definition.types.ts#L35)

## `task-emission.types.ts`

### TaskProgressEmitter (interface)

Emitter contract for task progress items.

**Signature**

```ts
export interface TaskProgressEmitter<Value = unknown> {
  readonly emit: (value: Value) => Promise<ProgressEmitReceipt>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L6)

### TaskProgressInput (type alias)

Input type inferred for task progress.

**Signature**

```ts
type TaskProgressInput<Schema extends StandardSchemaV1> = InferInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L18)

### TaskProgressOutput (type alias)

Output type inferred for task progress.

**Signature**

```ts
type TaskProgressOutput<Schema extends StandardSchemaV1> = InferOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L20)

### TaskStreamEmitter (interface)

Emitter contract for task stream items.

**Signature**

```ts
export interface TaskStreamEmitter<Value = unknown> {
  readonly emit: (value: Value) => Promise<ProgressEmitReceipt>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L11)

### TaskStreamEmitters (type alias)

Named emitters whose input types follow each declared stream schema.

**Signature**

```ts
type TaskStreamEmitters<Streams extends TaskStreamSchemas> = {
  readonly [Name in keyof Streams & string]: TaskStreamEmitter<TaskStreamInput<Streams[Name]>>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L26)

### TaskStreamFrames (type alias)

Discriminated frames for all declared task streams.

**Signature**

```ts
type TaskStreamFrames<Streams extends TaskStreamSchemas> = {
  readonly [Name in keyof Streams & string]: NamedStreamFrame<TaskStreamOutput<Streams[Name]>> & {
    readonly name: Name;
  };
}[keyof Streams & string];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L30)

### TaskStreamInput (type alias)

Input type inferred for task stream.

**Signature**

```ts
type TaskStreamInput<Schema extends StandardSchemaV1> = InferInput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L22)

### TaskStreamItem (type alias)

Validated item output inferred from a stream schema.

**Signature**

```ts
type TaskStreamItem<Schema extends StandardSchemaV1> = InferOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L16)

### TaskStreamOutput (type alias)

Output type inferred for task stream.

**Signature**

```ts
type TaskStreamOutput<Schema extends StandardSchemaV1> = InferOutput<Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-emission.types.ts#L24)

## `task-observation-validation.ts`

### TaskObservationError (class)

An invalid task observation declaration.

**Example**

```ts
new TaskObservationError({ reason: "Task observation must be an object" });
```

**Signature**

```ts
declare class TaskObservationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.ts#L13)

### copyObservation

Synchronous task observation compatibility adapter.

**Throws**

TypeError when the declaration contradicts task schemas.

**Example**

```ts
copyObservation(undefined, undefined, undefined);
```

**Signature**

```ts
declare const copyObservation: (
  value: unknown,
  progress: unknown,
  streams: ObservationStreams,
) => TaskObservation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.ts#L101)

### copyObservationEffect

Normalizes a task's progress and stream observation declarations in Effect.

**Example**

```ts
Effect.runPromise(copyObservationEffect(undefined, undefined, undefined));
```

**Signature**

```ts
declare const copyObservationEffect: (
  value: unknown,
  progress: unknown,
  streams: ObservationStreams,
) => Effect.Effect<NormalizedObservation, TaskObservationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.ts#L25)

## `task-observation-validation.types.ts`

### NormalizedObservation (type alias)

Normalized observation configuration.

**Signature**

```ts
type NormalizedObservation = TaskObservation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.types.ts#L9)

### ObservationStreams (type alias)

Declared schemas available to the task observation validator.

**Signature**

```ts
type ObservationStreams = TaskStreamSchemas | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.types.ts#L6)

### TaskObservation

**Signature**

```ts
declare const TaskObservation: TaskObservation<Streams, ProgressSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.types.ts#L3)

### TaskStreamSchemas

**Signature**

```ts
declare const TaskStreamSchemas: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-observation-validation.types.ts#L3)

## `task-policy-basic.ts`

### assertBoundedString

Synchronous bounded string assertion.

**Throws**

TypeError for invalid text.

**Example**

```ts
assertBoundedString("tag", "Task tag");
```

**Signature**

```ts
declare const assertBoundedString: (
  value: unknown,
  name: string,
  maxBytes?: number,
) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L49)

### assertBoundedStringEffect

Checks nonempty bounded UTF-8 text in Effect.

**Example**

```ts
Effect.runSync(assertBoundedStringEffect("tag", "Task tag"));
```

**Signature**

```ts
declare const assertBoundedStringEffect: (
  value: unknown,
  name: string,
  maxBytes?: any,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L35)

### assertCanonicalScalarKey

Synchronous required canonical scalar key assertion.

**Throws**

TypeError for unsupported projections or fields.

**Example**

```ts
assertCanonicalScalarKey(schema, "tenantId", "concurrency.key");
```

**Signature**

```ts
declare const assertCanonicalScalarKey: (
  schema: StandardSchemaV1,
  key: string,
  name: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L114)

### assertCanonicalScalarKeyEffect

Checks that a concurrency key is a required canonical scalar in Effect.

**Example**

```ts
Effect.runSync(assertCanonicalScalarKeyEffect(schema, "tenantId", "concurrency.key"));
```

**Signature**

```ts
declare const assertCanonicalScalarKeyEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  key: string,
  name: string,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L100)

### assertFieldName

Synchronous top-level field name assertion.

**Throws**

TypeError for invalid paths or expressions.

**Example**

```ts
assertFieldName("tenantId");
```

**Signature**

```ts
declare const assertFieldName: (value: unknown, name?: string) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L73)

### assertFieldNameEffect

Checks a top-level canonical field name in Effect.

**Example**

```ts
Effect.runSync(assertFieldNameEffect("tenantId"));
```

**Signature**

```ts
declare const assertFieldNameEffect: (
  value: unknown,
  name?: any,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L62)

### memoryBytes

Synchronous memory quantity parser.

**Throws**

TypeError for invalid or unsafe quantities.

**Example**

```ts
memoryBytes("1 GiB");
```

**Signature**

```ts
declare const memoryBytes: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L90)

### memoryBytesEffect

Parses an exact MiB or GiB memory quantity in Effect.

**Example**

```ts
Effect.runSync(memoryBytesEffect("1 GiB"));
```

**Signature**

```ts
declare const memoryBytesEffect: (
  value: string,
) => Effect.Effect<number, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L81)

### utf8Bytes

Synchronous UTF-8 byte count.

**Example**

```ts
utf8Bytes("hello");
```

**Signature**

```ts
declare const utf8Bytes: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L25)

### utf8BytesEffect

Counts encoded UTF-8 bytes in Effect.

**Example**

```ts
Effect.runSync(utf8BytesEffect("hello"));
```

**Signature**

```ts
declare const utf8BytesEffect: (
  value: string,
) => Effect.Effect<number, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-basic.ts#L17)

## `task-policy-copy.ts`

### copyConcurrency

Synchronous task concurrency copier.

**Throws**

TypeError for invalid concurrency settings.

**Example**

```ts
copyConcurrency({ limit: 2 });
```

**Signature**

```ts
declare const copyConcurrency: (
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => TaskConcurrency | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L64)

### copyConcurrencyEffect

Copies bounded concurrency settings in Effect.

**Example**

```ts
Effect.runSync(copyConcurrencyEffect({ limit: 2 }));
```

**Signature**

```ts
declare const copyConcurrencyEffect: (
  value: unknown,
  canonicalSchema?: StandardSchemaV1<unknown, unknown> | undefined,
) => Effect.Effect<TaskConcurrency<string> | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L51)

### copyLogging

Synchronous logging policy copier.

**Throws**

TypeError for invalid logging policy.

**Example**

```ts
copyLogging({ level: "info" });
```

**Signature**

```ts
declare const copyLogging: (value: unknown) => TaskLogging | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L84)

### copyLoggingEffect

Copies bounded logging settings in Effect.

**Example**

```ts
Effect.runSync(copyLoggingEffect({ level: "info" }));
```

**Signature**

```ts
declare const copyLoggingEffect: (
  value: unknown,
) => Effect.Effect<TaskLogging | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L75)

### copyResources

Synchronous task resource copier.

**Throws**

TypeError for invalid CPU or memory settings.

**Example**

```ts
copyResources({ cpu: 1, memory: "1 GiB" });
```

**Signature**

```ts
declare const copyResources: (value: unknown) => TaskResources | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L42)

### copyResourcesEffect

Copies validated CPU and memory settings in Effect.

**Example**

```ts
Effect.runSync(copyResourcesEffect({ cpu: 1, memory: "1 GiB" }));
```

**Signature**

```ts
declare const copyResourcesEffect: (
  value: unknown,
) => Effect.Effect<TaskResources | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L33)

### copyTaskTags

Synchronous task tag copier.

**Throws**

TypeError for invalid or duplicate tags.

**Example**

```ts
copyTaskTags(["important"]);
```

**Signature**

```ts
declare const copyTaskTags: (value: unknown) => readonly string[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L25)

### copyTaskTagsEffect

Copies bounded unique task tags in Effect.

**Example**

```ts
Effect.runSync(copyTaskTagsEffect(["important"]));
```

**Signature**

```ts
declare const copyTaskTagsEffect: (
  value: unknown,
) => Effect.Effect<ReadonlyArray<string> | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-copy.ts#L16)

## `task-policy-random.ts`

### TaskPolicyRandom (class)

Substitutable random sample source for retry jitter.

**Example**

```ts
const service = yield * TaskPolicyRandom;
```

**Signature**

```ts
declare class TaskPolicyRandom
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-random.ts#L8)

### retryDelayMillis

Synchronous bounded retry delay calculator.

**Throws**

TypeError for invalid attempts or samples.

**Example**

```ts
retryDelayMillis(policy, 2, 0, () => 0.5);
```

**Signature**

```ts
declare const retryDelayMillis: (
  policy: NormalizedTaskRetryPolicy,
  attempt: number,
  retryAfterMillis?: number,
  random?: () => number,
) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-random.ts#L54)

### retryDelayMillisEffect

Computes bounded retry delay in Effect using an injectable sample source.

**Example**

```ts
Effect.runSync(
  Effect.provide(
    retryDelayMillisEffect(policy, 2),
    taskPolicyRandomLayer(() => 0.5),
  ),
);
```

**Signature**

```ts
declare const retryDelayMillisEffect: (
  policy: NormalizedTaskRetryPolicy,
  attempt: number,
  retryAfterMillis?: any,
  random?: (() => number) | undefined,
) => Effect.Effect<number, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-random.ts#L27)

### taskPolicyRandomLayer

Provides deterministic retry jitter samples.

**Example**

```ts
taskPolicyRandomLayer(() => 0.5);
```

**Signature**

```ts
declare const taskPolicyRandomLayer: (
  sample: () => number,
) => Layer.Layer<TaskPolicyRandom, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-random.ts#L17)

## `task-policy-validation.ts`

### "./task-policy-basic.js" (namespace export)

Re-exports all named exports from the "./task-policy-basic.js" module.

**Signature**

```ts
export * from "./task-policy-basic.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L9)

### "./task-policy-copy.js" (namespace export)

Re-exports all named exports from the "./task-policy-copy.js" module.

**Signature**

```ts
export * from "./task-policy-copy.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L10)

### "./task-policy-random.js" (namespace export)

Re-exports all named exports from the "./task-policy-random.js" module.

**Signature**

```ts
export * from "./task-policy-random.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L11)

### TASK_INPUT_MAX_BYTES

**Signature**

```ts
declare const TASK_INPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L2)

### TASK_ITEM_MAX_BYTES

**Signature**

```ts
declare const TASK_ITEM_MAX_BYTES: number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L4)

### TASK_KEY_MAX_BYTES

**Signature**

```ts
declare const TASK_KEY_MAX_BYTES: 256;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L5)

### TASK_MAX_TAGS

**Signature**

```ts
declare const TASK_MAX_TAGS: 20;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L7)

### TASK_OUTPUT_MAX_BYTES

**Signature**

```ts
declare const TASK_OUTPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L3)

### TASK_REASON_MAX_BYTES

**Signature**

```ts
declare const TASK_REASON_MAX_BYTES: 1024;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-validation.ts#L6)

## `task-policy-value-copy.ts`

### assertCanonicalScalarKey

Requires a projected required string or number field for partitioning.

**Throws**

TypeError for missing or unsupported schema projections.

**Example**

```ts
assertCanonicalScalarKey(schema, "tenantId", "concurrency.key");
```

**Signature**

```ts
declare const assertCanonicalScalarKey: (
  schema: StandardSchemaV1,
  key: string,
  name: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value-copy.ts#L83)

### copyConcurrency

Validates a bounded concurrency limit and optional canonical scalar key.

**Throws**

TypeError for invalid limits or keys.

**Example**

```ts
copyConcurrency({ limit: 2, key: "tenantId" }, schema);
```

**Signature**

```ts
declare const copyConcurrency: (
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => TaskConcurrency | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value-copy.ts#L57)

### copyLogging

Copies logging level and unique redaction keys.

**Throws**

TypeError for invalid levels or redaction names.

**Example**

```ts
copyLogging({ level: "info", redact: ["secret"] });
```

**Signature**

```ts
declare const copyLogging: (value: unknown) => TaskLogging | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value-copy.ts#L113)

### copyResources

Validates CPU and exact memory for a task resource request.

**Throws**

TypeError for invalid CPU or memory.

**Example**

```ts
copyResources({ cpu: 1, memory: "1 GiB" });
```

**Signature**

```ts
declare const copyResources: (value: unknown) => TaskResources | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value-copy.ts#L34)

### copyTaskTags

Copies unique, bounded task tags into a frozen list.

**Throws**

TypeError for duplicates, invalid text, or excess tags.

**Example**

```ts
copyTaskTags(["urgent"]);
```

**Signature**

```ts
declare const copyTaskTags: (value: unknown) => readonly string[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value-copy.ts#L16)

## `task-policy-value.ts`

### TASK_INPUT_MAX_BYTES

Maximum canonical task input bytes.

**Example**

```ts
TASK_INPUT_MAX_BYTES === 1_048_576;
```

**Signature**

```ts
declare const TASK_INPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L6)

### TASK_ITEM_MAX_BYTES

Maximum progress or stream item bytes.

**Example**

```ts
TASK_ITEM_MAX_BYTES === 65_536;
```

**Signature**

```ts
declare const TASK_ITEM_MAX_BYTES: number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L14)

### TASK_KEY_MAX_BYTES

Maximum identifier and scalar key bytes.

**Example**

```ts
TASK_KEY_MAX_BYTES === 256;
```

**Signature**

```ts
declare const TASK_KEY_MAX_BYTES: 256;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L18)

### TASK_MAX_TAGS

Maximum count of unique task tags.

**Example**

```ts
TASK_MAX_TAGS === 20;
```

**Signature**

```ts
declare const TASK_MAX_TAGS: 20;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L26)

### TASK_OUTPUT_MAX_BYTES

Maximum canonical task output bytes.

**Example**

```ts
TASK_OUTPUT_MAX_BYTES === 1_048_576;
```

**Signature**

```ts
declare const TASK_OUTPUT_MAX_BYTES: 1048576;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L10)

### TASK_REASON_MAX_BYTES

Maximum bounded reason text bytes.

**Example**

```ts
TASK_REASON_MAX_BYTES === 1_024;
```

**Signature**

```ts
declare const TASK_REASON_MAX_BYTES: 1024;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L22)

### assertBoundedString

Requires a nonempty UTF-8 string within a configured byte limit.

**Throws**

TypeError for empty, nontext, or oversized values.

**Example**

```ts
assertBoundedString("order-1", "orderId");
```

**Signature**

```ts
declare const assertBoundedString: (
  value: unknown,
  name: string,
  maxBytes?: number,
) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L46)

### assertCanonicalScalarKey

**Signature**

```ts
declare const assertCanonicalScalarKey: (
  schema: StandardSchemaV1,
  key: string,
  name: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L127)

### assertFieldName

Requires one top-level canonical field name rather than a path.

**Throws**

TypeError for invalid paths or expressions.

**Example**

```ts
assertFieldName("tenantId");
```

**Signature**

```ts
declare const assertFieldName: (value: unknown, name?: string) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L62)

### copyConcurrency

**Signature**

```ts
declare const copyConcurrency: (
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => TaskConcurrency | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L126)

### copyLogging

**Signature**

```ts
declare const copyLogging: (value: unknown) => TaskLogging | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L128)

### copyResources

**Signature**

```ts
declare const copyResources: (value: unknown) => TaskResources | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L125)

### copyTaskTags

**Signature**

```ts
declare const copyTaskTags: (value: unknown) => readonly string[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L124)

### memoryBytes

Parses exact decimal MiB or GiB memory into safe integer bytes.

**Throws**

TypeError for fractional bytes or unsafe ranges.

**Example**

```ts
memoryBytes("1.5 GiB");
```

**Signature**

```ts
declare const memoryBytes: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L74)

### retryDelayMillis

Computes bounded task retry delay with optional jitter and retry-after floor.

**Throws**

TypeError for invalid attempt or jitter.

**Example**

```ts
retryDelayMillis(policy, 2, 0, () => 0.5);
```

**Signature**

```ts
declare const retryDelayMillis: (
  policy: NormalizedTaskRetryPolicy,
  attempt: number,
  retryAfterMillis?: number,
  random?: () => number,
) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L99)

### utf8Bytes

Counts UTF-8 bytes rather than JavaScript code units.

**Example**

```ts
utf8Bytes("é");
```

**Signature**

```ts
declare const utf8Bytes: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-policy-value.ts#L35)

## `task-progress-emission.ts`

### createEmission

Builds a validated Effect emitter and its compatibility adapter.

**Example**

```ts
createEmission(progressSchema, options, "progress");
```

**Signature**

```ts
declare const createEmission: <S extends StandardSchemaV1>(
  schema: S,
  options: TaskEmitterOptions,
  kind: "progress" | "stream",
) => EffectTaskEmitter<InferInput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress-emission.ts#L20)

## `task-progress-error.ts`

### TaskEmissionError (class)

Compatibility error thrown by Promise based task emitters.

**Example**

```ts
if (error instanceof TaskEmissionError) console.log(error.message);
```

**Signature**

```ts
declare class TaskEmissionError { constructor(
    readonly code: TaskEmissionErrorCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress-error.ts#L6)

### TaskEmissionFailure (class)

Expected emission failure in Effect, retaining the compatibility error.

**Example**

```ts
if (error instanceof TaskEmissionFailure) console.log(error.message);
```

**Signature**

```ts
declare class TaskEmissionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress-error.ts#L18)

## `task-progress.ts`

### EffectTaskEmitter

**Signature**

```ts
declare const EffectTaskEmitter: EffectTaskEmitter<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L19)

### TaskEmissionError

**Signature**

```ts
declare const TaskEmissionError: typeof TaskEmissionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L12)

### TaskEmissionErrorCode

**Signature**

```ts
declare const TaskEmissionErrorCode: TaskEmissionErrorCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L18)

### TaskEmissionFailure

**Signature**

```ts
declare const TaskEmissionFailure: typeof TaskEmissionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L12)

### TaskEmissionSink

**Signature**

```ts
declare const TaskEmissionSink: TaskEmissionSink;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L14)

### TaskEmitterOptions

**Signature**

```ts
declare const TaskEmitterOptions: TaskEmitterOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L15)

### TaskStreamEmitterOptions

**Signature**

```ts
declare const TaskStreamEmitterOptions: TaskStreamEmitterOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L16)

### TaskStreamSink

**Signature**

```ts
declare const TaskStreamSink: TaskStreamSink;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L17)

### createTaskProgressEmitter

Compatibility factory for validated progress emitters.

**Throws**

TypeError if the configured byte limit is invalid.

**Example**

```ts
createTaskProgressEmitter(z.string());
```

**Signature**

```ts
declare const createTaskProgressEmitter: <S extends StandardSchemaV1>(
  schema: S,
  options?: TaskEmitterOptions,
) => EffectTaskEmitter<InferInput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L44)

### createTaskProgressEmitterEffect

Creates a validated progress emitter in Effect.

**Example**

```ts
Effect.runSync(createTaskProgressEmitterEffect(z.string()));
```

**Signature**

```ts
declare const createTaskProgressEmitterEffect: <S extends StandardSchemaV1>(
  schema: S,
  options?: TaskEmitterOptions | undefined,
) => Effect.Effect<EffectTaskEmitter<InferInput<S>>, TaskEmissionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L27)

### createTaskStreamEmitter

Compatibility factory for named stream emitters.

**Throws**

TypeError for invalid names or byte limits.

**Example**

```ts
createTaskStreamEmitter(z.string(), { name: "events" });
```

**Signature**

```ts
declare const createTaskStreamEmitter: <S extends StandardSchemaV1>(
  schema: S,
  options: TaskStreamEmitterOptions,
) => EffectTaskEmitter<InferInput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L100)

### createTaskStreamEmitterEffect

Creates a named stream emitter in Effect.

**Example**

```ts
Effect.runSync(createTaskStreamEmitterEffect(z.string(), { name: "events" }));
```

**Signature**

```ts
declare const createTaskStreamEmitterEffect: <S extends StandardSchemaV1>(
  schema: S,
  options: TaskStreamEmitterOptions,
) => Effect.Effect<EffectTaskEmitter<InferInput<S>>, TaskEmissionFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.ts#L58)

## `task-progress.types.ts`

### EffectTaskEmitter (interface)

An emitter with a typed Effect operation alongside its Promise adapter.

**Signature**

```ts
export interface EffectTaskEmitter<Value> {
  readonly emit: (value: Value) => Promise<ProgressEmitReceipt>;
  readonly emitEffect: (value: Value) => Effect.Effect<ProgressEmitReceipt, TaskEmissionFailure>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L42)

### TaskEmissionErrorCode (type alias)

Stable compatibility error codes for task emissions.

**Signature**

```ts
type TaskEmissionErrorCode =
  | "RELKIT_TASK_PROGRESS_INVALID"
  | "RELKIT_TASK_STREAM_INVALID"
  | "RELKIT_TASK_PROGRESS_TOO_LARGE"
  | "RELKIT_TASK_STREAM_TOO_LARGE"
  | "RELKIT_TASK_PROGRESS_PERSISTENCE"
  | "RELKIT_TASK_STREAM_PERSISTENCE"
  | "RELKIT_TASK_PROGRESS_RETENTION"
  | "RELKIT_TASK_STREAM_RETENTION"
  | "RELKIT_TASK_EMISSION_ABORTED";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L31)

### TaskEmissionSink (type alias)

Sink for a validated progress item.

**Signature**

```ts
type TaskEmissionSink = (
  value: unknown,
  signal: AbortSignal,
) => MaybePromise<ProgressEmitReceipt | void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L6)

### TaskEmitterOptions (interface)

Delivery and retention settings for a progress emitter.

**Signature**

```ts
export interface TaskEmitterOptions {
  readonly signal?: AbortSignal;
  readonly sink?: TaskEmissionSink;
  readonly durable?: boolean;
  readonly maxBytes?: number;
  readonly generation?: string;
  readonly requireGeneration?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L11)

### TaskStreamEmitterOptions (interface)

Delivery settings for a named stream emitter.

**Signature**

```ts
export interface TaskStreamEmitterOptions extends Omit<TaskEmitterOptions, "sink"> {
  readonly name: string;
  readonly sink?: TaskStreamSink;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L20)

### TaskStreamSink (type alias)

Sink for a validated named stream item.

**Signature**

```ts
type TaskStreamSink = (
  value: unknown,
  signal: AbortSignal,
  identity: { readonly name: string; readonly generation?: string },
) => MaybePromise<ProgressEmitReceipt | void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-progress.types.ts#L25)

## `task-types.ts`

### "./task-core.types.js" (namespace export)

Re-exports all named exports from the "./task-core.types.js" module.

**Signature**

```ts
export * from "./task-core.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-types.ts#L1)

### "./task-definition.types.js" (namespace export)

Re-exports all named exports from the "./task-definition.types.js" module.

**Signature**

```ts
export * from "./task-definition.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-types.ts#L2)

## `task-validation-copy.ts`

### copyDependencies

Synchronous dependency map copier.

**Throws**

TypeError for invalid dependencies.

**Example**

```ts
copyDependencies({ tasks: {} });
```

**Signature**

```ts
declare const copyDependencies: <Dependencies extends TaskDependencies>(
  value: unknown,
) => Dependencies | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L53)

### copyDependenciesEffect

Copies declared task dependencies in Effect.

**Example**

```ts
Effect.runSync(copyDependenciesEffect({ tasks: {} }));
```

**Signature**

```ts
declare const copyDependenciesEffect: <Dependencies extends TaskDependencies>(
  value: unknown,
) => Effect.Effect<Dependencies | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L41)

### copyErrors

Synchronous task error descriptor copier.

**Throws**

TypeError for invalid descriptors.

**Example**

```ts
copyErrors([]);
```

**Signature**

```ts
declare const copyErrors: (value: unknown) => readonly ErrorDescriptorAny[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L72)

### copyErrorsEffect

Copies declared task errors in Effect.

**Example**

```ts
Effect.runSync(copyErrorsEffect([]));
```

**Signature**

```ts
declare const copyErrorsEffect: (
  value: unknown,
) => Effect.Effect<ReadonlyArray<ErrorDescriptorAny> | undefined, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L63)

### copyStreams

Synchronous stream schema copier.

**Throws**

TypeError for invalid stream names or schemas.

**Example**

```ts
copyStreams({ text: z.string() });
```

**Signature**

```ts
declare const copyStreams: (value: unknown) => TaskStreamSchemas | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L89)

### copyStreamsEffect

Copies named task stream schemas in Effect.

**Example**

```ts
Effect.runSync(copyStreamsEffect({ text: z.string() }));
```

**Signature**

```ts
declare const copyStreamsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<Record<string, StandardSchemaV1<unknown, unknown>>> | undefined,
  TaskValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L80)

### duration

Synchronous task duration validator.

**Throws**

TypeError for invalid duration.

**Example**

```ts
duration("1 second", "maxDuration", true);
```

**Signature**

```ts
declare const duration: (value: unknown, name: string, positive?: boolean) => DurationInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L111)

### normalizeRetry

Synchronous retry policy normalizer.

**Throws**

TypeError for invalid retry settings.

**Example**

```ts
normalizeRetry({ maxAttempts: 3 });
```

**Signature**

```ts
declare const normalizeRetry: (value: unknown) => NormalizedTaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L33)

### normalizeRetryEffect

Normalizes a task retry policy in Effect.

**Example**

```ts
Effect.runSync(normalizeRetryEffect({ maxAttempts: 3 }));
```

**Signature**

```ts
declare const normalizeRetryEffect: (
  value: unknown,
) => Effect.Effect<NormalizedTaskRetryPolicy, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L24)

### taskDurationEffect

Validates a readable task duration in Effect.

**Example**

```ts
Effect.runSync(taskDurationEffect("1 second", "maxDuration", true));
```

**Signature**

```ts
declare const taskDurationEffect: (
  value: unknown,
  name: string,
  positive?: any,
) => Effect.Effect<
  | `${number} second`
  | `${number} seconds`
  | `${number} minute`
  | `${number} minutes`
  | `${number} hour`
  | `${number} hours`
  | `${number} day`
  | `${number} days`
  | `${number} week`
  | `${number} weeks`
  | `${number} millisecond`
  | `${number} milliseconds`,
  TaskValidationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-copy.ts#L99)

## `task-validation-run.ts`

### TaskValidationFailure (class)

Expected task definition validation failure with its original cause.

**Example**

```ts
if (error instanceof TaskValidationFailure) console.log(error.message);
```

**Signature**

```ts
declare class TaskValidationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-run.ts#L7)

### runTaskValidation

Synchronous task validation compatibility runner.

**Throws**

The original validation error on failure.

**Example**

```ts
runTaskValidation(taskValidationEffect("task.validate", () => descriptor));
```

**Signature**

```ts
declare const runTaskValidation: <A>(effect: Effect.Effect<A, TaskValidationFailure>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-run.ts#L32)

### taskValidationEffect

Runs a task validation calculation in observed Effect.

**Example**

```ts
taskValidationEffect("task.validate", () => descriptor);
```

**Signature**

```ts
declare const taskValidationEffect: <A>(
  operation: JobsOperation,
  compute: () => A,
) => Effect.Effect<A, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-run.ts#L17)

## `task-validation-schema.ts`

### assertCanonicalSchemaSupport

Synchronous canonical schema assertion.

**Throws**

TypeError for unsupported schema projections.

**Example**

```ts
assertCanonicalSchemaSupport(z.string(), "output");
```

**Signature**

```ts
declare const assertCanonicalSchemaSupport: (
  schema: StandardSchemaV1,
  name: string,
  allowVoid?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L90)

### assertCanonicalSchemaSupportEffect

Checks canonical schema projection in Effect.

**Example**

```ts
Effect.runSync(assertCanonicalSchemaSupportEffect(z.string(), "output"));
```

**Signature**

```ts
declare const assertCanonicalSchemaSupportEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  name: string,
  allowVoid?: any,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L76)

### assertCanonicalStreamSupport

Synchronous named stream schema assertion.

**Throws**

TypeError for noncanonical stream schemas.

**Example**

```ts
assertCanonicalStreamSupport({ text: z.string() });
```

**Signature**

```ts
declare const assertCanonicalStreamSupport: (streams: TaskStreamSchemas | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L114)

### assertCanonicalStreamSupportEffect

Checks each named stream schema in Effect.

**Example**

```ts
Effect.runSync(assertCanonicalStreamSupportEffect({ text: z.string() }));
```

**Signature**

```ts
declare const assertCanonicalStreamSupportEffect: (
  streams: Readonly<Record<string, StandardSchemaV1<unknown, unknown>>> | undefined,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L102)

### assertInputWireSupport

Synchronous task inputWire support assertion.

**Throws**

TypeError for noncanonical input support.

**Example**

```ts
assertInputWireSupport(z.string(), undefined);
```

**Signature**

```ts
declare const assertInputWireSupport: (input: StandardSchemaV1, inputWire: unknown) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L66)

### assertInputWireSupportEffect

Checks canonical support for input and optional inputWire in Effect.

**Example**

```ts
Effect.runSync(assertInputWireSupportEffect(z.string(), undefined));
```

**Signature**

```ts
declare const assertInputWireSupportEffect: (
  input: StandardSchemaV1<unknown, unknown>,
  inputWire: unknown,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L55)

### assertSchema

Synchronous Standard Schema v1 assertion.

**Throws**

TypeError for invalid schema.

**Example**

```ts
assertSchema(z.string(), "Task input");
```

**Signature**

```ts
declare const assertSchema: (value: unknown, name: string) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L29)

### assertSchemaEffect

Asserts Standard Schema v1 in Effect.

**Example**

```ts
Effect.runSync(assertSchemaEffect(z.string(), "Task input"));
```

**Signature**

```ts
declare const assertSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L18)

### normalizeVersion

Synchronous task version normalizer.

**Throws**

Original invalid identifier error.

**Example**

```ts
normalizeVersion("v1");
```

**Signature**

```ts
declare const normalizeVersion: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L46)

### normalizeVersionEffect

Normalizes a task version or identifier in Effect.

**Example**

```ts
Effect.runSync(normalizeVersionEffect("v1"));
```

**Signature**

```ts
declare const normalizeVersionEffect: (
  value: unknown,
) => Effect.Effect<string, TaskValidationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-schema.ts#L37)

## `task-validation-value-copy.ts`

### copyDependencies

Copies declared task dependencies by supported kind and stable name.

**Throws**

TypeError for unsupported kinds or invalid references.

**Example**

```ts
copyDependencies({ jobs: { send: jobRef } });
```

**Signature**

```ts
declare const copyDependencies: <Dependencies extends TaskDependencies>(
  value: unknown,
) => Dependencies | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value-copy.ts#L15)

### copyErrors

Copies unique declared task error descriptors.

**Throws**

TypeError for invalid descriptors or duplicate IDs.

**Example**

```ts
copyErrors([notFoundError]);
```

**Signature**

```ts
declare const copyErrors: (value: unknown) => readonly ErrorDescriptorAny[] | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value-copy.ts#L56)

### copyStreams

Copies named task streams with Standard Schema validators.

**Throws**

TypeError for invalid stream names or validators.

**Example**

```ts
copyStreams({ events: eventSchema });
```

**Signature**

```ts
declare const copyStreams: (value: unknown) => TaskStreamSchemas | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value-copy.ts#L72)

## `task-validation-value.ts`

### assertCanonicalSchemaSupport

Checks a schema's faithful canonical output projection.

**Throws**

TypeError for transforms or missing projections.

**Example**

```ts
assertCanonicalSchemaSupport(outputSchema, "Task output");
```

**Signature**

```ts
declare const assertCanonicalSchemaSupport: (
  schema: StandardSchemaV1,
  name: string,
  allowVoid?: boolean,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L60)

### assertCanonicalStreamSupport

Checks every stream item schema for canonical output support.

**Throws**

TypeError for unsupported stream item schemas.

**Example**

```ts
assertCanonicalStreamSupport({ events: eventSchema });
```

**Signature**

```ts
declare const assertCanonicalStreamSupport: (streams: TaskStreamSchemas | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L78)

### assertInputWireSupport

Requires transformed input to provide a canonical identity validator.

**Throws**

TypeError for unsupported transformations.

**Example**

```ts
assertInputWireSupport(inputSchema, inputWireSchema);
```

**Signature**

```ts
declare const assertInputWireSupport: (input: StandardSchemaV1, inputWire: unknown) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L39)

### assertSchema

Requires the Standard Schema v1 validator shape.

**Throws**

TypeError for missing or malformed Standard Schema fields.

**Example**

```ts
assertSchema(schema, "Task input");
```

**Signature**

```ts
declare const assertSchema: (value: unknown, name: string) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L13)

### duration

Validates readable duration text and optional positivity.

**Throws**

TypeError for unreadable or nonpositive durations.

**Example**

```ts
duration("1 second", "timeout", true);
```

**Signature**

```ts
declare const duration: (value: unknown, name: string, positive?: boolean) => DurationInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L120)

### normalizeRetry

Applies safe retry defaults and validates delay, factor, and jitter.

**Throws**

TypeError for invalid attempts or delay relationships.

**Example**

```ts
normalizeRetry({ maxAttempts: 5 });
```

**Signature**

```ts
declare const normalizeRetry: (value: unknown) => NormalizedTaskRetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L89)

### normalizeVersion

Normalizes the task version to a stable identifier.

**Throws**

TypeError for invalid identifiers.

**Example**

```ts
normalizeVersion("v1");
```

**Signature**

```ts
declare const normalizeVersion: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation-value.ts#L29)

## `task-validation.ts`

### "./task-validation-copy.js" (namespace export)

Re-exports all named exports from the "./task-validation-copy.js" module.

**Signature**

```ts
export * from "./task-validation-copy.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L2)

### "./task-validation-schema.js" (namespace export)

Re-exports all named exports from the "./task-validation-schema.js" module.

**Signature**

```ts
export * from "./task-validation-schema.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L1)

### TaskValidationFailure

**Signature**

```ts
declare const TaskValidationFailure: typeof TaskValidationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L3)

### copyConcurrency

**Signature**

```ts
declare const copyConcurrency: (
  value: unknown,
  canonicalSchema?: StandardSchemaV1,
) => TaskConcurrency | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L5)

### copyLogging

**Signature**

```ts
declare const copyLogging: (value: unknown) => TaskLogging | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L5)

### copyObservation

**Signature**

```ts
declare const copyObservation: (
  value: unknown,
  progress: unknown,
  streams: ObservationStreams,
) => TaskObservation | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L4)

### copyResources

**Signature**

```ts
declare const copyResources: (value: unknown) => TaskResources | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-validation.ts#L5)

## `task-wire-codec.ts`

### decodeJobWire

Synchronous validated job wire decoder.

**Throws**

TaskWireValidationError or TypeError for malformed input.

**Example**

```ts
decodeJobWire(encodeTaskInput("value"));
```

**Signature**

```ts
declare const decodeJobWire: (envelope: unknown, maxBytes?: number) => JsonValue | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L92)

### decodeJobWireEffect

Decodes and validates a job wire envelope in Effect.

**Example**

```ts
Effect.runSync(decodeJobWireEffect(encodeTaskInput("value")));
```

**Signature**

```ts
declare const decodeJobWireEffect: (
  envelope: unknown,
  maxBytes?: any,
) => Effect.Effect<JsonValue | undefined, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L81)

### encodeJobWire

Synchronous generic job wire encoder.

**Throws**

TaskWireValidationError or TypeError for invalid input.

**Example**

```ts
encodeJobWire({ id: 1 });
```

**Signature**

```ts
declare const encodeJobWire: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L29)

### encodeJobWireEffect

Encodes a generic job wire envelope in Effect.

**Example**

```ts
Effect.runSync(encodeJobWireEffect({ id: 1 }));
```

**Signature**

```ts
declare const encodeJobWireEffect: (
  value: unknown,
  maxBytes?: any,
) => Effect.Effect<JobWireEnvelope, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L18)

### encodeTaskInput

Synchronous task input encoder.

**Throws**

TaskWireValidationError or TypeError for invalid input.

**Example**

```ts
encodeTaskInput({ id: 1 });
```

**Signature**

```ts
declare const encodeTaskInput: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L49)

### encodeTaskInputEffect

Encodes task input in Effect.

**Example**

```ts
Effect.runSync(encodeTaskInputEffect({ id: 1 }));
```

**Signature**

```ts
declare const encodeTaskInputEffect: (
  value: unknown,
  maxBytes?: any,
) => Effect.Effect<JobWireEnvelope, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L38)

### encodeTaskOutput

Synchronous task output encoder.

**Throws**

TaskWireValidationError or TypeError for invalid output.

**Example**

```ts
encodeTaskOutput("done");
```

**Signature**

```ts
declare const encodeTaskOutput: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L69)

### encodeTaskOutputEffect

Encodes task output in Effect.

**Example**

```ts
Effect.runSync(encodeTaskOutputEffect("done"));
```

**Signature**

```ts
declare const encodeTaskOutputEffect: (
  value: unknown,
  maxBytes?: any,
) => Effect.Effect<JobWireEnvelope, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-codec.ts#L58)

## `task-wire-run.ts`

### TaskWireFailure (class)

Expected wire operation failure with its original compatibility error.

**Example**

```ts
if (error instanceof TaskWireFailure) console.log(error.message);
```

**Signature**

```ts
declare class TaskWireFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-run.ts#L8)

### runWirePromise

Runs an Effect wire operation for Promise compatibility.

**Throws**

The original wire validation error on failure.

**Example**

```ts
await runWirePromise(wirePromiseEffect("wire.decode", async () => decoded));
```

**Signature**

```ts
declare const runWirePromise: <A>(effect: Effect.Effect<A, TaskWireFailure>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-run.ts#L67)

### runWireSync

Runs an Effect wire operation for synchronous compatibility.

**Throws**

The original wire validation error on failure.

**Example**

```ts
runWireSync(wireEffect("wire.encode", () => encoded));
```

**Signature**

```ts
declare const runWireSync: <A>(effect: Effect.Effect<A, TaskWireFailure>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-run.ts#L56)

### wireEffect

Lifts a synchronous wire operation into observed Effect.

**Example**

```ts
wireEffect("wire.encode", () => encoded);
```

**Signature**

```ts
declare const wireEffect: <A>(
  operation: JobsOperation,
  compute: () => A,
) => Effect.Effect<A, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-run.ts#L18)

### wirePromiseEffect

Lifts an asynchronous wire operation into observed Effect.

**Example**

```ts
wirePromiseEffect("wire.decode", async () => decoded);
```

**Signature**

```ts
declare const wirePromiseEffect: <A>(
  operation: JobsOperation,
  compute: () => Promise<A>,
) => Effect.Effect<A, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-run.ts#L37)

## `task-wire-support.ts`

### TaskWireErrorCode

**Signature**

```ts
declare const TaskWireErrorCode: TaskWireErrorCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L7)

### TaskWireValidationError (class)

Invalid canonical task wire data with a stable machine-readable code.

**Example**

```ts
new TaskWireValidationError("RELKIT_TASK_WIRE_INVALID", "Invalid envelope");
```

**Signature**

```ts
declare class TaskWireValidationError { constructor(
    readonly code: TaskWireErrorCode,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L12)

### assertByteLimit

Requires a positive safe integer wire size limit.

**Throws**

TypeError for zero, negative, or noninteger limits.

**Example**

```ts
assertByteLimit(1024);
```

**Signature**

```ts
declare const assertByteLimit: (maxBytes: number) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L114)

### assertEnvelope

Rejects hostile or malformed wire envelope object shapes.

**Throws**

TaskWireValidationError for invalid or accessor-backed envelopes.

**Example**

```ts
assertEnvelope({ version: 1, kind: "void" });
```

**Signature**

```ts
declare const assertEnvelope: (value: unknown) => asserts value is JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L125)

### assertSize

Enforces the encoded UTF-8 size for canonical JSON text.

**Throws**

TaskWireValidationError or TypeError for invalid size.

**Example**

```ts
assertSize("{}", 1024, "RELKIT_TASK_INPUT_TOO_LARGE", "input");
```

**Signature**

```ts
declare const assertSize: (
  text: string,
  maxBytes: number,
  code: TaskWireErrorCode,
  name: string,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L96)

### encode

Canonicalizes JSON or void data into a bounded wire envelope.

**Throws**

TaskWireValidationError or TypeError for invalid data or limit.

**Example**

```ts
encode({ id: "one" }, 1024, "RELKIT_TASK_INPUT_INVALID", "RELKIT_TASK_INPUT_TOO_LARGE", "input");
```

**Signature**

```ts
declare const encode: (
  value: unknown,
  maxBytes: number,
  invalidCode: TaskWireErrorCode,
  sizeCode: TaskWireErrorCode,
  name: string,
) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L35)

### hasOwn

Checks an envelope's own property without consulting its prototype.

**Example**

```ts
hasOwn({ kind: "void" }, "kind");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L156)

### invalidEnvelope

Fails with the stable invalid-envelope error.

**Throws**

TaskWireValidationError with the wire-invalid code.

**Example**

```ts
if (invalid) invalidEnvelope();
```

**Signature**

```ts
declare const invalidEnvelope: () => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L140)

### message

Converts a validator rejection into a bounded diagnostic string.

**Example**

```ts
message(new Error("invalid"));
```

**Signature**

```ts
declare const message: (error: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L165)

### validateValue

Runs Standard Schema validation and retains its parsed output.

**Throws**

TaskWireValidationError for issues or validator rejection.

**Example**

```ts
await validateValue(schema, "hello", "RELKIT_TASK_INPUT_INVALID");
```

**Signature**

```ts
declare const validateValue: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
  code: Extract<TaskWireErrorCode, "RELKIT_TASK_INPUT_INVALID" | "RELKIT_TASK_OUTPUT_INVALID">,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.ts#L67)

## `task-wire-support.types.ts`

Stable codes for wire validation, identity, and size errors.

### TaskWireErrorCode (type alias)

Stable codes for wire validation, identity, and size errors.

**Signature**

```ts
type TaskWireErrorCode =
  | "RELKIT_TASK_WIRE_INVALID"
  | "RELKIT_TASK_INPUT_INVALID"
  | "RELKIT_TASK_OUTPUT_INVALID"
  | "RELKIT_TASK_INPUT_WIRE_NON_IDENTITY"
  | "RELKIT_TASK_INPUT_TOO_LARGE"
  | "RELKIT_TASK_OUTPUT_TOO_LARGE";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-support.types.ts#L2)

## `task-wire-validation.ts`

### validateCanonicalInput

Promise compatibility canonical input validation.

**Throws**

TaskWireValidationError or TypeError for invalid input.

**Example**

```ts
await validateCanonicalInput(z.number(), 7);
```

**Signature**

```ts
declare const validateCanonicalInput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  inputWire?: StandardSchemaV1<InferOutput<S>, InferOutput<S>>,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L66)

### validateCanonicalInputEffect

Validates retained canonical task input in Effect.

**Example**

```ts
Effect.runPromise(validateCanonicalInputEffect(z.number(), 7));
```

**Signature**

```ts
declare const validateCanonicalInputEffect: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  inputWire?: StandardSchemaV1<InferOutput<S>, InferOutput<S>> | undefined,
  maxBytes?: number | undefined,
) => Effect.Effect<InferOutput<S>, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L46)

### validateCanonicalOutput

Promise compatibility canonical output validation.

**Throws**

TaskWireValidationError or TypeError for invalid output.

**Example**

```ts
await validateCanonicalOutput(z.string(), "done");
```

**Signature**

```ts
declare const validateCanonicalOutput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L125)

### validateCanonicalOutputEffect

Validates a retained canonical task output in Effect.

**Example**

```ts
Effect.runPromise(validateCanonicalOutputEffect(z.string(), "done"));
```

**Signature**

```ts
declare const validateCanonicalOutputEffect: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  maxBytes?: number | undefined,
) => Effect.Effect<InferOutput<S>, TaskWireFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L111)

### validateTaskInput

Promise compatibility input validation.

**Throws**

TaskWireValidationError or TypeError for invalid input.

**Example**

```ts
await validateTaskInput(z.string(), "value");
```

**Signature**

```ts
declare const validateTaskInput: <S extends StandardSchemaV1>(
  schema: S,
  input: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L31)

### validateTaskInputEffect

Validates and encodes submitted task input in Effect.

**Example**

```ts
Effect.runPromise(validateTaskInputEffect(z.string(), "value"));
```

**Signature**

```ts
declare const validateTaskInputEffect: <S extends StandardSchemaV1>(
  schema: S,
  input: InferInput<S>,
  maxBytes?: number | undefined,
) => Effect.Effect<
  { readonly value: InferOutput<S>; readonly wire: JobWireEnvelope },
  TaskWireFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L19)

### validateTaskOutput

Promise compatibility output validation.

**Throws**

TaskWireValidationError or TypeError for invalid output.

**Example**

```ts
await validateTaskOutput(z.string(), "done");
```

**Signature**

```ts
declare const validateTaskOutput: <S extends StandardSchemaV1>(
  schema: S,
  output: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L97)

### validateTaskOutputEffect

Validates and encodes task output in Effect.

**Example**

```ts
Effect.runPromise(validateTaskOutputEffect(z.string(), "done"));
```

**Signature**

```ts
declare const validateTaskOutputEffect: <S extends StandardSchemaV1>(
  schema: S,
  output: InferInput<S>,
  maxBytes?: number | undefined,
) => Effect.Effect<
  { readonly value: InferOutput<S>; readonly wire: JobWireEnvelope },
  TaskWireFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-validation.ts#L81)

## `task-wire-value-validation.ts`

### validateCanonicalInput

Validates retained input without changing its canonical JSON bytes.

**Throws**

TaskWireValidationError for schema, size, or identity failures.

**Example**

```ts
await validateCanonicalInput(schema, "hello");
```

**Signature**

```ts
declare const validateCanonicalInput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  inputWire?: StandardSchemaV1<InferOutput<S>, InferOutput<S>>,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value-validation.ts#L41)

### validateCanonicalOutput

Validates retained output without changing canonical JSON bytes.

**Throws**

TaskWireValidationError for schema, size, or identity failures.

**Example**

```ts
await validateCanonicalOutput(schema, "done");
```

**Signature**

```ts
declare const validateCanonicalOutput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value-validation.ts#L107)

### validateTaskInput

Validates authored task input and constructs its canonical wire form.

**Throws**

TaskWireValidationError for schema or size failures.

**Example**

```ts
await validateTaskInput(schema, "hello");
```

**Signature**

```ts
declare const validateTaskInput: <S extends StandardSchemaV1>(
  schema: S,
  input: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value-validation.ts#L15)

### validateTaskOutput

Validates task output and constructs its canonical wire form.

**Throws**

TaskWireValidationError for schema or size failures.

**Example**

```ts
await validateTaskOutput(schema, "done");
```

**Signature**

```ts
declare const validateTaskOutput: <S extends StandardSchemaV1>(
  schema: S,
  output: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value-validation.ts#L82)

## `task-wire-value.ts`

### TaskWireErrorCode

**Signature**

```ts
declare const TaskWireErrorCode: TaskWireErrorCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L16)

### TaskWireValidationError

**Signature**

```ts
declare const TaskWireValidationError: typeof TaskWireValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L15)

### decodeJobWire

Decodes a hostile wire envelope into immutable canonical JSON.

**Throws**

TaskWireValidationError for malformed or oversized envelopes.

**Example**

```ts
decodeJobWire({ version: 1, kind: "void" });
```

**Signature**

```ts
declare const decodeJobWire: (envelope: unknown, maxBytes?: number) => JsonValue | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L69)

### encodeJobWire

Encodes a generic jobs wire value with the input byte limit.

**Throws**

TaskWireValidationError for invalid or oversized data.

**Example**

```ts
encodeJobWire({ id: "one" });
```

**Signature**

```ts
declare const encodeJobWire: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L24)

### encodeTaskInput

Encodes submitted task input with input-specific failure codes.

**Throws**

TaskWireValidationError for invalid or oversized input.

**Example**

```ts
encodeTaskInput("hello");
```

**Signature**

```ts
declare const encodeTaskInput: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L34)

### encodeTaskOutput

Encodes handler output with output-specific failure codes.

**Throws**

TaskWireValidationError for invalid or oversized output.

**Example**

```ts
encodeTaskOutput("done");
```

**Signature**

```ts
declare const encodeTaskOutput: (value: unknown, maxBytes?: number) => JobWireEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L50)

### validateCanonicalInput

**Signature**

```ts
declare const validateCanonicalInput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  inputWire?: StandardSchemaV1<InferOutput<S>, InferOutput<S>>,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L96)

### validateCanonicalOutput

**Signature**

```ts
declare const validateCanonicalOutput: <S extends StandardSchemaV1>(
  schema: S,
  canonical: unknown,
  maxBytes?: number,
) => Promise<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L98)

### validateTaskInput

**Signature**

```ts
declare const validateTaskInput: <S extends StandardSchemaV1>(
  schema: S,
  input: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L95)

### validateTaskOutput

**Signature**

```ts
declare const validateTaskOutput: <S extends StandardSchemaV1>(
  schema: S,
  output: InferInput<S>,
  maxBytes?: number,
) => Promise<{ readonly value: InferOutput<S>; readonly wire: JobWireEnvelope }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire-value.ts#L97)

## `task-wire.ts`

### "./task-wire-codec.js" (namespace export)

Re-exports all named exports from the "./task-wire-codec.js" module.

**Signature**

```ts
export * from "./task-wire-codec.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire.ts#L1)

### "./task-wire-validation.js" (namespace export)

Re-exports all named exports from the "./task-wire-validation.js" module.

**Signature**

```ts
export * from "./task-wire-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire.ts#L2)

### TaskWireErrorCode

**Signature**

```ts
declare const TaskWireErrorCode: TaskWireErrorCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire.ts#L5)

### TaskWireFailure

**Signature**

```ts
declare const TaskWireFailure: typeof TaskWireFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire.ts#L3)

### TaskWireValidationError

**Signature**

```ts
declare const TaskWireValidationError: typeof TaskWireValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/task-wire.ts#L4)

## `trigger-validation.ts`

### CopiedTriggerOptions

**Signature**

```ts
declare const CopiedTriggerOptions: CopiedTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L9)

### TriggerValidationError (class)

Invalid trigger or result observation options.

**Example**

```ts
if (error instanceof TriggerValidationError) console.log(error.message);
```

**Signature**

```ts
declare class TriggerValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L13)

### copyTriggerOptions

Synchronous trigger options validator.

**Throws**

TypeError for invalid fields.

**Example**

```ts
copyTriggerOptions({ operationId: "op" });
```

**Signature**

```ts
declare const copyTriggerOptions: (value: unknown) => CopiedTriggerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L44)

### copyTriggerOptionsEffect

Validates and freezes trigger options in Effect.

**Example**

```ts
Effect.runSync(copyTriggerOptionsEffect({ operationId: "op" }));
```

**Signature**

```ts
declare const copyTriggerOptionsEffect: (
  value: unknown,
) => Effect.Effect<CopiedTriggerOptions, TriggerValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L32)

### validateResultOptions

Synchronous result options validator.

**Throws**

TypeError for invalid fields.

**Example**

```ts
validateResultOptions({ timeout: "1 second" });
```

**Signature**

```ts
declare const validateResultOptions: (value: unknown) => RunResultOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L92)

### validateResultOptionsEffect

Validates bounded result observation options in Effect.

**Example**

```ts
Effect.runSync(validateResultOptionsEffect({ timeout: "1 second" }));
```

**Signature**

```ts
declare const validateResultOptionsEffect: (
  value: unknown,
) => Effect.Effect<RunResultOptions, TriggerValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.ts#L79)

## `trigger-validation.types.ts`

### CopiedTriggerOptions (type alias)

Validated trigger options with an optional authored job selector.

**Signature**

```ts
type CopiedTriggerOptions = ServerTriggerOptions & { readonly job?: unknown };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger-validation.types.ts#L3)

## `trigger.types.ts`

### JobDescriptorForThisTask (type alias)

Job reference constrained to target the selected task.

**Signature**

```ts
type JobDescriptorForThisTask<Task extends TaskRefAny = TaskRefAny> = JobRefAny & {
  readonly task: Task;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger.types.ts#L20)

### RunResultOptions (interface)

Options accepted for run result operations.

**Signature**

```ts
export interface RunResultOptions {
  readonly timeout: DurationInput;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger.types.ts#L32)

### ServerTriggerOptions (interface)

Options accepted for server trigger operations.

**Signature**

```ts
export interface ServerTriggerOptions extends TriggerOptions {
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger.types.ts#L15)

### TaskTriggerOptions (interface)

Options accepted for task trigger operations.

**Signature**

```ts
export interface TaskTriggerOptions<
  Task extends TaskRefAny = TaskRefAny,
> extends ServerTriggerOptions {
  readonly job?: JobDescriptorForThisTask<Task>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger.types.ts#L25)

### TriggerOptions (interface)

Browser-safe submission fields. Server-only signals and selectors are separate.

**Signature**

```ts
export interface TriggerOptions {
  readonly operationId?: string;
  readonly idempotencyKey?: string;
  readonly delay?: DurationInput;
  readonly at?: string;
  readonly tags?: readonly string[];
  readonly correlationId?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/jobs/src/trigger.types.ts#L5)

---

# Local history API
Source: https://relkit.dev/docs/api/observability-local

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [inspector](/docs/modules/operations/inspector).

## Public imports

- `@relkit/observability-local` — 27 exports
- `@relkit/observability-local/worker` — 4 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                          | Kind  | Import from                                                         | Example                                                                                                                            |
| -------------------------------------------------------------------------------------------- | ----- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [duckdbDatabaseLayer](/docs/api/observability-local#duckdbdatabaselayer)                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdatabaselayer)                                                                   |
| [DuckdbDatabaseService](/docs/api/observability-local#duckdbdatabaseservice-class)           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdatabaseservice-class)                                                           |
| [duckdbDriverLayer](/docs/api/observability-local#duckdbdriverlayer)                         | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdriverlayer)                                                                     |
| [DuckdbDriverService](/docs/api/observability-local#duckdbdriverservice-class)               | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdbdriverservice-class)                                                             |
| [duckdbError](/docs/api/observability-local#duckdberror)                                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdberror)                                                                           |
| [DuckdbError](/docs/api/observability-local#duckdberror-class)                               | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#duckdberror-class)                                                                     |
| [duckdbWorkerLayer](/docs/api/observability-local#duckdbworkerlayer)                         | Value | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-effect.test.ts#L45)  |
| [DuckdbWorkerService](/docs/api/observability-local#duckdbworkerservice-class)               | Value | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-effect.test.ts#L41)  |
| [LocalLogOrigin](/docs/api/observability-local#locallogorigin-type-alias)                    | Type  | `@relkit/observability-local`                                       | [Module example](/docs/modules/operations/inspector)                                                                               |
| [LocalRecord](/docs/api/observability-local#localrecord-interface)                           | Type  | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localrecord-interface)                                                                 |
| [LocalRecordValidationError](/docs/api/observability-local#localrecordvalidationerror-class) | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localrecordvalidationerror-class)                                                      |
| [LocalWorkerCommand](/docs/api/observability-local#localworkercommand-type-alias)            | Type  | `@relkit/observability-local`, `@relkit/observability-local/worker` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-sigterm.test.ts#L17) |
| [LocalWorkerEffects](/docs/api/observability-local#localworkereffects-interface)             | Type  | `@relkit/observability-local`, `@relkit/observability-local/worker` | [API example](/docs/api/observability-local#localworkereffects-interface)                                                          |
| [LocalWorkerError](/docs/api/observability-local#localworkererror-class)                     | Value | `@relkit/observability-local`, `@relkit/observability-local/worker` | [API example](/docs/api/observability-local#localworkererror-class)                                                                |
| [localWorkerLayer](/docs/api/observability-local#localworkerlayer)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localworkerlayer)                                                                      |
| [LocalWorkerResponse](/docs/api/observability-local#localworkerresponse-interface)           | Type  | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/duckdb-worker-sigterm.test.ts#L18) |
| [LocalWorkerService](/docs/api/observability-local#localworkerservice-class)                 | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#localworkerservice-class)                                                              |
| [makeDuckdbWorkerEffect](/docs/api/observability-local#makeduckdbworkereffect)               | Value | `@relkit/observability-local`                                       | [Module example](/docs/modules/operations/inspector)                                                                               |
| [openDuckdbDatabase](/docs/api/observability-local#openduckdbdatabase)                       | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#openduckdbdatabase)                                                                    |
| [openDuckdbDatabaseEffect](/docs/api/observability-local#openduckdbdatabaseeffect)           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#openduckdbdatabaseeffect)                                                              |
| [recordTime](/docs/api/observability-local#recordtime)                                       | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#recordtime)                                                                            |
| [recordTimeEffect](/docs/api/observability-local#recordtimeeffect)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#recordtimeeffect)                                                                      |
| [startLocalWorker](/docs/api/observability-local#startlocalworker)                           | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#startlocalworker)                                                                      |
| [startLocalWorkerEffect](/docs/api/observability-local#startlocalworkereffect)               | Value | `@relkit/observability-local`, `@relkit/observability-local/worker` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/inspector/tests/history-shutdown-bun.test.ts#L20)            |
| [StoredLocalRecord](/docs/api/observability-local#storedlocalrecord-type-alias)              | Type  | `@relkit/observability-local`                                       | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/tests/import-history.test.ts#L33)        |
| [validateLocalRecord](/docs/api/observability-local#validatelocalrecord)                     | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#validatelocalrecord)                                                                   |
| [validateLocalRecordEffect](/docs/api/observability-local#validatelocalrecordeffect)         | Value | `@relkit/observability-local`                                       | [API example](/docs/api/observability-local#validatelocalrecordeffect)                                                             |

## `index.ts`

Optional native history API; importing this package explicitly selects local storage.

### "./local/duckdb-database-effect.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-database-effect.js" module.

**Signature**

```ts
export * from "./local/duckdb-database-effect.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L3)

### "./local/duckdb-database.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-database.js" module.

**Signature**

```ts
export * from "./local/duckdb-database.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L4)

### "./local/duckdb-driver.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-driver.js" module.

**Signature**

```ts
export * from "./local/duckdb-driver.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L5)

### "./local/duckdb-error.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-error.js" module.

**Signature**

```ts
export * from "./local/duckdb-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L6)

### "./local/duckdb-worker-effect.js" (namespace export)

Re-exports all named exports from the "./local/duckdb-worker-effect.js" module.

**Signature**

```ts
export * from "./local/duckdb-worker-effect.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L7)

### "./local/worker-client.js" (namespace export)

Re-exports all named exports from the "./local/worker-client.js" module.

**Signature**

```ts
export * from "./local/worker-client.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L2)

### "@relkit/observability/local/record" (namespace export)

Re-exports all named exports from the "@relkit/observability/local/record" module.

**Signature**

```ts
export * from "@relkit/observability/local/record";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/index.ts#L8)

## `duckdb-database-effect.ts`

Owns duckdb database effect for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbDatabaseService (class)

Database operations provided for one owned Effect Scope.

**Example**

```ts
const database = yield * DuckdbDatabaseService;
yield * database.flush();
```

**Signature**

```ts
declare class DuckdbDatabaseService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L27)

### duckdbDatabaseLayer

Provides a scoped database service using an injectable DuckdbDriverService.

**Example**

```ts
const program = Effect.gen(function* () {
  return yield* DuckdbDatabaseService;
});
const layer = duckdbDatabaseLayer(root);
```

**Signature**

```ts
declare const duckdbDatabaseLayer: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Layer.Layer<DuckdbDatabaseService, DuckdbError, DuckdbDriverService>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L95)

### openDuckdbDatabaseEffect

Acquires an instance and connection in the caller's Scope, initializes schema,
and returns Effect operations. Scope finalizers close the connection first,
then the instance, including on setup failure or interruption.

**Example**

```ts
const database = yield * openDuckdbDatabaseEffect(root);
yield * database.flush();
```

**Signature**

```ts
declare const openDuckdbDatabaseEffect: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy | undefined,
  redaction?: RedactionPolicy | undefined,
) => Effect.Effect<
  {
    imported: { records: number; malformed: number };
    append: (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>;
    configure: (
      retention: TelemetryLocalRetentionPolicy,
      redaction?: RedactionPolicy,
    ) => Effect.Effect<void, DuckdbError>;
    flush: () => Effect.Effect<void, DuckdbError>;
    list: (
      kind: "logs" | "requests" | "traces",
      input?: ObservabilityQueryRequest | undefined,
    ) => Effect.Effect<
      ObservabilityQueryPage<StoredLocalRecord>,
      DuckdbError | DuckdbQueryError,
      never
    >;
    detail: (
      kind: "request" | "log" | "trace",
      id: string,
    ) => Effect.Effect<
      | {
          log: StoredLocalRecord;
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          request: RequestRecord;
          spans: readonly SpanRecord[];
          roots: readonly SpanNode[];
          continuations: readonly { readonly traceId: string; readonly active: boolean }[];
          records: readonly ObservabilityRecord[];
          counts: {
            readonly records: number;
            readonly spans: number;
            readonly continuations: number;
          };
          incomplete: readonly string[];
          items: ReadonlyArray<never>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | {
          trace: StoredLocalRecord | undefined;
          spans: Array<SpanRecord>;
          records: ReadonlyArray<StoredLocalRecord>;
          items: ReadonlyArray<StoredLocalRecord>;
          nextCursor?: string;
          protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
          version: typeof OBSERVABILITY_QUERY_VERSION;
        }
      | undefined,
      DuckdbError | DuckdbQueryError,
      never
    >;
  },
  DuckdbError,
  Scope | DuckdbDriverService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database-effect.ts#L46)

## `duckdb-database.ts`

Owns duckdb database for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### openDuckdbDatabase

Opens a private DuckDB database and owns its Effect Scope until close.
The scoped Effect implementation contains acquisition and operation logic.

**Throws**

If acquisition, storage, or import fails.

**Example**

```ts
const database = await openDuckdbDatabase(root);
await database.close();
```

**Signature**

```ts
declare const openDuckdbDatabase: (
  root: string,
  configured?: TelemetryLocalRetentionPolicy,
  redaction?: RedactionPolicy,
) => Promise<{
  imported: { records: number; malformed: number };
  append: (
    records: Parameters<
      (records: readonly LocalRecord[]) => Effect.Effect<StoredLocalRecord[], DuckdbError>
    >[0],
  ) => Promise<Array<StoredLocalRecord>>;
  list: (
    kind: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    input?: Parameters<
      (
        kind: "logs" | "requests" | "traces",
        input?: ObservabilityQueryRequest | undefined,
      ) => Effect.Effect<
        ObservabilityQueryPage<StoredLocalRecord>,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[1],
  ) => Promise<ObservabilityQueryPage<StoredLocalRecord>>;
  detail: (
    kind: Parameters<
      (
        kind: "request" | "log" | "trace",
        id: string,
      ) => Effect.Effect<
        | {
            log: StoredLocalRecord;
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            request: RequestRecord;
            spans: readonly SpanRecord[];
            roots: readonly SpanNode[];
            continuations: readonly { readonly traceId: string; readonly active: boolean }[];
            records: readonly ObservabilityRecord[];
            counts: {
              readonly records: number;
              readonly spans: number;
              readonly continuations: number;
            };
            incomplete: readonly string[];
            items: ReadonlyArray<never>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | {
            trace: StoredLocalRecord | undefined;
            spans: Array<SpanRecord>;
            records: ReadonlyArray<StoredLocalRecord>;
            items: ReadonlyArray<StoredLocalRecord>;
            nextCursor?: string;
            protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
            version: typeof OBSERVABILITY_QUERY_VERSION;
          }
        | undefined,
        DuckdbError | DuckdbQueryError,
        never
      >
    >[0],
    id: string,
  ) => Promise<
    | {
        log: StoredLocalRecord;
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        request: RequestRecord;
        spans: readonly SpanRecord[];
        roots: readonly SpanNode[];
        continuations: readonly { readonly traceId: string; readonly active: boolean }[];
        records: readonly ObservabilityRecord[];
        counts: {
          readonly records: number;
          readonly spans: number;
          readonly continuations: number;
        };
        incomplete: readonly string[];
        items: ReadonlyArray<never>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | {
        trace: StoredLocalRecord | undefined;
        spans: Array<SpanRecord>;
        records: ReadonlyArray<StoredLocalRecord>;
        items: ReadonlyArray<StoredLocalRecord>;
        nextCursor?: string;
        protocol: typeof OBSERVABILITY_QUERY_PROTOCOL;
        version: typeof OBSERVABILITY_QUERY_VERSION;
      }
    | undefined
  >;
  configure: (
    value: TelemetryLocalRetentionPolicy,
    nextRedaction?: RedactionPolicy,
  ) => Promise<void>;
  flush: () => Promise<void>;
  close: () => Promise<void>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-database.ts#L27)

## `duckdb-driver.ts`

Owns duckdb driver for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbDriverService (class)

Injectable native DuckDB instance factory.

**Example**

```ts
const driver = yield * DuckdbDriverService;
const instance = yield * driver.create(path);
```

**Signature**

```ts
declare class DuckdbDriverService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-driver.ts#L17)

### duckdbDriverLayer

Live native driver for local observability storage.

**Example**

```ts
const database = yield * openDuckdbDatabaseEffect(root).pipe(Effect.provide(duckdbDriverLayer));
```

**Signature**

```ts
declare const duckdbDriverLayer: Layer.Layer<DuckdbDriverService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-driver.ts#L38)

## `duckdb-error.ts`

Owns duckdb error for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### DuckdbError (class)

Expected local DuckDB IO or schema failure with a stable operation label.

**Example**

```ts
const failure = new DuckdbError({ operation: "connect", message: "failed", cause });
```

**Signature**

```ts
declare class DuckdbError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-error.ts#L14)

### duckdbError

Converts a native DuckDB failure to the local storage error channel.

**Example**

```ts
const error = duckdbError("connect", cause);
```

**Signature**

```ts
declare const duckdbError: <Cause>(operation: string, cause: Cause) => DuckdbError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-error.ts#L30)

## `duckdb-worker-effect.ts`

Composes serialized storage commands behind an injectable worker service.
Its scope owns the explicit database scope until close, failure or interruption.

### DuckdbWorkerService (class)

Injectable command executor whose owner must close its database.

**Signature**

```ts
declare class DuckdbWorkerService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L14)

### duckdbWorkerLayer

Owns the command service and releases native state on every scope exit.

**Signature**

```ts
declare const duckdbWorkerLayer: Layer.Layer<DuckdbWorkerService, never, DuckdbDriverService>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L43)

### makeDuckdbWorkerEffect

**Signature**

```ts
declare const makeDuckdbWorkerEffect: () => Effect.Effect<
  {
    execute: (
      command: LocalWorkerCommand,
    ) => Effect.Effect<
      | void
      | Array<StoredLocalRecord>
      | ObservabilityQueryPage<StoredLocalRecord>
      | { records: number; malformed: number },
      DuckdbError | DuckdbQueryError,
      never
    >;
    close: () => Effect.Effect<void, DuckdbError, never>;
  },
  never,
  DuckdbDriverService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/duckdb-worker-effect.ts#L20)

## `duckdb-worker.ts`

Owns duckdb worker for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

## `worker-client-effect.ts`

Acquires the optional isolated Node worker and exposes shared structural effects.
Its caller owns close; neither record producers nor console logging import it.

### startLocalWorkerEffect

Starts one child without opening a database until the caller sends open.

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-effect.ts#L23)

## `worker-client-service.ts`

Owns worker client service for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### LocalWorkerService (class)

Injectable local worker operations. A Layer owns the worker process until
its scope closes, so callers can substitute a deterministic service in tests.

**Example**

```ts
const program = Effect.gen(function* () {
  const worker = yield* LocalWorkerService;
  return worker.pid;
});
```

**Signature**

```ts
declare class LocalWorkerService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-service.ts#L20)

### localWorkerLayer

Acquires a worker for the Layer scope and releases it on every exit.

**Example**

```ts
const result = await Effect.runPromise(program.pipe(Effect.provide(localWorkerLayer())));
```

**Signature**

```ts
declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer.Layer<LocalWorkerService, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client-service.ts#L38)

## `worker-client.ts`

Owns worker client for the optional local history store.
Shared records and query contracts come from lightweight observability; native
handles and worker lifetimes remain owned by this storage package.

### LocalWorkerEffects

**Signature**

```ts
declare const LocalWorkerEffects: LocalWorkerEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L15)

### LocalWorkerError

**Signature**

```ts
declare const LocalWorkerError: typeof LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L12)

### LocalWorkerService

**Signature**

```ts
declare const LocalWorkerService: typeof LocalWorkerService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L14)

### localWorkerLayer

**Signature**

```ts
declare const localWorkerLayer: (
  onFailure?: (error: Error) => void,
) => Layer<LocalWorkerService, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L14)

### startLocalWorker

Starts a local worker with the existing Promise API.

**Throws**

If process creation fails.

**Example**

```ts
const worker = startLocalWorker();
try {
  await worker.call({ type: "flush" });
} finally {
  await worker.close();
}
```

**Signature**

```ts
declare const startLocalWorker: (onFailure?: (error: Error) => void) => {
  pid: number | undefined;
  call: <T>(command: LocalWorkerCommand) => Promise<T>;
  close: () => Promise<void>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L30)

### startLocalWorkerEffect

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect.Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker-client.ts#L13)

## `worker.ts`

Exposes IPC transport without evaluating the native DuckDB driver in its caller.
The isolated Node worker imports that driver in its own process. Its caller
retains the transport's explicit close operation and physical child identity.

### LocalWorkerCommand

**Signature**

```ts
declare const LocalWorkerCommand: LocalWorkerCommand;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L14)

### LocalWorkerEffects

**Signature**

```ts
declare const LocalWorkerEffects: LocalWorkerEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L12)

### LocalWorkerError

**Signature**

```ts
declare const LocalWorkerError: LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L13)

### startLocalWorkerEffect

**Signature**

```ts
declare const startLocalWorkerEffect: (
  onFailure?: ((error: Error) => void) | undefined,
) => Effect<LocalWorkerEffects, LocalWorkerError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability-local/src/local/worker.ts#L11)

## `types.ts`

Validates diagnostic transport envelopes before any queue, IPC, or storage boundary.

### "./types.types.js" (namespace export)

Re-exports all named exports from the "./types.types.js" module.

**Signature**

```ts
export * from "./types.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L6)

### LocalRecordValidationError (class)

Invalid local record envelope at the persistent storage boundary.

**Example**

```ts
Effect.runSync(
  validateLocalRecordEffect(null).pipe(
    Effect.catchTag("LocalRecordValidationError", (error) => Effect.succeed(error.reason)),
  ),
);
```

**Signature**

```ts
declare class LocalRecordValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L16)

### recordTime

Synchronous compatibility adapter for local record time parsing.

**Example**

```ts
recordTime(logRecord);
```

**Signature**

```ts
declare const recordTime: (record: ObservabilityRecord) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L135)

### recordTimeEffect

Reads the canonical time field for a local record.

**Example**

```ts
Effect.runSync(recordTimeEffect(logRecord));
```

**Signature**

```ts
declare const recordTimeEffect: (
  record: ObservabilityRecord,
) => Effect.Effect<number, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L96)

### validateLocalRecord

Synchronous compatibility adapter for local record validation.

**Throws**

If the envelope or record is invalid.

**Example**

```ts
validateLocalRecord(envelope);
```

**Signature**

```ts
declare const validateLocalRecord: <Input>(value: Input) => asserts value is Input & LocalRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L115)

### validateLocalRecordEffect

Validates a local transport envelope before persistence.

**Example**

```ts
Effect.runSync(validateLocalRecordEffect(envelope));
```

**Signature**

```ts
declare const validateLocalRecordEffect: <Input>(
  value: Input,
) => Effect.Effect<Input & LocalRecord, LocalRecordValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.ts#L54)

## `types.types.ts`

Redacted telemetry envelopes and the diagnostic worker IPC protocol; no storage resources.

### LocalLogOrigin (type alias)

A stable origin assigned to local telemetry records.

**Signature**

```ts
type LocalLogOrigin = "application" | "relkit" | "inspector";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L10)

### LocalRecord (interface)

Transport envelope accepted by the local worker.

**Example**

```ts
const envelope: LocalRecord = { key: "source:1", origin: "application", record };
```

**Signature**

```ts
export interface LocalRecord {
  readonly key: string;
  readonly origin: LocalLogOrigin;
  readonly record: ObservabilityRecord;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L18)

### LocalWorkerCommand (type alias)

Commands sent through the local worker IPC channel.

**Signature**

```ts
type LocalWorkerCommand =
  | {
      readonly type: "open";
      readonly root: string;
      readonly retention?: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "append"; readonly records: readonly LocalRecord[] }
  | {
      readonly type: "query";
      readonly kind: "logs" | "requests" | "traces";
      readonly query: ObservabilityQueryRequest;
    }
  | { readonly type: "detail"; readonly kind: "log" | "request" | "trace"; readonly id: string }
  | {
      readonly type: "retention";
      readonly retention: TelemetryLocalRetentionPolicy;
      readonly redaction?: RedactionPolicy;
    }
  | { readonly type: "flush" | "close" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L31)

### LocalWorkerResponse (interface)

A worker reply carrying a value or a safe error code and message.

**Signature**

```ts
export interface LocalWorkerResponse {
  readonly id: number;
  readonly fatal?: boolean;
  readonly value?: Schema.Json;
  readonly error?: string;
  readonly code?: ObservabilityQueryError["code"];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L53)

### StoredLocalRecord (type alias)

A persisted model record with its local cursor and origin.

**Signature**

```ts
type StoredLocalRecord = ObservabilityRecord & {
  readonly cursor: string;
  readonly origin: LocalLogOrigin;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/types.types.ts#L25)

## `worker-client-error.ts`

Typed IPC failures shared with tooling; no worker or database is acquired here.

### LocalWorkerError (class)

A local worker creation, IPC, timeout, or response failure.

**Example**

```ts
Effect.runPromise(
  worker
    .call(command)
    .pipe(Effect.catchTag("LocalWorkerError", (error) => Effect.succeed(error.reason))),
);
```

**Signature**

```ts
declare class LocalWorkerError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L13)

### WorkerTransportError (class)

Failure raised by the IPC transport before mapping to the Effect channel.

**Signature**

```ts
declare class WorkerTransportError { constructor(
    readonly reason: "send" | "timeout" | "response",
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L25)

### workerFailure

Maps an IPC failure to a tagged worker error without losing query codes.

**Signature**

```ts
declare const workerFailure: <Failure>(
  error: Failure,
  reason: LocalWorkerError["reason"],
) => LocalWorkerError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client-error.ts#L35)

## `worker-client.types.ts`

Structural worker authority borrowed by telemetry producers without native dependencies.

### LocalWorkerEffects (interface)

Effect operations for a live local telemetry worker process.
The owning Layer or caller must close the worker after its final call.

**Example**

```ts
const worker = Effect.runSync(startLocalWorkerEffect());
await Effect.runPromise(worker.close());
```

**Signature**

```ts
export interface LocalWorkerEffects {
  readonly pid: number | undefined;
  /** @param command - Worker IPC command. @returns Its response or a tagged worker error. */
  readonly call: (
    command: LocalWorkerCommand,
  ) => Effect.Effect<Schema.Json | undefined, LocalWorkerError>;
  /** @returns Completion after the worker process and pending calls are released. */
  readonly close: () => Effect.Effect<void, LocalWorkerError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/observability/src/local/worker-client.types.ts#L14)

---

# Provider authoring API
Source: https://relkit.dev/docs/api/provider

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [provider authoring](/docs/modules/integrations/provider-authoring).

## Public imports

- `@relkit/provider` — 88 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                       | Kind  | Import from        | Example                                                                                                                    |
| --------------------------------------------------------------------------------------------------------- | ----- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| [BindingValueRef](/docs/api/provider#bindingvalueref-type-alias)                                          | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [BindingValueType](/docs/api/provider#bindingvaluetype-type-alias)                                        | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [createBindingValueRef](/docs/api/provider#createbindingvalueref)                                         | Value | `@relkit/provider` | [API example](/docs/api/provider#createbindingvalueref)                                                                    |
| [createBindingValueRefEffect](/docs/api/provider#createbindingvaluerefeffect)                             | Value | `@relkit/provider` | [API example](/docs/api/provider#createbindingvaluerefeffect)                                                              |
| [defineConnectionContract](/docs/api/provider#defineconnectioncontract)                                   | Value | `@relkit/provider` | [API example](/docs/api/provider#defineconnectioncontract)                                                                 |
| [defineConnectionContractEffect](/docs/api/provider#defineconnectioncontracteffect)                       | Value | `@relkit/provider` | [API example](/docs/api/provider#defineconnectioncontracteffect)                                                           |
| [defineInfrastructureProviderSource](/docs/api/provider#defineinfrastructureprovidersource-1)             | Value | `@relkit/provider` | [API example](/docs/api/provider#defineinfrastructureprovidersource-1)                                                     |
| [defineInfrastructureProviderSourceEffect](/docs/api/provider#defineinfrastructureprovidersourceeffect-1) | Value | `@relkit/provider` | [API example](/docs/api/provider#defineinfrastructureprovidersourceeffect-1)                                               |
| [defineIntegrationReference](/docs/api/provider#defineintegrationreference)                               | Value | `@relkit/provider` | [API example](/docs/api/provider#defineintegrationreference)                                                               |
| [defineIntegrationReferenceEffect](/docs/api/provider#defineintegrationreferenceeffect)                   | Value | `@relkit/provider` | [API example](/docs/api/provider#defineintegrationreferenceeffect)                                                         |
| [defineLocalProviderSource](/docs/api/provider#definelocalprovidersource-1)                               | Value | `@relkit/provider` | [API example](/docs/api/provider#definelocalprovidersource-1)                                                              |
| [defineLocalProviderSourceEffect](/docs/api/provider#definelocalprovidersourceeffect-1)                   | Value | `@relkit/provider` | [API example](/docs/api/provider#definelocalprovidersourceeffect-1)                                                        |
| [defineLocalRecipeReference](/docs/api/provider#definelocalrecipereference)                               | Value | `@relkit/provider` | [API example](/docs/api/provider#definelocalrecipereference)                                                               |
| [defineLocalRecipeReferenceEffect](/docs/api/provider#definelocalrecipereferenceeffect)                   | Value | `@relkit/provider` | [API example](/docs/api/provider#definelocalrecipereferenceeffect)                                                         |
| [defineProviderAccess](/docs/api/provider#defineprovideraccess)                                           | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovideraccess)                                                                     |
| [defineProviderAccessEffect](/docs/api/provider#defineprovideraccesseffect)                               | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovideraccesseffect)                                                               |
| [defineProviderAdapter](/docs/api/provider#defineprovideradapter)                                         | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovideradapter)                                                                    |
| [defineProviderAdapterEffect](/docs/api/provider#defineprovideradaptereffect)                             | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovideradaptereffect)                                                              |
| [DefineProviderAdapterOptions](/docs/api/provider#defineprovideradapteroptions-interface)                 | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [defineProviderBehavior](/docs/api/provider#defineproviderbehavior)                                       | Value | `@relkit/provider` | [API example](/docs/api/provider#defineproviderbehavior)                                                                   |
| [defineProviderBehaviorEffect](/docs/api/provider#defineproviderbehavioreffect)                           | Value | `@relkit/provider` | [API example](/docs/api/provider#defineproviderbehavioreffect)                                                             |
| [defineProviderCapability](/docs/api/provider#defineprovidercapability)                                   | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovidercapability)                                                                 |
| [defineProviderCapabilityEffect](/docs/api/provider#defineprovidercapabilityeffect)                       | Value | `@relkit/provider` | [API example](/docs/api/provider#defineprovidercapabilityeffect)                                                           |
| [defineProviderFeature](/docs/api/provider#defineproviderfeature)                                         | Value | `@relkit/provider` | [API example](/docs/api/provider#defineproviderfeature)                                                                    |
| [defineProviderFeatureEffect](/docs/api/provider#defineproviderfeatureeffect)                             | Value | `@relkit/provider` | [API example](/docs/api/provider#defineproviderfeatureeffect)                                                              |
| [InfrastructureProviderSource](/docs/api/provider#infrastructureprovidersource-type-alias)                | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [IntegrationReference](/docs/api/provider#integrationreference-type-alias)                                | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [isBindingValueRef](/docs/api/provider#isbindingvalueref)                                                 | Value | `@relkit/provider` | [API example](/docs/api/provider#isbindingvalueref)                                                                        |
| [isBindingValueRefEffect](/docs/api/provider#isbindingvaluerefeffect)                                     | Value | `@relkit/provider` | [API example](/docs/api/provider#isbindingvaluerefeffect)                                                                  |
| [LocalProviderSource](/docs/api/provider#localprovidersource-type-alias)                                  | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [NormalizedProviderAdapter](/docs/api/provider#normalizedprovideradapter-interface)                       | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [NormalizedProviderBinding](/docs/api/provider#normalizedproviderbinding-type-alias)                      | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [NormalizedProviderProfiles](/docs/api/provider#normalizedproviderprofiles-interface)                     | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [NormalizedProviderSource](/docs/api/provider#normalizedprovidersource-type-alias)                        | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [normalizeProviderBinding](/docs/api/provider#normalizeproviderbinding)                                   | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeproviderbinding)                                                                 |
| [normalizeProviderBindingEffect](/docs/api/provider#normalizeproviderbindingeffect)                       | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeproviderbindingeffect)                                                           |
| [NormalizeProviderBindingOptions](/docs/api/provider#normalizeproviderbindingoptions-interface)           | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [normalizeProviderProfiles](/docs/api/provider#normalizeproviderprofiles)                                 | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeproviderprofiles)                                                                |
| [normalizeProviderProfilesEffect](/docs/api/provider#normalizeproviderprofileseffect)                     | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeproviderprofileseffect)                                                          |
| [normalizeProviderSource](/docs/api/provider#normalizeprovidersource-1)                                   | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeprovidersource-1)                                                                |
| [normalizeProviderSourceEffect](/docs/api/provider#normalizeprovidersourceeffect-1)                       | Value | `@relkit/provider` | [API example](/docs/api/provider#normalizeprovidersourceeffect-1)                                                          |
| [observeProvider](/docs/api/provider#observeprovider)                                                     | Value | `@relkit/provider` | [API example](/docs/api/provider#observeprovider)                                                                          |
| [PROVIDER_PROTOCOL_VERSION](/docs/api/provider#provider_protocol_version)                                 | Value | `@relkit/provider` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/version-cohort.test.ts#L30)                   |
| [ProviderAccess](/docs/api/provider#provideraccess-type-alias)                                            | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderAdapter](/docs/api/provider#provideradapter-type-alias)                                          | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderBehavior](/docs/api/provider#providerbehavior-type-alias)                                        | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderBindingResolutionCode](/docs/api/provider#providerbindingresolutioncode-type-alias)              | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderBindingResolutionError](/docs/api/provider#providerbindingresolutionerror-class)                 | Value | `@relkit/provider` | [API example](/docs/api/provider#providerbindingresolutionerror-class)                                                     |
| [ProviderBindingResolutionFailure](/docs/api/provider#providerbindingresolutionfailure-class)             | Value | `@relkit/provider` | [API example](/docs/api/provider#providerbindingresolutionfailure-class)                                                   |
| [ProviderBindingSource](/docs/api/provider#providerbindingsource-type-alias)                              | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [providerCalculation](/docs/api/provider#providercalculation)                                             | Value | `@relkit/provider` | [API example](/docs/api/provider#providercalculation)                                                                      |
| [ProviderCapability](/docs/api/provider#providercapability-type-alias)                                    | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionContract](/docs/api/provider#providerconnectioncontract-type-alias)                    | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionDescriptor](/docs/api/provider#providerconnectiondescriptor-interface)                 | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionField](/docs/api/provider#providerconnectionfield-interface)                           | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionFieldInput](/docs/api/provider#providerconnectionfieldinput-interface)                 | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionFields](/docs/api/provider#providerconnectionfields-type-alias)                        | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionValue](/docs/api/provider#providerconnectionvalue-type-alias)                          | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionValueMode](/docs/api/provider#providerconnectionvaluemode-type-alias)                  | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderConnectionValues](/docs/api/provider#providerconnectionvalues-type-alias)                        | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderError](/docs/api/provider#providererror-type-alias)                                              | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderFeature](/docs/api/provider#providerfeature-type-alias)                                          | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderFeatureMismatchError](/docs/api/provider#providerfeaturemismatcherror-class)                     | Value | `@relkit/provider` | [API example](/docs/api/provider#providerfeaturemismatcherror-class)                                                       |
| [ProviderFeatureMismatchFailure](/docs/api/provider#providerfeaturemismatchfailure-class)                 | Value | `@relkit/provider` | [API example](/docs/api/provider#providerfeaturemismatchfailure-class)                                                     |
| [ProviderInput](/docs/api/provider#providerinput-type-alias)                                              | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderLocalRecipeReference](/docs/api/provider#providerlocalrecipereference-interface)                 | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderOperation](/docs/api/provider#provideroperation-type-alias)                                      | Type  | `@relkit/provider` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/provider/tests/effect-telemetry.test.ts#L53)         |
| [ProviderProfileSelection](/docs/api/provider#providerprofileselection-interface)                         | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderProfileSelectionError](/docs/api/provider#providerprofileselectionerror-class)                   | Value | `@relkit/provider` | [API example](/docs/api/provider#providerprofileselectionerror-class)                                                      |
| [ProviderProfileSelectionFailure](/docs/api/provider#providerprofileselectionfailure-class)               | Value | `@relkit/provider` | [API example](/docs/api/provider#providerprofileselectionfailure-class)                                                    |
| [ProviderProfileSelectionSource](/docs/api/provider#providerprofileselectionsource-type-alias)            | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderProtocolVersion](/docs/api/provider#providerprotocolversion-type-alias)                          | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderSourceInput](/docs/api/provider#providersourceinput-type-alias)                                  | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderTelemetry](/docs/api/provider#providertelemetry-class)                                           | Value | `@relkit/provider` | [API example](/docs/api/provider#providertelemetry-class)                                                                  |
| [ProviderTelemetryLive](/docs/api/provider#providertelemetrylive)                                         | Value | `@relkit/provider` | [API example](/docs/api/provider#providertelemetrylive)                                                                    |
| [ProviderTelemetryService](/docs/api/provider#providertelemetryservice-interface)                         | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [ProviderValidationError](/docs/api/provider#providervalidationerror-class)                               | Value | `@relkit/provider` | [API example](/docs/api/provider#providervalidationerror-class)                                                            |
| [resolveProviderConnection](/docs/api/provider#resolveproviderconnection)                                 | Value | `@relkit/provider` | [API example](/docs/api/provider#resolveproviderconnection)                                                                |
| [resolveProviderConnectionEffect](/docs/api/provider#resolveproviderconnectioneffect)                     | Value | `@relkit/provider` | [API example](/docs/api/provider#resolveproviderconnectioneffect)                                                          |
| [ResolveProviderConnectionOptions](/docs/api/provider#resolveproviderconnectionoptions-interface)         | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [runProvider](/docs/api/provider#runprovider)                                                             | Value | `@relkit/provider` | [API example](/docs/api/provider#runprovider)                                                                              |
| [RuntimeProviderContext](/docs/api/provider#runtimeprovidercontext-interface)                             | Type  | `@relkit/provider` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/engine/tests/provider-registry-runtime.test.ts#L16)  |
| [RuntimeProviderGeneration](/docs/api/provider#runtimeprovidergeneration-interface)                       | Type  | `@relkit/provider` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/engine/tests/provider-registry-runtime.test.ts#L504) |
| [RuntimeProviderIntegration](/docs/api/provider#runtimeproviderintegration-interface)                     | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |
| [RuntimeProviderRegistration](/docs/api/provider#runtimeproviderregistration-interface)                   | Type  | `@relkit/provider` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/engine/tests/provider-registry-runtime.test.ts#L505) |
| [selectProviderProfile](/docs/api/provider#selectproviderprofile)                                         | Value | `@relkit/provider` | [API example](/docs/api/provider#selectproviderprofile)                                                                    |
| [selectProviderProfileEffect](/docs/api/provider#selectproviderprofileeffect)                             | Value | `@relkit/provider` | [API example](/docs/api/provider#selectproviderprofileeffect)                                                              |
| [SelectProviderProfileOptions](/docs/api/provider#selectproviderprofileoptions-interface)                 | Type  | `@relkit/provider` | [Module example](/docs/modules/integrations/provider-authoring)                                                            |

## `adapter-builder.ts`

### DefineProviderAdapterOptions

**Signature**

```ts
declare const DefineProviderAdapterOptions: DefineProviderAdapterOptions<
  Capability,
  AdapterId,
  Connection,
  Behavior
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/adapter-builder.ts#L20)

### defineProviderAdapter

Define and validate a pure provider adapter synchronously.

**Throws**

TypeError for unknown fields, invalid features, or invalid identifiers.

**Example**

```ts
defineProviderAdapter(options);
```

**Signature**

```ts
declare const defineProviderAdapter: <
  const Capability extends ProviderCapability,
  const AdapterId extends string,
  const Connection extends ProviderConnectionValues,
  const Behavior extends ProviderBehavior,
>(
  options: DefineProviderAdapterOptions<Capability, AdapterId, Connection, Behavior>,
) => BuiltProviderAdapter<Capability, AdapterId, Connection, Behavior>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/adapter-builder.ts#L70)

### defineProviderAdapterEffect

Define and validate a pure provider adapter in an Effect.

**Example**

```ts
Effect.runSync(defineProviderAdapterEffect(options));
```

**Signature**

```ts
declare const defineProviderAdapterEffect: <
  const Capability extends ProviderCapability,
  const AdapterId extends string,
  const Connection extends ProviderConnectionValues,
  const Behavior extends ProviderBehavior,
>(
  options: DefineProviderAdapterOptions<Capability, AdapterId, Connection, Behavior>,
) => Effect.Effect<
  BuiltProviderAdapter<Capability, AdapterId, Connection, Behavior>,
  ProviderError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/adapter-builder.ts#L26)

## `adapter-builder.types.ts`

### BuiltProviderAdapter (type alias)

Adapter produced from a typed builder input.

**Signature**

```ts
type BuiltProviderAdapter<
  Capability extends ProviderCapability,
  AdapterId extends string,
  Connection extends ProviderConnectionValues,
  Behavior extends ProviderBehavior,
> = ProviderAdapter<Capability, AdapterId, Connection, Behavior>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/adapter-builder.types.ts#L28)

### DefineProviderAdapterOptions (interface)

Inputs accepted by a provider adapter builder.

**Signature**

```ts
export interface DefineProviderAdapterOptions<
  Capability extends ProviderCapability,
  AdapterId extends string,
  Connection extends ProviderConnectionValues,
  Behavior extends ProviderBehavior,
> {
  readonly integration: IntegrationReference;
  readonly capability: Capability;
  readonly adapterId: AdapterId;
  readonly connectionContract: ProviderConnectionContract;
  readonly connection: Connection;
  readonly behavior: Behavior;
  readonly features?: readonly ProviderFeature<Capability["id"]>[];
  readonly localRecipe?: ProviderLocalRecipeReference;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/adapter-builder.types.ts#L12)

## `binding-normalization.ts`

### NormalizeProviderBindingOptions

**Signature**

```ts
declare const NormalizeProviderBindingOptions: NormalizeProviderBindingOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-normalization.ts#L15)

### ProviderFeatureMismatchError

**Signature**

```ts
declare const ProviderFeatureMismatchError: typeof ProviderFeatureMismatchError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-normalization.ts#L14)

### normalizeProviderBinding

Normalize a selected binding for synchronous callers.

**Throws**

ProviderFeatureMismatchError when required features are absent.

**Example**

```ts
normalizeProviderBinding(selection, { descriptorId: "cart" });
```

**Signature**

```ts
declare const normalizeProviderBinding: (
  selection: ProviderProfileSelection,
  options: NormalizeProviderBindingOptions,
) => NormalizedProviderBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-normalization.ts#L40)

### normalizeProviderBindingEffect

Normalize a selected binding in an Effect after checking features.

**Example**

```ts
Effect.runSync(normalizeProviderBindingEffect(selection, { descriptorId: "cart" }));
```

**Signature**

```ts
declare const normalizeProviderBindingEffect: (
  selection: ProviderProfileSelection,
  options: NormalizeProviderBindingOptions,
) => Effect.Effect<NormalizedProviderBinding, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-normalization.ts#L22)

## `binding-normalization.types.ts`

Required features for a logical descriptor's selected provider.

### NormalizeProviderBindingOptions (interface)

Required features for a logical descriptor's selected provider.

**Signature**

```ts
export interface NormalizeProviderBindingOptions {
  readonly descriptorId: string;
  readonly requiredFeatures?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-normalization.types.ts#L2)

## `binding-resolution.ts`

### ProviderBindingResolutionCode

**Signature**

```ts
declare const ProviderBindingResolutionCode: ProviderBindingResolutionCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L18)

### ProviderBindingResolutionError

**Signature**

```ts
declare const ProviderBindingResolutionError: typeof ProviderBindingResolutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L17)

### ProviderConnectionDescriptor

**Signature**

```ts
declare const ProviderConnectionDescriptor: ProviderConnectionDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L20)

### ResolveProviderConnectionOptions

**Signature**

```ts
declare const ResolveProviderConnectionOptions: ResolveProviderConnectionOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L21)

### resolveProviderConnection

Resolve provider connection values synchronously for legacy callers.

**Throws**

ProviderBindingResolutionError for missing or conflicting values; TypeError for invalid input.

**Example**

```ts
resolveProviderConnection(adapter, { profile: "default" });
```

**Signature**

```ts
declare const resolveProviderConnection: (
  adapter: ProviderConnectionDescriptor,
  options: ResolveProviderConnectionOptions,
) => Readonly<Record<string, JsonValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L47)

### resolveProviderConnectionEffect

Resolve a provider's connection values in an Effect with tagged failures.

**Example**

```ts
Effect.runSync(resolveProviderConnectionEffect(adapter, { profile: "default" }));
```

**Signature**

```ts
declare const resolveProviderConnectionEffect: (
  adapter: ProviderConnectionDescriptor,
  options: ResolveProviderConnectionOptions,
) => Effect.Effect<Readonly<Record<string, JsonValue>>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.ts#L29)

## `binding-resolution.types.ts`

### ProviderConnectionDescriptor (interface)

Minimal adapter shape accepted by connection resolution.

**Signature**

```ts
export interface ProviderConnectionDescriptor {
  readonly capability: Readonly<{ readonly id: string }>;
  readonly connectionContract: Readonly<{
    readonly fields: Readonly<Record<string, ProviderConnectionField>>;
  }>;
  readonly connection: ProviderConnectionValues;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.types.ts#L14)

### ResolveProviderConnectionOptions (interface)

Inputs for resolving authored, local, infrastructure, and named values.

**Signature**

```ts
export interface ResolveProviderConnectionOptions {
  readonly profile: string;
  readonly bindingId?: string;
  readonly local?: Readonly<Record<string, JsonValue>>;
  readonly infrastructure?: Readonly<Record<string, JsonValue>>;
  readonly values?: Readonly<Record<string, JsonValue>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-resolution.types.ts#L5)

## `binding-values.ts`

### createBindingValueRef

Create a binding-local value reference synchronously.

**Throws**

TypeError for an invalid name.

**Example**

```ts
createBindingValueRef("CACHE_URL", "secret-string");
```

**Signature**

```ts
declare const createBindingValueRef: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-values.ts#L45)

### createBindingValueRefEffect

Create a binding-local named value reference in an Effect.

**Example**

```ts
Effect.runSync(createBindingValueRefEffect("CACHE_URL", "secret-string"));
```

**Signature**

```ts
declare const createBindingValueRefEffect: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => Effect.Effect<BindingValueRef<Name, Value, Type>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-values.ts#L26)

### isBindingValueRef

Check an exact binding-local reference synchronously.

**Example**

```ts
isBindingValueRef(value);
```

**Signature**

```ts
declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-values.ts#L81)

### isBindingValueRefCore

Pure predicate shared by observed provider operations.

**Example**

```ts
isBindingValueRefCore({ kind: "binding-value-ref", name: "URL", type: "string", sensitive: false });
```

**Signature**

```ts
declare const isBindingValueRefCore: (value: unknown) => value is BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-values.ts#L89)

### isBindingValueRefEffect

Check an exact binding-local reference in an Effect.

**Example**

```ts
Effect.runSync(isBindingValueRefEffect(value));
```

**Signature**

```ts
declare const isBindingValueRefEffect: (value: unknown) => Effect.Effect<boolean, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/binding-values.ts#L70)

## `dependency-preflight.service.ts`

Validates only selected capability/phase requirements before readiness.
The Layer captures read-only resolution; checks resolve adapters from projects
and peers from adapters, aggregate missing/version diagnostics, and never install.

### "./dependency-preflight.types.js" (namespace export)

Re-exports all named exports from the "./dependency-preflight.types.js" module.

**Signature**

```ts
export * from "./dependency-preflight.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L153)

### DependencyResolutionFailure

**Signature**

```ts
declare const DependencyResolutionFailure: typeof DependencyResolutionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L151)

### DependencySource

**Signature**

```ts
declare const DependencySource: typeof DependencySource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L148)

### DependencySourceLive

**Signature**

```ts
declare const DependencySourceLive: Layer.Layer<DependencySource, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L148)

### SelectedDependencies (class)

Shared startup/compiler validator; each call retains its own selection and roots.

**Signature**

```ts
declare class SelectedDependencies
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L127)

### SelectedDependenciesLayer

Domain Layer leaves its native source replaceable without changing check behavior.

**Signature**

```ts
declare const SelectedDependenciesLayer: Layer.Layer<SelectedDependencies, never, DependencySource>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L138)

### SelectedDependenciesLive

Live compiler/runtime composition has no CLI/compiler or concrete SDK dependency.

**Signature**

```ts
declare const SelectedDependenciesLive: Layer.Layer<SelectedDependencies, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L144)

### SelectedDependencyFailure

**Signature**

```ts
declare const SelectedDependencyFailure: typeof SelectedDependencyFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L150)

### SelectedDependencyInitializationFailure

**Signature**

```ts
declare const SelectedDependencyInitializationFailure: typeof SelectedDependencyInitializationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L156)

### checkIntegrationDependencies

**Signature**

```ts
declare const checkIntegrationDependencies: (
  plan: RuntimeIntegrationPlan,
  options: {
    readonly projectRoot: string;
    readonly phase: IntegrationDependencyPhase;
    readonly manager?: DependencyPackageManager;
  },
) => Effect.Effect<
  Array<Array<InstalledPackageIdentity>>,
  DependencyResolutionFailure | SelectedDependencyFailure,
  SelectedDependencies
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L154)

### initializeIntegration

**Signature**

```ts
declare const initializeIntegration: <Module>(
  packageName: string,
  load: () => Promise<Module>,
) => Effect.Effect<Module, SelectedDependencyInitializationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/dependency-preflight.service.ts#L155)

## `identity-builders.ts`

### defineIntegrationReference

Define a static integration identity synchronously.

**Throws**

TypeError for invalid identifiers.

**Example**

```ts
defineIntegrationReference("redis");
```

**Signature**

```ts
declare const defineIntegrationReference: <const Id extends string>(
  integrationId: Id,
) => IntegrationReference<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L102)

### defineIntegrationReferenceEffect

Define a static integration identity in an Effect.

**Example**

```ts
Effect.runSync(defineIntegrationReferenceEffect("redis"));
```

**Signature**

```ts
declare const defineIntegrationReferenceEffect: <const Id extends string>(
  integrationId: Id,
) => Effect.Effect<IntegrationReference<Id>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L83)

### defineLocalRecipeReference

Define versioned local-recipe provenance synchronously.

**Throws**

TypeError for invalid versions or identifiers.

**Example**

```ts
defineLocalRecipeReference(redis, "redis-docker", 1);
```

**Signature**

```ts
declare const defineLocalRecipeReference: (
  integration: IntegrationReference,
  recipeId: string,
  recipeVersion: number,
) => ProviderLocalRecipeReference;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L140)

### defineLocalRecipeReferenceEffect

Define versioned local-recipe provenance in an Effect.

**Example**

```ts
Effect.runSync(defineLocalRecipeReferenceEffect(redis, "redis-docker", 1));
```

**Signature**

```ts
declare const defineLocalRecipeReferenceEffect: (
  integration: IntegrationReference,
  recipeId: string,
  recipeVersion: number,
) => Effect.Effect<ProviderLocalRecipeReference, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L114)

### defineProviderCapability

Define a stable capability synchronously.

**Throws**

TypeError for invalid identifiers.

**Example**

```ts
defineProviderCapability("cache");
```

**Signature**

```ts
declare const defineProviderCapability: <const Id extends string>(id: Id) => ProviderCapability<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L38)

### defineProviderCapabilityEffect

Define a stable provider capability in an Effect.

**Example**

```ts
Effect.runSync(defineProviderCapabilityEffect("cache"));
```

**Signature**

```ts
declare const defineProviderCapabilityEffect: <const Id extends string>(
  id: Id,
) => Effect.Effect<ProviderCapability<Id>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L21)

### defineProviderFeature

Define an adapter feature synchronously.

**Throws**

TypeError for invalid identifiers.

**Example**

```ts
defineProviderFeature(cache, "atomicIncrement");
```

**Signature**

```ts
declare const defineProviderFeature: <
  const Capability extends ProviderCapability,
  const Id extends string,
>(
  capability: Capability,
  id: Id,
) => ProviderFeature<Capability["id"], Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L72)

### defineProviderFeatureEffect

Define an adapter feature in an Effect.

**Example**

```ts
Effect.runSync(defineProviderFeatureEffect(cache, "atomicIncrement"));
```

**Signature**

```ts
declare const defineProviderFeatureEffect: <
  const Capability extends ProviderCapability,
  const Id extends string,
>(
  capability: Capability,
  id: Id,
) => Effect.Effect<ProviderFeature<Capability["id"], Id>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/identity-builders.ts#L47)

## `index.ts`

### "./binding-normalization.js" (namespace export)

Re-exports all named exports from the "./binding-normalization.js" module.

**Signature**

```ts
export * from "./binding-normalization.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L2)

### "./binding-resolution.js" (namespace export)

Re-exports all named exports from the "./binding-resolution.js" module.

**Signature**

```ts
export * from "./binding-resolution.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L1)

### "./profile-normalization.js" (namespace export)

Re-exports all named exports from the "./profile-normalization.js" module.

**Signature**

```ts
export * from "./profile-normalization.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L9)

### "./protocol-builders.js" (namespace export)

Re-exports all named exports from the "./protocol-builders.js" module.

**Signature**

```ts
export * from "./protocol-builders.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L10)

### "./protocol.js" (namespace export)

Re-exports all named exports from the "./protocol.js" module.

**Signature**

```ts
export * from "./protocol.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L11)

### "./protocol.types.js" (namespace export)

Re-exports all named exports from the "./protocol.types.js" module.

**Signature**

```ts
export * from "./protocol.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L12)

### "./provider-observability.js" (namespace export)

Re-exports all named exports from the "./provider-observability.js" module.

**Signature**

```ts
export * from "./provider-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L22)

### "./runtime.types.js" (namespace export)

Re-exports all named exports from the "./runtime.types.js" module.

**Signature**

```ts
export * from "./runtime.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L13)

### ProviderBindingResolutionFailure

**Signature**

```ts
declare const ProviderBindingResolutionFailure: typeof ProviderBindingResolutionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L27)

### ProviderFeatureMismatchFailure

**Signature**

```ts
declare const ProviderFeatureMismatchFailure: typeof ProviderFeatureMismatchFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L26)

### ProviderProfileSelectionFailure

**Signature**

```ts
declare const ProviderProfileSelectionFailure: typeof ProviderProfileSelectionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L25)

### ProviderValidationError

**Signature**

```ts
declare const ProviderValidationError: typeof ProviderValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L24)

### createBindingValueRef

**Signature**

```ts
declare const createBindingValueRef: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => BindingValueRef<Name, Value, Type>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L4)

### createBindingValueRefEffect

**Signature**

```ts
declare const createBindingValueRefEffect: <
  const Name extends string,
  Value = unknown,
  const Type extends BindingValueType = BindingValueType,
>(
  name: Name,
  type: Type,
) => Effect<BindingValueRef<Name, Value, Type>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L5)

### defineInfrastructureProviderSource

**Signature**

```ts
declare const defineInfrastructureProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => InfrastructureProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L17)

### defineInfrastructureProviderSourceEffect

**Signature**

```ts
declare const defineInfrastructureProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => Effect<InfrastructureProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L18)

### defineLocalProviderSource

**Signature**

```ts
declare const defineLocalProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L15)

### defineLocalProviderSourceEffect

**Signature**

```ts
declare const defineLocalProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => Effect<LocalProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L16)

### isBindingValueRef

**Signature**

```ts
declare const isBindingValueRef: (value: unknown) => value is BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L6)

### isBindingValueRefEffect

**Signature**

```ts
declare const isBindingValueRefEffect: (value: unknown) => Effect<boolean, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L7)

### normalizeProviderSource

**Signature**

```ts
declare const normalizeProviderSource: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L19)

### normalizeProviderSourceEffect

**Signature**

```ts
declare const normalizeProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => Effect<NormalizedProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/index.ts#L20)

## `profile-normalization.ts`

### NormalizedProviderProfiles

**Signature**

```ts
declare const NormalizedProviderProfiles: NormalizedProviderProfiles<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L28)

### ProviderInput

**Signature**

```ts
declare const ProviderInput: ProviderInput<Binding>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L29)

### ProviderProfileSelection

**Signature**

```ts
declare const ProviderProfileSelection: ProviderProfileSelection<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L30)

### ProviderProfileSelectionError

**Signature**

```ts
declare const ProviderProfileSelectionError: typeof ProviderProfileSelectionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L26)

### ProviderProfileSelectionSource

**Signature**

```ts
declare const ProviderProfileSelectionSource: ProviderProfileSelectionSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L31)

### SelectProviderProfileOptions

**Signature**

```ts
declare const SelectProviderProfileOptions: SelectProviderProfileOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L32)

### normalizeProviderProfiles

Normalize provider profiles for synchronous callers.

**Throws**

TypeError when a profile is empty, duplicated, or mismatched.

**Example**

```ts
normalizeProviderProfiles(cache, adapter);
```

**Signature**

```ts
declare const normalizeProviderProfiles: <Adapter extends ProviderAdapter>(
  capability: ProviderCapability,
  input: ProviderInput<ProviderSourceInput<Adapter>>,
) => NormalizedProviderProfiles<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L56)

### normalizeProviderProfilesEffect

Normalize a direct source or named profile map in an Effect.

**Example**

```ts
Effect.runSync(normalizeProviderProfilesEffect(cache, adapter));
```

**Signature**

```ts
declare const normalizeProviderProfilesEffect: <Adapter extends ProviderAdapter>(
  capability: ProviderCapability,
  input: ProviderInput<ProviderSourceInput<Adapter>>,
) => Effect.Effect<NormalizedProviderProfiles<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L40)

### selectProviderProfile

Select a provider profile synchronously for legacy callers.

**Throws**

ProviderProfileSelectionError for ambiguity or an unknown profile.

**Example**

```ts
selectProviderProfile(profiles, { descriptorId: "cart" });
```

**Signature**

```ts
declare const selectProviderProfile: <Adapter extends ProviderAdapter>(
  normalized: NormalizedProviderProfiles<Adapter>,
  options: SelectProviderProfileOptions,
) => ProviderProfileSelection<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L109)

### selectProviderProfileEffect

Select a descriptor, default, or sole provider profile in an Effect.

**Example**

```ts
Effect.runSync(selectProviderProfileEffect(profiles, { descriptorId: "cart" }));
```

**Signature**

```ts
declare const selectProviderProfileEffect: <Adapter extends ProviderAdapter>(
  normalized: NormalizedProviderProfiles<Adapter>,
  options: SelectProviderProfileOptions,
) => Effect.Effect<ProviderProfileSelection<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.ts#L93)

## `profile-normalization.types.ts`

### NormalizedProviderProfiles (interface)

Immutable provider sources keyed by normalized profile name.

**Signature**

```ts
export interface NormalizedProviderProfiles<Adapter extends ProviderAdapter = ProviderAdapter> {
  readonly kind: "normalized-provider-profiles";
  readonly capability: string;
  readonly profiles: Readonly<Record<string, NormalizedProviderSource<Adapter>>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L9)

### ProviderInput (type alias)

A direct binding or a map of named provider profiles.

**Signature**

```ts
type ProviderInput<Binding> = Binding | Readonly<Record<string, Binding>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L7)

### ProviderProfileSelection (interface)

Selected profile with the matching normalized binding.

**Signature**

```ts
export interface ProviderProfileSelection<Adapter extends ProviderAdapter = ProviderAdapter> {
  readonly capability: string;
  readonly profile: string;
  readonly source: ProviderProfileSelectionSource;
  readonly binding: NormalizedProviderSource<Adapter>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L17)

### ProviderProfileSelectionSource (type alias)

How a profile was selected.

**Signature**

```ts
type ProviderProfileSelectionSource = "descriptor" | "default" | "sole";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L15)

### ProviderProfileSource (type alias)

Source accepted by profile normalization.

**Signature**

```ts
type ProviderProfileSource<Adapter extends ProviderAdapter> = ProviderInput<
  ProviderSourceInput<Adapter>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L24)

### SelectProviderProfileOptions (interface)

Descriptor and optional application-level default profile selection.

**Signature**

```ts
export interface SelectProviderProfileOptions {
  readonly descriptorId: string;
  readonly profile?: string;
  readonly defaultProfile?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/profile-normalization.types.ts#L28)

## `protocol.ts`

Current provider descriptor protocol version.

### PROVIDER_PROTOCOL_VERSION

Current provider descriptor protocol version.

**Signature**

```ts
declare const PROVIDER_PROTOCOL_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.ts#L2)

## `protocol.types.ts`

### BindingValueRef (type alias)

Opaque reference to a binding-local runtime value.

**Signature**

```ts
type BindingValueRef<
  Name extends string = string,
  Value = unknown,
  Type extends BindingValueType = BindingValueType,
> = Readonly<{
  kind: "binding-value-ref";
  name: Name;
  type: Type;
  sensitive: Type extends "secret-string" ? true : false;
  __value?: Value;
}> &
  ProviderProtocolType<"binding-value-ref">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L18)

### BindingValueType (type alias)

Supported named binding value kinds.

**Signature**

```ts
type BindingValueType = "string" | "number" | "boolean" | "port" | "url" | "json" | "secret-string";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L14)

### InfrastructureProviderSource (type alias)

Adapter and infrastructure materialization request.

**Signature**

```ts
type InfrastructureProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "provider-infrastructure-source";
  adapter: Adapter;
  integration: IntegrationReference;
  options: JsonValue;
  access?: ProviderAccess;
}> &
  ProviderProtocolType<"infrastructure-source">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L134)

### IntegrationReference (type alias)

Static integration identity without an import path.

**Signature**

```ts
type IntegrationReference<Id extends string = string> = Readonly<{
  kind: "integration-reference";
  integrationId: Id;
}> &
  ProviderProtocolType<"integration-reference">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L95)

### LocalProviderSource (type alias)

Adapter wrapped with its declared local recipe.

**Signature**

```ts
type LocalProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "provider-local-source";
  adapter: Adapter;
}> &
  ProviderProtocolType<"local-source">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L127)

### NormalizedProviderAdapter (interface)

Runtime-facing projection of an adapter's immutable fields.

**Signature**

```ts
export interface NormalizedProviderAdapter {
  readonly integrationId: string;
  readonly adapterId: string;
  readonly protocolVersion: ProviderProtocolVersion;
  readonly behavior: JsonValue;
  readonly connectionContract: ProviderConnectionFields;
  readonly connection: ProviderConnectionValues;
  readonly features: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L176)

### NormalizedProviderBinding (type alias)

Selected provider binding consumed by the runtime.

**Signature**

```ts
type NormalizedProviderBinding = Readonly<{
  kind: "provider-binding";
  capability: string;
  profile: string;
  adapter: NormalizedProviderAdapter;
  source: ProviderBindingSource;
  local?: ProviderLocalRecipeReference;
  access?: JsonValue;
}> &
  ProviderProtocolType<"normalized-binding">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L187)

### NormalizedProviderSource (type alias)

Frozen source descriptor consumed by profile normalization.

**Signature**

```ts
type NormalizedProviderSource<Adapter extends ProviderAdapter = ProviderAdapter> = Readonly<{
  kind: "normalized-provider-source";
  adapter: Adapter;
  source: ProviderBindingSource;
  local?: ProviderLocalRecipeReference;
  access?: JsonValue;
}> &
  ProviderProtocolType<"normalized-source">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L166)

### ProviderAccess (type alias)

Access policy metadata for an infrastructure source.

**Signature**

```ts
type ProviderAccess<Value extends JsonValue = JsonValue> = Readonly<{
  kind: "provider-access";
  value: Value;
}> &
  ProviderProtocolType<"access">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L88)

### ProviderAdapter (type alias)

Immutable adapter descriptor for one integration capability.

**Signature**

```ts
type ProviderAdapter<
  Capability extends ProviderCapability = ProviderCapability,
  AdapterId extends string = string,
  Connection extends ProviderConnectionValues = ProviderConnectionValues,
  Behavior extends ProviderBehavior = ProviderBehavior,
> = Readonly<{
  kind: "provider-adapter";
  protocolVersion: ProviderProtocolVersion;
  integration: IntegrationReference;
  capability: Capability;
  adapterId: AdapterId;
  connectionContract: ProviderConnectionContract;
  connection: Connection;
  behavior: Behavior;
  features: readonly ProviderFeature<Capability["id"]>[];
  localRecipe?: ProviderLocalRecipeReference;
}> &
  ProviderProtocolType<"adapter">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L107)

### ProviderBehavior (type alias)

Immutable behavioral metadata separate from connection values.

**Signature**

```ts
type ProviderBehavior<Value extends JsonValue = JsonValue> = Readonly<{
  kind: "provider-behavior";
  value: Value;
}> &
  ProviderProtocolType<"behavior">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L81)

### ProviderBindingSource (type alias)

Source mode selected for a normalized provider binding.

**Signature**

```ts
type ProviderBindingSource =
  | Readonly<{ kind: "connected" }>
  | Readonly<{ kind: "local-only" }>
  | Readonly<{
      kind: "infrastructure";
      integrationId: string;
      options: JsonValue;
    }>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L149)

### ProviderCapability (type alias)

Nominal capability identity shared by features and adapters.

**Signature**

```ts
type ProviderCapability<Id extends string = string> = Readonly<{
  kind: "provider-capability";
  id: Id;
}> &
  ProviderProtocolType<"capability">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L32)

### ProviderConnectionContract (type alias)

Nominal connection contract for a provider adapter.

**Signature**

```ts
type ProviderConnectionContract<
  Fields extends ProviderConnectionFields = ProviderConnectionFields,
> = Readonly<{
  kind: "provider-connection-contract";
  fields: Fields;
}> &
  ProviderProtocolType<"connection-contract">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L72)

### ProviderConnectionField (interface)

Normalized field contract with explicit defaults.

**Signature**

```ts
export interface ProviderConnectionField {
  readonly required: boolean;
  readonly sensitive: boolean;
  readonly authoredValue: ProviderConnectionValueMode;
  readonly default?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L61)

### ProviderConnectionFieldInput (interface)

Authoring options for one connection field.

**Signature**

```ts
export interface ProviderConnectionFieldInput {
  readonly required?: boolean;
  readonly sensitive?: boolean;
  readonly authoredValue?: ProviderConnectionValueMode;
  readonly default?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L53)

### ProviderConnectionFields (type alias)

Named connection fields in an adapter contract.

**Signature**

```ts
type ProviderConnectionFields = Readonly<Record<string, ProviderConnectionField>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L69)

### ProviderConnectionValue (type alias)

Literal JSON or a named binding value reference.

**Signature**

```ts
type ProviderConnectionValue = JsonValue | BindingValueRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L102)

### ProviderConnectionValueMode (type alias)

Whether authored connection values are fixed or allow outputs to replace them.

**Signature**

```ts
type ProviderConnectionValueMode = "fixed" | "fallback";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L50)

### ProviderConnectionValues (type alias)

Authored connection field values.

**Signature**

```ts
type ProviderConnectionValues = Readonly<Record<string, ProviderConnectionValue>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L104)

### ProviderFeature (type alias)

Nominal feature identity within one provider capability.

**Signature**

```ts
type ProviderFeature<Capability extends string = string, Id extends string = string> = Readonly<{
  kind: "provider-feature";
  capability: Capability;
  id: Id;
}> &
  ProviderProtocolType<"feature">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L39)

### ProviderLocalRecipeReference (interface)

Versioned local recipe provenance for an adapter.

**Signature**

```ts
export interface ProviderLocalRecipeReference {
  readonly integrationId: string;
  readonly recipeId: string;
  readonly recipeVersion: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L159)

### ProviderProtocolVersion (type alias)

Current version accepted by provider descriptors.

**Signature**

```ts
type ProviderProtocolVersion = typeof PROVIDER_PROTOCOL_VERSION;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L11)

### ProviderSourceInput (type alias)

Direct adapter or one source wrapper.

**Signature**

```ts
type ProviderSourceInput<Adapter extends ProviderAdapter = ProviderAdapter> =
  Adapter | LocalProviderSource<Adapter> | InfrastructureProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/protocol.types.ts#L145)

## `provider-compat-errors.ts`

### ProviderBindingResolutionError (class)

Synchronous connection error retained for compatibility.

**Example**

```ts
throw new ProviderBindingResolutionError(
  "MISSING_CONNECTION_VALUE",
  "cache.default",
  "url",
  "is required",
);
```

**Signature**

```ts
declare class ProviderBindingResolutionError {
  constructor(
    code: ProviderBindingResolutionCode,
    bindingId: string,
    field: string,
    reason: string,
  );
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L75)

### code (property)

**Signature**

```ts
readonly code: ProviderBindingResolutionCode
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L76)

### bindingId (property)

**Signature**

```ts
readonly bindingId: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L77)

### field (property)

**Signature**

```ts
readonly field: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L78)

### reason (property)

**Signature**

```ts
readonly reason: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L79)

### ProviderFeatureMismatchError (class)

Synchronous missing-feature error retained for compatibility.

**Example**

```ts
throw new ProviderFeatureMismatchError("cache", "default", "cart", ["atomic"]);
```

**Signature**

```ts
declare class ProviderFeatureMismatchError {
  constructor(
    capability: string,
    profile: string,
    descriptorId: string,
    features: readonly string[],
  );
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L44)

### code (property)

**Signature**

```ts
readonly code: "MISSING_PROVIDER_FEATURE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L45)

### capability (property)

**Signature**

```ts
readonly capability: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L46)

### profile (property)

**Signature**

```ts
readonly profile: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L47)

### descriptorId (property)

**Signature**

```ts
readonly descriptorId: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L48)

### features (property)

**Signature**

```ts
readonly features: ReadonlyArray<string>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L49)

### ProviderInputError (class)

Internal marker for expected provider input failures.

**Example**

```ts
throw new ProviderInputError("Invalid provider ID");
```

**Signature**

```ts
declare class ProviderInputError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L6)

### ProviderProfileSelectionError (class)

Synchronous profile selection error retained for compatibility.

**Example**

```ts
throw new ProviderProfileSelectionError(
  "UNKNOWN_PROVIDER_PROFILE",
  "cache",
  "cart",
  [],
  "selected unknown profile",
);
```

**Signature**

```ts
declare class ProviderProfileSelectionError {
  constructor(
    code: ProviderProfileSelectionError["code"],
    capability: string,
    descriptorId: string,
    profiles: readonly string[],
    reason: string,
  );
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L10)

### code (property)

**Signature**

```ts
readonly code: "AMBIGUOUS_PROVIDER_PROFILE" | "UNKNOWN_PROVIDER_PROFILE"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L11)

### capability (property)

**Signature**

```ts
readonly capability: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L12)

### descriptorId (property)

**Signature**

```ts
readonly descriptorId: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L13)

### profiles (property)

**Signature**

```ts
readonly profiles: ReadonlyArray<string>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L14)

### reason (property)

**Signature**

```ts
readonly reason: string
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-compat-errors.ts#L15)

## `provider-errors.ts`

### ProviderBindingResolutionCode

**Signature**

```ts
declare const ProviderBindingResolutionCode: ProviderBindingResolutionCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L7)

### ProviderBindingResolutionFailure (class)

Tagged connection failure in the Effect error channel.

**Example**

```ts
Effect.catchTag("ProviderBindingResolutionError", (error) => Effect.logWarning(error.message));
```

**Signature**

```ts
declare class ProviderBindingResolutionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L46)

### ProviderFeatureMismatchFailure (class)

Tagged missing-feature failure in the Effect error channel.

**Example**

```ts
Effect.catchTag("ProviderFeatureMismatchError", (error) => Effect.logWarning(error.message));
```

**Signature**

```ts
declare class ProviderFeatureMismatchFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L33)

### ProviderProfileSelectionFailure (class)

Tagged profile failure in the Effect error channel.

**Example**

```ts
Effect.catchTag("ProviderProfileSelectionError", (error) => Effect.logWarning(error.message));
```

**Signature**

```ts
declare class ProviderProfileSelectionFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L20)

### ProviderValidationCode

**Signature**

```ts
declare const ProviderValidationCode: ProviderValidationCode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L8)

### ProviderValidationError (class)

Tagged invalid provider input, with a stable category and safe message.

**Example**

```ts
Effect.catchTag("ProviderValidationError", (error) => Effect.logWarning(error.message));
```

**Signature**

```ts
declare class ProviderValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.ts#L13)

## `provider-errors.types.ts`

Stable validation codes for provider authoring failures.

### ProviderBindingResolutionCode (type alias)

Stable codes for connection resolution failures.

**Signature**

```ts
type ProviderBindingResolutionCode =
  "CONFLICTING_CONNECTION_VALUE" | "MISSING_CONNECTION_VALUE" | "UNKNOWN_CONNECTION_OUTPUT";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.types.ts#L5)

### ProviderValidationCode (type alias)

Stable validation codes for provider authoring failures.

**Signature**

```ts
type ProviderValidationCode =
  "INVALID_ID" | "INVALID_DESCRIPTOR" | "INVALID_CONNECTION" | "INVALID_PROFILE";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-errors.types.ts#L2)

## `provider-observability.ts`

### ProviderError

**Signature**

```ts
declare const ProviderError: ProviderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L20)

### ProviderOperation

**Signature**

```ts
declare const ProviderOperation: ProviderOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L21)

### ProviderTelemetry (class)

Injectable telemetry for provider operations.

**Example**

```ts
Effect.provide(defineProviderCapabilityEffect("cache"), ProviderTelemetryLive);
```

**Signature**

```ts
declare class ProviderTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L27)

### ProviderTelemetryLive

Live spans and metrics for provider operations.

**Example**

```ts
Effect.runSync(Effect.provide(defineProviderCapabilityEffect("cache"), ProviderTelemetryLive));
```

**Signature**

```ts
declare const ProviderTelemetryLive: Layer.Layer<ProviderTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L34)

### ProviderTelemetryService

**Signature**

```ts
declare const ProviderTelemetryService: ProviderTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L22)

### observeProvider

Records a fixed provider operation with substitutable telemetry.

**Example**

```ts
observeProvider("capability.define", Effect.succeed("cache"));
```

**Signature**

```ts
declare const observeProvider: <A, E, R>(
  operation: ProviderOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L46)

### providerCalculation

Runs synchronous provider logic inside Effect and tags known validation failures.

**Example**

```ts
providerCalculation("INVALID_ID", () => "cache");
```

**Signature**

```ts
declare const providerCalculation: <A>(
  code: ProviderValidationError["code"],
  evaluate: () => A,
) => Effect.Effect<A, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L83)

### runProvider

Runs a public synchronous compatibility adapter.

**Throws**

A TypeError for general validation, a named domain error, or an unexpected defect.

**Example**

```ts
runProvider(Effect.succeed("cache"));
```

**Signature**

```ts
declare const runProvider: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.ts#L142)

## `provider-observability.types.ts`

Names provider operations and typed failures for substitutable instrumentation that preserves Effect result channels.

### ProviderError (type alias)

Expected tagged failures from provider operations.

**Signature**

```ts
type ProviderError =
  | ProviderValidationError
  | ProviderProfileSelectionFailure
  | ProviderFeatureMismatchFailure
  | ProviderBindingResolutionFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.types.ts#L33)

### ProviderOperation (type alias)

Fixed names for provider operations; never derived from user input.

**Signature**

```ts
type ProviderOperation =
  | "dependency.resolve"
  | "dependency.manager"
  | "dependency.check"
  | "dependency.initialize"
  | "binding-value.create"
  | "binding-value.is-ref"
  | "binding.resolve"
  | "binding.normalize"
  | "profile.normalize"
  | "profile.select"
  | "source.local"
  | "source.infrastructure"
  | "source.normalize"
  | "capability.define"
  | "feature.define"
  | "connection.define"
  | "behavior.define"
  | "access.define"
  | "integration.define"
  | "recipe.define"
  | "adapter.define";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.types.ts#L10)

### ProviderTelemetryService (interface)

Substitutable operation telemetry used by public Effect functions.

**Signature**

```ts
export interface ProviderTelemetryService {
  /** Observe an operation without changing its result or failure.
   * @param operation - Fixed operation name.
   * @param effect - Effect to observe.
   * @returns The same success and error channels.
   * @example telemetry.observe("capability.define", Effect.succeed("cache"));
   */
  readonly observe: <A, E, R>(
    operation: ProviderOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/provider-observability.types.ts#L39)

## `runtime.types.ts`

### RuntimeProviderContext (interface)

Binding data passed to a runtime provider generation.

**Signature**

```ts
export interface RuntimeProviderContext {
  readonly generationId: string;
  readonly bindingId: string;
  readonly capability: string;
  readonly profile: string;
  readonly executionModel?: "task" | "legacy-function";
  readonly behavior: JsonValue;
  readonly connection: Readonly<Record<string, JsonValue>>;
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/runtime.types.ts#L8)

### RuntimeProviderGeneration (interface)

Acquired runtime value and optional readiness and disposal hooks.

**Signature**

```ts
export interface RuntimeProviderGeneration {
  readonly value: unknown;
  readonly ready?: () => MaybePromise<void>;
  readonly readiness?: () => MaybePromise<void>;
  readonly release?: () => MaybePromise<void>;
  readonly dispose?: () => MaybePromise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/runtime.types.ts#L20)

### RuntimeProviderIntegration (interface)

Collection of runtime provider registrations owned by an integration.

**Signature**

```ts
export interface RuntimeProviderIntegration<IntegrationId extends string = string> {
  readonly kind: "runtime-integration";
  readonly integrationId: IntegrationId;
  readonly registrations: readonly RuntimeProviderRegistration[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/runtime.types.ts#L34)

### RuntimeProviderRegistration (interface)

Registration factory for one runtime provider capability.

**Signature**

```ts
export interface RuntimeProviderRegistration extends RuntimeIntegrationRegistrationMetadata {
  readonly create: (context: RuntimeProviderContext) => MaybePromise<RuntimeProviderGeneration>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/runtime.types.ts#L29)

## `source-normalization.ts`

### defineInfrastructureProviderSource

Add an infrastructure source synchronously.

**Throws**

TypeError when the adapter is invalid or has no local recipe.

**Example**

```ts
defineInfrastructureProviderSource(adapter, integration, {});
```

**Signature**

```ts
declare const defineInfrastructureProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => InfrastructureProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L91)

### defineInfrastructureProviderSourceEffect

Add an infrastructure source in an Effect.

**Example**

```ts
Effect.runSync(defineInfrastructureProviderSourceEffect(adapter, integration, {}));
```

**Signature**

```ts
declare const defineInfrastructureProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
  integration: IntegrationReference,
  options: JsonValue,
  access?: ProviderAccess,
) => Effect.Effect<InfrastructureProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L69)

### defineLocalProviderSource

Add an adapter's local recipe for synchronous callers.

**Throws**

TypeError when the adapter is invalid or has no local recipe.

**Example**

```ts
defineLocalProviderSource(adapter);
```

**Signature**

```ts
declare const defineLocalProviderSource: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => LocalProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L48)

### defineLocalProviderSourceEffect

Add an adapter's local recipe without starting it.

**Example**

```ts
Effect.runSync(defineLocalProviderSourceEffect(adapter));
```

**Signature**

```ts
declare const defineLocalProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  adapter: Adapter,
) => Effect.Effect<LocalProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L34)

### normalizeProviderSource

Normalize a provider source synchronously.

**Throws**

TypeError for invalid descriptors, nested wrappers, or missing values.

**Example**

```ts
normalizeProviderSource(adapter);
```

**Signature**

```ts
declare const normalizeProviderSource: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L137)

### normalizeProviderSourceCore

Pure normalization shared by observed source and profile operations.

**Throws**

TypeError for invalid descriptors or missing required values.

**Example**

```ts
normalizeProviderSourceCore(adapter);
```

**Signature**

```ts
declare const normalizeProviderSourceCore: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => NormalizedProviderSource<Adapter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L148)

### normalizeProviderSourceEffect

Normalize any provider source in an Effect.

**Example**

```ts
Effect.runSync(normalizeProviderSourceEffect(adapter));
```

**Signature**

```ts
declare const normalizeProviderSourceEffect: <const Adapter extends ProviderAdapter>(
  input: ProviderSourceInput<Adapter>,
) => Effect.Effect<NormalizedProviderSource<Adapter>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/source-normalization.ts#L123)

## `value-builders.ts`

### defineConnectionContract

Define connection fields synchronously.

**Throws**

TypeError for invalid or duplicate fields.

**Example**

```ts
defineConnectionContract({ url: { sensitive: true } });
```

**Signature**

```ts
declare const defineConnectionContract: (
  fields: Readonly<Record<string, ProviderConnectionFieldInput>>,
) => ProviderConnectionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L56)

### defineConnectionContractEffect

Define connection fields in an Effect with deterministic key order.

**Example**

```ts
Effect.runSync(defineConnectionContractEffect({ url: { sensitive: true } }));
```

**Signature**

```ts
declare const defineConnectionContractEffect: (
  fields: Readonly<Record<string, ProviderConnectionFieldInput>>,
) => Effect.Effect<ProviderConnectionContract, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L23)

### defineProviderAccess

Define immutable access metadata synchronously.

**Throws**

TypeError for invalid JSON.

**Example**

```ts
defineProviderAccess({ actions: ["cache:read"] });
```

**Signature**

```ts
declare const defineProviderAccess: <const Value extends JsonValue>(
  value: Value,
) => ProviderAccess<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L110)

### defineProviderAccessEffect

Define immutable access metadata in an Effect.

**Example**

```ts
Effect.runSync(defineProviderAccessEffect({ actions: ["cache:read"] }));
```

**Signature**

```ts
declare const defineProviderAccessEffect: <const Value extends JsonValue>(
  value: Value,
) => Effect.Effect<ProviderAccess<Value>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L93)

### defineProviderBehavior

Define immutable provider behavior synchronously.

**Throws**

TypeError for invalid JSON.

**Example**

```ts
defineProviderBehavior({ keyPrefix: "cart" });
```

**Signature**

```ts
declare const defineProviderBehavior: <const Value extends JsonValue>(
  value: Value,
) => ProviderBehavior<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L83)

### defineProviderBehaviorEffect

Define immutable provider behavior in an Effect.

**Example**

```ts
Effect.runSync(defineProviderBehaviorEffect({ keyPrefix: "cart" }));
```

**Signature**

```ts
declare const defineProviderBehaviorEffect: <const Value extends JsonValue>(
  value: Value,
) => Effect.Effect<ProviderBehavior<Value>, ProviderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/provider/src/value-builders.ts#L66)

---

# Local providers API
Source: https://relkit.dev/docs/api/providers-local

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [local providers](/docs/modules/integrations/local-providers).

## Public imports

- `@relkit/providers-local` — 217 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                       | Kind  | Import from               | Example                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------- | ----- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AgentStateStore](/docs/api/providers-local#agentstatestore-interface)                                    | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L143)                   |
| [applyRetry](/docs/api/providers-local#applyretry)                                                        | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-retry.test.ts#L49)                                |
| [assertActive](/docs/api/providers-local#assertactive)                                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [assertContainedPath](/docs/api/providers-local#assertcontainedpath)                                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [assertTime](/docs/api/providers-local#asserttime)                                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [byteLength](/docs/api/providers-local#bytelength)                                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [calculateRetryDelay](/docs/api/providers-local#calculateretrydelay)                                      | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-retry.test.ts#L21)                                |
| [checkpoint](/docs/api/providers-local#checkpoint)                                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [classifyFailure](/docs/api/providers-local#classifyfailure)                                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [clone](/docs/api/providers-local#clone)                                                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [CompiledSchedule](/docs/api/providers-local#compiledschedule-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [compileSchedule](/docs/api/providers-local#compileschedule-1)                                            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-scheduler.test.ts#L10)                            |
| [createAgentStateProviderFromStore](/docs/api/providers-local#createagentstateproviderfromstore)          | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/fixture.ts#L43)                    |
| [createEphemeralDelivery](/docs/api/providers-local#createephemeraldelivery)                              | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/events-ephemeral.test.ts#L53)                          |
| [createEventAdmin](/docs/api/providers-local#createeventadmin)                                            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/events-admin.test.ts#L45)                              |
| [createEventDelivery](/docs/api/providers-local#createeventdelivery)                                      | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/events-delivery.test.ts#L44)                           |
| [createEventLog](/docs/api/providers-local#createeventlog)                                                | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/events-log.test.ts#L13)                                |
| [createEventLogPaths](/docs/api/providers-local#createeventlogpaths)                                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [createEventRouter](/docs/api/providers-local#createeventrouter)                                          | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/events-admin.test.ts#L17)                              |
| [createJobAdmin](/docs/api/providers-local#createjobadmin)                                                | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-admin.test.ts#L31)                                |
| [createJobQueue](/docs/api/providers-local#createjobqueue)                                                | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/engine/tests/server-runtime/background-observation-fixture.ts#L18)           |
| [createJobStore](/docs/api/providers-local#createjobstore-1)                                              | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/engine/tests/server-runtime/background-observation-fixture.ts#L17)           |
| [createLocalAgentStateProvider](/docs/api/providers-local#createlocalagentstateprovider)                  | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/agent-state-failure/continuation-recovery.case.ts#L82) |
| [createLocalBucketProvider](/docs/api/providers-local#createlocalbucketprovider)                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [createLocalBucketProviderForTest](/docs/api/providers-local#createlocalbucketproviderfortest)            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/local.ts#L8)                                            |
| [createLocalCacheInspector](/docs/api/providers-local#createlocalcacheinspector)                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [createLocalCacheKey](/docs/api/providers-local#createlocalcachekey)                                      | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/cache.test.ts#L19)                                     |
| [createLocalCacheProvider](/docs/api/providers-local#createlocalcacheprovider)                            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/cache.test.ts#L7)                                      |
| [createLocalCacheProviderForTest](/docs/api/providers-local#createlocalcacheprovider)                     | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/cache.test.ts#L7)                                      |
| [createLocalEventProvider](/docs/api/providers-local#createlocaleventprovider)                            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/event-publication.test.ts#L11)                                      |
| [createLocalJobProvider](/docs/api/providers-local#createlocaljobprovider)                                | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/jobs-native-projection.test.ts#L42)                       |
| [createLocalObservabilityProvider](/docs/api/providers-local#createlocalobservabilityprovider)            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [createLocalRealtimeProvider](/docs/api/providers-local#createlocalrealtimeprovider)                      | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/realtime.test.ts#L11)                                  |
| [createRealtimeProviderFromStore](/docs/api/providers-local#createrealtimeproviderfromstore)              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [createScheduler](/docs/api/providers-local#createscheduler-1)                                            | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-scheduler.test.ts#L38)                            |
| [DEFAULT_BUCKET_PAGE_SIZE](/docs/api/providers-local#default_bucket_page_size)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [DEFAULT_EPHEMERAL_CAPACITY](/docs/api/providers-local#default_ephemeral_capacity)                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [DurableEventDeliveryResult](/docs/api/providers-local#eventdeliveryresult-interface)                     | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [emptyAgentState](/docs/api/providers-local#emptyagentstate)                                              | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/effect/agent-state-read-errors.test.ts#L16)            |
| [emptyPartition](/docs/api/providers-local#emptypartition)                                                | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [emptyRealtimeState](/docs/api/providers-local#emptyrealtimestate)                                        | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/effect/fixtures.ts#L17)                                |
| [encodeBucketKey](/docs/api/providers-local#encodebucketkey)                                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [encodedBytes](/docs/api/providers-local#encodedbytes)                                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EPHEMERAL_DELIVERY_CAPABILITIES](/docs/api/providers-local#ephemeral_delivery_capabilities)              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EphemeralDelivery](/docs/api/providers-local#ephemeraldelivery-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EphemeralDeliveryResult](/docs/api/providers-local#ephemeraldeliveryresult-interface)                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EphemeralDeliverySnapshot](/docs/api/providers-local#ephemeraldeliverysnapshot-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EVENT_ADMIN_PROTOCOL](/docs/api/providers-local#event_admin_protocol)                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EVENT_ADMIN_VERSION](/docs/api/providers-local#event_admin_version)                                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EVENT_DELIVERY_CAPABILITIES](/docs/api/providers-local#event_delivery_capabilities)                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EVENT_DELIVERY_VERSION](/docs/api/providers-local#event_delivery_version)                                | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EVENT_LOG_VERSION](/docs/api/providers-local#event_log_version)                                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdmin](/docs/api/providers-local#eventadmin-interface)                                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminAction](/docs/api/providers-local#eventadminaction-type-alias)                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminActionContract](/docs/api/providers-local#eventadminactioncontract-interface)                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminActionOutcome](/docs/api/providers-local#eventadminactionoutcome-type-alias)                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminActionRecord](/docs/api/providers-local#eventadminactionrecord-interface)                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminActionRequest](/docs/api/providers-local#eventadminactionrequest-interface)                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminActionSink](/docs/api/providers-local#eventadminactionsink-type-alias)                         | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminError](/docs/api/providers-local#eventadminerror-class)                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminMode](/docs/api/providers-local#eventadminmode-type-alias)                                     | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminOptions](/docs/api/providers-local#eventadminoptions-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventAdminVersion](/docs/api/providers-local#eventadminversion-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventContract](/docs/api/providers-local#eventcontract-interface)                                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventContractInput](/docs/api/providers-local#eventcontractinput-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeadLetterContract](/docs/api/providers-local#eventdeadlettercontract-interface)                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDelivery](/docs/api/providers-local#eventdelivery-interface)                                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryBinding](/docs/api/providers-local#eventdeliverybinding-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryBoundary](/docs/api/providers-local#eventdeliveryboundary-type-alias)                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryContract](/docs/api/providers-local#eventdeliverycontract-interface)                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryLedgerRecord](/docs/api/providers-local#eventdeliveryledgerrecord-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryOptions](/docs/api/providers-local#eventdeliveryoptions-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryRecord](/docs/api/providers-local#eventdeliveryrecord-interface)                            | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliveryResult](/docs/api/providers-local#eventdeliveryresult-interface-1)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventDeliverySnapshot](/docs/api/providers-local#eventdeliverysnapshot-interface)                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventFanoutResult](/docs/api/providers-local#eventfanoutresult-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLog](/docs/api/providers-local#eventlog-interface)                                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogBoundary](/docs/api/providers-local#eventlogboundary-type-alias)                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogInput](/docs/api/providers-local#eventloginput-type-alias)                                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogOptions](/docs/api/providers-local#eventlogoptions-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogPaths](/docs/api/providers-local#eventlogpaths-type-alias)                                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogRecord](/docs/api/providers-local#eventlogrecord-interface)                                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogSnapshot](/docs/api/providers-local#eventlogsnapshot-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventLogStateError](/docs/api/providers-local#eventlogstateerror-class)                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventPublicationContract](/docs/api/providers-local#eventpublicationcontract-interface)                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventQueryContract](/docs/api/providers-local#eventquerycontract-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventQueryRequest](/docs/api/providers-local#eventqueryrequest-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRetryRequest](/docs/api/providers-local#eventretryrequest-type-alias)                               | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouter](/docs/api/providers-local#eventrouter-interface)                                            | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterInput](/docs/api/providers-local#eventrouterinput-type-alias)                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterOptions](/docs/api/providers-local#eventrouteroptions-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterRouteOptions](/docs/api/providers-local#eventrouterrouteoptions-interface)                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterSnapshot](/docs/api/providers-local#eventroutersnapshot-interface)                            | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterStateError](/docs/api/providers-local#eventrouterstateerror-class)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventRouterTrigger](/docs/api/providers-local#eventroutertrigger-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventTriggerCapabilityContract](/docs/api/providers-local#eventtriggercapabilitycontract-interface)      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventTriggerContract](/docs/api/providers-local#eventtriggercontract-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventTriggerSnapshot](/docs/api/providers-local#eventtriggersnapshot-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [EventVersioned](/docs/api/providers-local#eventversioned-interface)                                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JOB_ADMIN_PROTOCOL](/docs/api/providers-local#job_admin_protocol)                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JOB_ADMIN_VERSION](/docs/api/providers-local#job_admin_version)                                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JOB_QUEUE_STATES](/docs/api/providers-local#job_queue_states)                                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobActionContract](/docs/api/providers-local#jobactioncontract-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobActionRequest](/docs/api/providers-local#jobactionrequest-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdmin](/docs/api/providers-local#jobadmin-interface)                                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminAction](/docs/api/providers-local#jobadminaction-type-alias)                                     | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminActionOutcome](/docs/api/providers-local#jobadminactionoutcome-type-alias)                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminActionRecord](/docs/api/providers-local#jobadminactionrecord-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminActionSink](/docs/api/providers-local#jobadminactionsink-type-alias)                             | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminError](/docs/api/providers-local#jobadminerror-class)                                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminMode](/docs/api/providers-local#jobadminmode-type-alias)                                         | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminOptions](/docs/api/providers-local#jobadminoptions-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobAdminVersion](/docs/api/providers-local#jobadminversion-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobCancelRequest](/docs/api/providers-local#jobcancelrequest-type-alias)                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobDeadLetterRequest](/docs/api/providers-local#jobdeadletterrequest-type-alias)                         | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobFailureKind](/docs/api/providers-local#jobfailurekind-type-alias)                                     | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobFailureMetadata](/docs/api/providers-local#jobfailuremetadata-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobFailureOutcome](/docs/api/providers-local#jobfailureoutcome-type-alias)                               | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobFailureRetry](/docs/api/providers-local#jobfailureretry-type-alias)                                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobIdempotencyDefinition](/docs/api/providers-local#jobidempotencydefinition-interface)                  | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/jobs.ts#L46)                                                          |
| [JobIdempotencyRecord](/docs/api/providers-local#jobidempotencyrecord-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueryContract](/docs/api/providers-local#jobquerycontract-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueryRequest](/docs/api/providers-local#jobqueryrequest-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueue](/docs/api/providers-local#jobqueue-interface)                                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueAcceptance](/docs/api/providers-local#jobqueueacceptance-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueAdminRetryOptions](/docs/api/providers-local#jobqueueadminretryoptions-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueCounts](/docs/api/providers-local#jobqueuecounts-type-alias)                                     | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueEnqueue](/docs/api/providers-local#jobqueueenqueue-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueEntry](/docs/api/providers-local#jobqueueentry-interface)                                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueLeaseOptions](/docs/api/providers-local#jobqueueleaseoptions-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueOptions](/docs/api/providers-local#jobqueueoptions-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueState](/docs/api/providers-local#jobqueuestate-type-alias)                                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueStateError](/docs/api/providers-local#jobqueuestateerror-class)                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobQueueTransitionOptions](/docs/api/providers-local#jobqueuetransitionoptions-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobRecord](/docs/api/providers-local#jobrecord-type-alias)                                               | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobRecordInput](/docs/api/providers-local#jobrecordinput-interface)                                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobRetryRequest](/docs/api/providers-local#jobretryrequest-type-alias)                                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobState](/docs/api/providers-local#jobstate-type-alias)                                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStatusContract](/docs/api/providers-local#jobstatuscontract-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStore](/docs/api/providers-local#jobstore-interface)                                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStoreBoundary](/docs/api/providers-local#jobstoreboundary-type-alias)                                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStoreCheckpoint](/docs/api/providers-local#jobstorecheckpoint-type-alias)                             | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStoreIndex](/docs/api/providers-local#jobstoreindex-type-alias)                                       | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStoreOptions](/docs/api/providers-local#jobstoreoptions-interface)                                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [JobStoreSnapshot](/docs/api/providers-local#jobstoresnapshot-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_AGENT_STATE_VERSION](/docs/api/providers-local#local_agent_state_version)                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_BUCKET_CAPABILITIES](/docs/api/providers-local#local_bucket_capabilities)                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_BUCKET_RESERVED_PREFIXES](/docs/api/providers-local#local_bucket_reserved_prefixes)                | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_CACHE_CAPABILITIES](/docs/api/providers-local#local_cache_capabilities)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_CACHE_DURABLE_CAPABILITIES](/docs/api/providers-local#local_cache_durable_capabilities)            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LOCAL_REALTIME_STATE_VERSION](/docs/api/providers-local#local_realtime_state_version)                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalAgentState](/docs/api/providers-local#localagentstate-type-alias)                                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalAgentStateProviderOptions](/docs/api/providers-local#localagentstateprovideroptions-interface)      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketKeyError](/docs/api/providers-local#localbucketkeyerror-class)                                | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/buckets.test.ts#L59)                                   |
| [LocalBucketListOptions](/docs/api/providers-local#localbucketlistoptions-interface)                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketListPage](/docs/api/providers-local#localbucketlistpage-interface)                            | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketObjectMetadata](/docs/api/providers-local#localbucketobjectmetadata-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketPaginationError](/docs/api/providers-local#localbucketpaginationerror-class)                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketPolicy](/docs/api/providers-local#localbucketpolicy-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketPolicyError](/docs/api/providers-local#localbucketpolicyerror-class)                          | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/buckets.test.ts#L63)                                   |
| [LocalBucketProvider](/docs/api/providers-local#localbucketprovider-type-alias)                           | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/buckets.test.ts#L121)                                  |
| [LocalBucketProviderOptions](/docs/api/providers-local#localbucketprovideroptions-interface)              | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/buckets.test.ts#L119)                                  |
| [LocalBucketStateError](/docs/api/providers-local#localbucketstateerror-class)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalBucketUnsupportedCapability](/docs/api/providers-local#localbucketunsupportedcapability-type-alias) | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheCapabilities](/docs/api/providers-local#localcachecapabilities-interface)                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheEvictionPolicy](/docs/api/providers-local#localcacheevictionpolicy-type-alias)                 | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheKeyError](/docs/api/providers-local#localcachekeyerror-class)                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCachePolicy](/docs/api/providers-local#localcachepolicy-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCachePolicyError](/docs/api/providers-local#localcachepolicyerror-class)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheProvider](/docs/api/providers-local#localcacheprovider-type-alias)                             | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/cache.test.ts#L54)                                                    |
| [LocalCacheProviderOptions](/docs/api/providers-local#localcacheprovideroptions-interface)                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheRead](/docs/api/providers-local#localcacheread-interface)                                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheSnapshot](/docs/api/providers-local#localcachesnapshot-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheStateError](/docs/api/providers-local#localcachestateerror-class)                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheStore](/docs/api/providers-local#localcachestore-class)                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheStoreEntry](/docs/api/providers-local#localcachestoreentry-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheStoreSnapshot](/docs/api/providers-local#localcachestoresnapshot-interface)                    | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheStoreState](/docs/api/providers-local#localcachestorestate-interface)                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalCacheValueError](/docs/api/providers-local#localcachevalueerror-class)                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalEventProvider](/docs/api/providers-local#localeventprovider-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalJobProvider](/docs/api/providers-local#localjobprovider-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalRealtimeError](/docs/api/providers-local#localrealtimeerror-class)                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalRealtimeProviderOptions](/docs/api/providers-local#localrealtimeprovideroptions-interface)          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [LocalRealtimeState](/docs/api/providers-local#localrealtimestate-type-alias)                             | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/effect/fixtures.ts#L22)                                |
| [MAX_BUCKET_PAGE_SIZE](/docs/api/providers-local#max_bucket_page_size)                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [MISSING](/docs/api/providers-local#missing)                                                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [MutableQueueState](/docs/api/providers-local#mutablequeuestate-interface)                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizeBucketKey](/docs/api/providers-local#normalizebucketkey)                                        | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizeBucketPrefix](/docs/api/providers-local#normalizebucketprefix)                                  | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizeCacheId](/docs/api/providers-local#normalizecacheid)                                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizePolicy](/docs/api/providers-local#normalizepolicy)                                              | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizeSchemaVersion](/docs/api/providers-local#normalizeschemaversion)                                | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [normalizeTtl](/docs/api/providers-local#normalizettl)                                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [paginateKeys](/docs/api/providers-local#paginatekeys)                                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [partitionKey](/docs/api/providers-local#partitionkey)                                                    | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [planRetry](/docs/api/providers-local#planretry)                                                          | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-retry.test.ts#L128)                               |
| [prunePartition](/docs/api/providers-local#prunepartition)                                                | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RandomSource](/docs/api/providers-local#randomsource-type-alias)                                         | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [readClock](/docs/api/providers-local#readclock)                                                          | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RealtimeStateStore](/docs/api/providers-local#realtimestatestore-interface)                              | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RetryClassification](/docs/api/providers-local#retryclassification-type-alias)                           | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RetryOptions](/docs/api/providers-local#retryoptions-interface)                                          | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RetryPlan](/docs/api/providers-local#retryplan-interface)                                                | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [RetryState](/docs/api/providers-local#retrystate-type-alias)                                             | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [safeFailureMetadata](/docs/api/providers-local#safefailuremetadata)                                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [ScheduleEnqueue](/docs/api/providers-local#scheduleenqueue-type-alias)                                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [ScheduleEnqueueContext](/docs/api/providers-local#scheduleenqueuecontext-interface)                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [Scheduler](/docs/api/providers-local#scheduler-interface)                                                | Type  | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/jobs.ts#L58)                                                          |
| [SchedulerClock](/docs/api/providers-local#schedulerclock-interface)                                      | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [SchedulerOptions](/docs/api/providers-local#scheduleroptions-interface)                                  | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [SchedulerRegistration](/docs/api/providers-local#schedulerregistration-interface)                        | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [ScheduleRun](/docs/api/providers-local#schedulerun-interface)                                            | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [ScheduleValidationError](/docs/api/providers-local#schedulevalidationerror-class)                        | Value | `@relkit/providers-local` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/tests/jobs-scheduler.test.ts#L21)                            |
| [scopeGap](/docs/api/providers-local#scopegap)                                                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [serializeLocalCacheValue](/docs/api/providers-local#serializelocalcachevalue)                            | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [StoredLocalBucketObject](/docs/api/providers-local#storedlocalbucketobject-type-alias)                   | Type  | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |
| [transitions](/docs/api/providers-local#transitions)                                                      | Value | `@relkit/providers-local` | [Module example](/docs/modules/integrations/local-providers)                                                                                       |

## `provider.ts`

Composes filesystem-backed agent-state operations and their Promise compatibility boundary.

### LocalAgentStateProviderOptions

**Signature**

```ts
declare const LocalAgentStateProviderOptions: LocalAgentStateProviderOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L19)

### LocalAgentStateService (class)

Local agent state operations with substitutable transactional storage.

**Signature**

```ts
declare class LocalAgentStateService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L54)

### agentStateLayer

Builds the live agent-state layer without starting background work.

**Example**

```ts
import { Effect } from "effect";
import { LocalAgentStateService, agentStateLayer } from "./provider.js";

const program = Effect.gen(function* () {
  const agents = yield* LocalAgentStateService;
  return yield* agents.getEpoch();
});
await Effect.runPromise(program.pipe(Effect.provide(agentStateLayer("/tmp/example-agents"))));
```

**Signature**

```ts
declare const agentStateLayer: (
  root: string,
  pollingMs?: number,
) => Layer.Layer<LocalAgentStateService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L79)

### createAgentStateProviderFromStore

Substitutes storage while preserving the same public agent-state operations.

**Signature**

```ts
declare const createAgentStateProviderFromStore: (
  store: ReturnType<typeof createAgentStateStore>,
  pollingMs?: number,
) => AgentStateProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L42)

### createLocalAgentStateProvider

Creates the filesystem-backed agent-state compatibility provider.

**Signature**

```ts
declare const createLocalAgentStateProvider: (
  root: string,
  options?: LocalAgentStateProviderOptions,
) => AgentStateProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L27)

### makeAgentStateService

Composes agent operations over a replaceable state store.

**Signature**

```ts
declare const makeAgentStateService: (
  store: AgentStateStoreEffects,
  pollingMs?: number,
) => AgentStateEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.ts#L89)

## `provider.types.ts`

Defines the Effect operation contract and bounded polling options for local agent state.

### AgentStateEffects (type alias)

Effect counterpart of the established public agent-state provider methods.

**Signature**

```ts
type AgentStateEffects = {
  readonly [K in keyof AgentStateProvider]: AgentStateProvider[K] extends (
    ...args: infer A
  ) => infer R
    ? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
    : AgentStateProvider[K];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.types.ts#L12)

### LocalAgentStateProviderOptions (interface)

Polling policy for observing updates from other agent-state processes.

**Signature**

```ts
export interface LocalAgentStateProviderOptions {
  readonly pollingMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/provider.types.ts#L7)

## `state.ts`

### LOCAL_AGENT_STATE_VERSION

**Signature**

```ts
declare const LOCAL_AGENT_STATE_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L18)

### LocalAgentState

**Signature**

```ts
declare const LocalAgentState: {
  readonly version: 1;
  readonly providerEpoch: string;
  readonly revision: number;
  readonly threads: {
    readonly [x: string]: {
      readonly thread: {
        readonly threadId: string;
        readonly agentId: string;
        readonly ownerScope: string;
        readonly status:
          | "idle"
          | "running"
          | "waiting"
          | "approval-interrupted"
          | "stopping"
          | "worker-interrupted";
        readonly revision: string;
        readonly createdAt: string;
        readonly updatedAt: string;
      };
      readonly runs: {
        readonly [x: string]: {
          readonly status:
            | "running"
            | "waiting"
            | "approval-interrupted"
            | "stopping"
            | "worker-interrupted"
            | "accepted"
            | "succeeded"
            | "failed"
            | "cancelled";
          readonly threadId: string;
          readonly runId: string;
          readonly owner: {
            readonly generationId: string;
            readonly publicFingerprint: string;
            readonly protocolVersion: number;
            readonly schemaVersion: number;
            readonly providerScope: string;
          };
          readonly operationId: OperationId;
          readonly inputDigest: string;
          readonly acceptedAt: string;
          readonly maxJournalBytes: number;
          readonly maxJournalRecordBytes: number;
          readonly terminalReserveBytes: number;
          readonly settledAt?: string;
          readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
        };
      };
      readonly messages: ReadonlyArray<{
        readonly createdAt: string;
        readonly role: "user" | "assistant" | "tool";
        readonly parts: ReadonlyArray<
          | {
              readonly kind: "text";
              readonly text: string;
              readonly partId: string;
              readonly state?: "streaming" | "complete";
            }
          | {
              readonly kind: "tool";
              readonly state:
                | "running"
                | "succeeded"
                | "failed"
                | "started"
                | "input-streaming"
                | "input-ready"
                | "approval-required"
                | "denied";
              readonly partId: string;
              readonly toolCallId: string;
              readonly toolId: string;
              readonly inputText?: string;
              readonly input?: unknown;
              readonly output?: unknown;
              readonly value?: unknown;
            }
          | {
              readonly partId: string;
              readonly kind: "progress";
              readonly value: unknown;
              readonly scope: "run";
            }
          | {
              readonly partId: string;
              readonly kind: "progress";
              readonly value: unknown;
              readonly scope: "tool";
              readonly toolCallId: string;
              readonly toolId: string;
            }
        >;
        readonly messageId: string;
        readonly runId?: string;
      }>;
      readonly approvals: ReadonlyArray<{
        readonly status: "cancelled" | "denied" | "open" | "approved";
        readonly runId: string;
        readonly approvalId: string;
        readonly interruptSetDigest: string;
        readonly publicRequest: unknown;
        readonly interruptSetSize?: number;
      }>;
      readonly journal: ReadonlyArray<{
        readonly recordId: string;
        readonly runId: string;
        readonly kind:
          "progress" | "message" | "approval" | "control" | "terminal" | "interruption" | "event";
        readonly publicValue: unknown;
        readonly checkpoint: {
          readonly applicationId: string;
          readonly environment: string;
          readonly profile: string;
          readonly providerEpoch: string;
          readonly threadId: string;
          readonly sequence: string;
        };
        readonly encodedBytes: number;
        readonly createdAt: string;
      }>;
      readonly sequence: number;
      readonly controls: {
        readonly [x: string]: {
          readonly sequence: number;
          readonly record: {
            readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
            readonly runId: string;
            readonly acceptedAt: string;
            readonly kind: "steer" | "follow-up" | "stop" | "approve";
            readonly controlId: OperationId;
            readonly semanticDigest: string;
            readonly effect: "not-started" | "confirmed" | "unknown";
            readonly settledAt?: string;
            readonly publicPayload?: unknown;
          };
          readonly publicPayload: unknown;
          readonly semanticDigest: string;
          readonly receipt: {
            readonly operationId: OperationId;
            readonly threadId: string;
            readonly runId: string;
            readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
            readonly effect: "not-started" | "confirmed" | "unknown";
            readonly duplicate: boolean;
          };
          readonly expiresAt: string;
          readonly downstreamOperationId?: string;
        };
      };
      readonly runClaims: {
        readonly [x: string]: {
          readonly runId: string;
          readonly claimId: string;
          readonly workerId: string;
          readonly generationId: string;
          readonly fence: number;
          readonly expiresAt: string;
        };
      };
      readonly controlClaims: {
        readonly [x: string]: {
          readonly controlId: OperationId;
          readonly claimId: string;
          readonly workerId: string;
          readonly generationId: string;
          readonly fence: number;
          readonly expiresAt: string;
        };
      };
      readonly scopeKey: string;
      readonly controlSequence: number;
      readonly nextFence: number;
      readonly waiting?: {
        readonly revision: string;
        readonly runId: string;
        readonly response: Json;
        readonly requests: ReadonlyArray<{
          readonly node: string;
          readonly response: Json;
          readonly value?: unknown;
        }>;
      };
      readonly activeRunId?: string;
      readonly snapshots?: {
        readonly [x: string]: {
          readonly createdAt: string;
          readonly messages: ReadonlyArray<{
            readonly createdAt: string;
            readonly role: "user" | "assistant" | "tool";
            readonly parts: ReadonlyArray<
              | {
                  readonly kind: "text";
                  readonly text: string;
                  readonly partId: string;
                  readonly state?: "streaming" | "complete";
                }
              | {
                  readonly kind: "tool";
                  readonly state:
                    | "running"
                    | "succeeded"
                    | "failed"
                    | "started"
                    | "input-streaming"
                    | "input-ready"
                    | "approval-required"
                    | "denied";
                  readonly partId: string;
                  readonly toolCallId: string;
                  readonly toolId: string;
                  readonly inputText?: string;
                  readonly input?: unknown;
                  readonly output?: unknown;
                  readonly value?: unknown;
                }
              | {
                  readonly partId: string;
                  readonly kind: "progress";
                  readonly value: unknown;
                  readonly scope: "run";
                }
              | {
                  readonly partId: string;
                  readonly kind: "progress";
                  readonly value: unknown;
                  readonly scope: "tool";
                  readonly toolCallId: string;
                  readonly toolId: string;
                }
            >;
            readonly messageId: string;
            readonly runId?: string;
          }>;
        };
      };
    };
  };
  readonly createReceipts: {
    readonly [x: string]: { readonly digest: string; readonly threadId: string };
  };
  readonly runReceipts: {
    readonly [x: string]: {
      readonly semanticDigest: string;
      readonly expiresAt: string;
      readonly value:
        | {
            readonly operationId: OperationId;
            readonly threadId: string;
            readonly runId: string;
            readonly status: "accepted";
            readonly duplicate: boolean;
          }
        | {
            readonly operationId: OperationId;
            readonly threadId: string;
            readonly runId: string;
            readonly status: "succeeded" | "failed" | "cancelled";
            readonly checkpoint: {
              readonly applicationId: string;
              readonly environment: string;
              readonly profile: string;
              readonly providerEpoch: string;
              readonly threadId: string;
              readonly sequence: string;
            };
            readonly duplicate: boolean;
          };
    };
  };
  readonly controlReceipts: {
    readonly [x: string]: {
      readonly semanticDigest: string;
      readonly expiresAt: string;
      readonly value: {
        readonly operationId: OperationId;
        readonly threadId: string;
        readonly runId: string;
        readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
        readonly effect: "not-started" | "confirmed" | "unknown";
        readonly duplicate: boolean;
      };
    };
  };
  readonly continuationReceipts: {
    readonly [x: string]: {
      readonly semanticDigest: string;
      readonly expiresAt: string;
      readonly value: {
        readonly threadId: string;
        readonly runId: string;
        readonly operationId: OperationId;
        readonly interruptSetDigest: string;
        readonly duplicate: boolean;
        readonly interruptedRunId: string;
        readonly waitingRevision?: string;
      };
    };
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L15)

### LocalAgentThread

**Signature**

```ts
declare const LocalAgentThread: {
  readonly thread: {
    readonly threadId: string;
    readonly agentId: string;
    readonly ownerScope: string;
    readonly status:
      "idle" | "running" | "waiting" | "approval-interrupted" | "stopping" | "worker-interrupted";
    readonly revision: string;
    readonly createdAt: string;
    readonly updatedAt: string;
  };
  readonly runs: {
    readonly [x: string]: {
      readonly status:
        | "running"
        | "waiting"
        | "approval-interrupted"
        | "stopping"
        | "worker-interrupted"
        | "accepted"
        | "succeeded"
        | "failed"
        | "cancelled";
      readonly threadId: string;
      readonly runId: string;
      readonly owner: {
        readonly generationId: string;
        readonly publicFingerprint: string;
        readonly protocolVersion: number;
        readonly schemaVersion: number;
        readonly providerScope: string;
      };
      readonly operationId: OperationId;
      readonly inputDigest: string;
      readonly acceptedAt: string;
      readonly maxJournalBytes: number;
      readonly maxJournalRecordBytes: number;
      readonly terminalReserveBytes: number;
      readonly settledAt?: string;
      readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
    };
  };
  readonly messages: ReadonlyArray<{
    readonly createdAt: string;
    readonly role: "user" | "assistant" | "tool";
    readonly parts: ReadonlyArray<
      | {
          readonly kind: "text";
          readonly text: string;
          readonly partId: string;
          readonly state?: "streaming" | "complete";
        }
      | {
          readonly kind: "tool";
          readonly state:
            | "running"
            | "succeeded"
            | "failed"
            | "started"
            | "input-streaming"
            | "input-ready"
            | "approval-required"
            | "denied";
          readonly partId: string;
          readonly toolCallId: string;
          readonly toolId: string;
          readonly inputText?: string;
          readonly input?: unknown;
          readonly output?: unknown;
          readonly value?: unknown;
        }
      | {
          readonly partId: string;
          readonly kind: "progress";
          readonly value: unknown;
          readonly scope: "run";
        }
      | {
          readonly partId: string;
          readonly kind: "progress";
          readonly value: unknown;
          readonly scope: "tool";
          readonly toolCallId: string;
          readonly toolId: string;
        }
    >;
    readonly messageId: string;
    readonly runId?: string;
  }>;
  readonly approvals: ReadonlyArray<{
    readonly status: "cancelled" | "denied" | "open" | "approved";
    readonly runId: string;
    readonly approvalId: string;
    readonly interruptSetDigest: string;
    readonly publicRequest: unknown;
    readonly interruptSetSize?: number;
  }>;
  readonly journal: ReadonlyArray<{
    readonly recordId: string;
    readonly runId: string;
    readonly kind:
      "progress" | "message" | "approval" | "control" | "terminal" | "interruption" | "event";
    readonly publicValue: unknown;
    readonly checkpoint: {
      readonly applicationId: string;
      readonly environment: string;
      readonly profile: string;
      readonly providerEpoch: string;
      readonly threadId: string;
      readonly sequence: string;
    };
    readonly encodedBytes: number;
    readonly createdAt: string;
  }>;
  readonly sequence: number;
  readonly controls: {
    readonly [x: string]: {
      readonly sequence: number;
      readonly record: {
        readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
        readonly runId: string;
        readonly acceptedAt: string;
        readonly kind: "steer" | "follow-up" | "stop" | "approve";
        readonly controlId: OperationId;
        readonly semanticDigest: string;
        readonly effect: "not-started" | "confirmed" | "unknown";
        readonly settledAt?: string;
        readonly publicPayload?: unknown;
      };
      readonly publicPayload: unknown;
      readonly semanticDigest: string;
      readonly receipt: {
        readonly operationId: OperationId;
        readonly threadId: string;
        readonly runId: string;
        readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
        readonly effect: "not-started" | "confirmed" | "unknown";
        readonly duplicate: boolean;
      };
      readonly expiresAt: string;
      readonly downstreamOperationId?: string;
    };
  };
  readonly runClaims: {
    readonly [x: string]: {
      readonly runId: string;
      readonly claimId: string;
      readonly workerId: string;
      readonly generationId: string;
      readonly fence: number;
      readonly expiresAt: string;
    };
  };
  readonly controlClaims: {
    readonly [x: string]: {
      readonly controlId: OperationId;
      readonly claimId: string;
      readonly workerId: string;
      readonly generationId: string;
      readonly fence: number;
      readonly expiresAt: string;
    };
  };
  readonly scopeKey: string;
  readonly controlSequence: number;
  readonly nextFence: number;
  readonly waiting?: {
    readonly revision: string;
    readonly runId: string;
    readonly response: Json;
    readonly requests: ReadonlyArray<{
      readonly node: string;
      readonly response: Json;
      readonly value?: unknown;
    }>;
  };
  readonly activeRunId?: string;
  readonly snapshots?: {
    readonly [x: string]: {
      readonly createdAt: string;
      readonly messages: ReadonlyArray<{
        readonly createdAt: string;
        readonly role: "user" | "assistant" | "tool";
        readonly parts: ReadonlyArray<
          | {
              readonly kind: "text";
              readonly text: string;
              readonly partId: string;
              readonly state?: "streaming" | "complete";
            }
          | {
              readonly kind: "tool";
              readonly state:
                | "running"
                | "succeeded"
                | "failed"
                | "started"
                | "input-streaming"
                | "input-ready"
                | "approval-required"
                | "denied";
              readonly partId: string;
              readonly toolCallId: string;
              readonly toolId: string;
              readonly inputText?: string;
              readonly input?: unknown;
              readonly output?: unknown;
              readonly value?: unknown;
            }
          | {
              readonly partId: string;
              readonly kind: "progress";
              readonly value: unknown;
              readonly scope: "run";
            }
          | {
              readonly partId: string;
              readonly kind: "progress";
              readonly value: unknown;
              readonly scope: "tool";
              readonly toolCallId: string;
              readonly toolId: string;
            }
        >;
        readonly messageId: string;
        readonly runId?: string;
      }>;
    };
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L12)

### LocalControl

**Signature**

```ts
declare const LocalControl: {
  readonly sequence: number;
  readonly record: {
    readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
    readonly runId: string;
    readonly acceptedAt: string;
    readonly kind: "steer" | "follow-up" | "stop" | "approve";
    readonly controlId: OperationId;
    readonly semanticDigest: string;
    readonly effect: "not-started" | "confirmed" | "unknown";
    readonly settledAt?: string;
    readonly publicPayload?: unknown;
  };
  readonly publicPayload: unknown;
  readonly semanticDigest: string;
  readonly receipt: {
    readonly operationId: OperationId;
    readonly threadId: string;
    readonly runId: string;
    readonly status: "accepted" | "cancelled" | "processing" | "applied" | "rejected";
    readonly effect: "not-started" | "confirmed" | "unknown";
    readonly duplicate: boolean;
  };
  readonly expiresAt: string;
  readonly downstreamOperationId?: string;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L11)

### LocalPinnedSnapshot

**Signature**

```ts
declare const LocalPinnedSnapshot: {
  readonly createdAt: string;
  readonly messages: ReadonlyArray<{
    readonly createdAt: string;
    readonly role: "user" | "assistant" | "tool";
    readonly parts: ReadonlyArray<
      | {
          readonly kind: "text";
          readonly text: string;
          readonly partId: string;
          readonly state?: "streaming" | "complete";
        }
      | {
          readonly kind: "tool";
          readonly state:
            | "running"
            | "succeeded"
            | "failed"
            | "started"
            | "input-streaming"
            | "input-ready"
            | "approval-required"
            | "denied";
          readonly partId: string;
          readonly toolCallId: string;
          readonly toolId: string;
          readonly inputText?: string;
          readonly input?: unknown;
          readonly output?: unknown;
          readonly value?: unknown;
        }
      | {
          readonly partId: string;
          readonly kind: "progress";
          readonly value: unknown;
          readonly scope: "run";
        }
      | {
          readonly partId: string;
          readonly kind: "progress";
          readonly value: unknown;
          readonly scope: "tool";
          readonly toolCallId: string;
          readonly toolId: string;
        }
    >;
    readonly messageId: string;
    readonly runId?: string;
  }>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L13)

### LocalStoredRun

**Signature**

```ts
declare const LocalStoredRun: {
  readonly status:
    | "running"
    | "waiting"
    | "approval-interrupted"
    | "stopping"
    | "worker-interrupted"
    | "accepted"
    | "succeeded"
    | "failed"
    | "cancelled";
  readonly threadId: string;
  readonly runId: string;
  readonly owner: {
    readonly generationId: string;
    readonly publicFingerprint: string;
    readonly protocolVersion: number;
    readonly schemaVersion: number;
    readonly providerScope: string;
  };
  readonly operationId: OperationId;
  readonly inputDigest: string;
  readonly acceptedAt: string;
  readonly maxJournalBytes: number;
  readonly maxJournalRecordBytes: number;
  readonly terminalReserveBytes: number;
  readonly settledAt?: string;
  readonly outcome?: "worker-interrupted" | "succeeded" | "failed" | "cancelled";
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L14)

### StoredReceipt

**Signature**

```ts
declare const StoredReceipt: StoredReceipt<Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L10)

### emptyAgentState

Creates format-v1 state with a fresh provider epoch and empty domain indexes.

**Signature**

```ts
declare const emptyAgentState: () => LocalAgentState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.ts#L24)

## `state.types.ts`

### LocalAgentState (type alias)

Complete validated version-one agent-state snapshot.

**Signature**

```ts
type LocalAgentState = typeof AgentState.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L19)

### LocalAgentThread (type alias)

Thread, runs, controls and retained content decoded before transitions.

**Signature**

```ts
type LocalAgentThread = typeof AgentThread.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L25)

### LocalControl (type alias)

Control record with its receipt and downstream identity.

**Signature**

```ts
type LocalControl = typeof AgentControl.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L28)

### LocalPinnedSnapshot (type alias)

Immutable pinned message view retained for paginated history.

**Signature**

```ts
type LocalPinnedSnapshot = typeof PinnedSnapshot.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L31)

### LocalStoredRun (type alias)

Run metadata and journal limits decoded together.

**Signature**

```ts
type LocalStoredRun = typeof AgentRun.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L22)

### StoredReceipt (interface)

Generic idempotency envelope used when selecting retained receipts.

**Signature**

```ts
export interface StoredReceipt<Value> {
  readonly semanticDigest: string;
  readonly expiresAt: string;
  readonly value: Value;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/state.types.ts#L12)

## `storage.types.ts`

### AgentStateStore (interface)

Promise storage seam retained for existing provider adapters and fault injection.

**Signature**

```ts
export interface AgentStateStore {
  read(): Promise<LocalAgentState>;
  update<Value>(
    change: (state: LocalAgentState) => readonly [LocalAgentState, Value],
  ): Promise<Value>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/storage.types.ts#L5)

### AgentStateStoreEffects (type alias)

Effect storage contract used by agent-state operations.

**Signature**

```ts
type AgentStateStoreEffects = LocalStateStore<LocalAgentState>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/agent-state/storage.types.ts#L13)

## `buckets.types.ts`

### LocalBucketListOptions (interface)

Optional cursor and bounded page size for lexical key listing.

**Signature**

```ts
export interface LocalBucketListOptions {
  readonly cursor?: string;
  readonly limit?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L25)

### LocalBucketListPage (interface)

Immutable bucket key page with continuation metadata.

**Signature**

```ts
export interface LocalBucketListPage {
  readonly items: readonly string[];
  readonly nextCursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L31)

### LocalBucketObjectMetadata (interface)

Verified content identity, size and optional application metadata.

**Signature**

```ts
export interface LocalBucketObjectMetadata extends BucketObjectMetadata {
  readonly contentHash: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L37)

### LocalBucketPolicy (interface)

Size, content-type and metadata limits enforced before bucket writes.

**Signature**

```ts
export interface LocalBucketPolicy {
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L11)

### LocalBucketProvider (type alias)

Public Promise bucket contract plus local inspection and lifecycle operations.

**Signature**

```ts
type LocalBucketProvider = Omit<BucketProvider, "list"> & {
  readonly capabilities: Readonly<BucketCapabilities>;
  readonly root: string;
  readonly policy: Readonly<LocalBucketPolicy>;
  readonly list: {
    (prefix?: string): Promise<readonly string[]>;
    (prefix: string | undefined, options: LocalBucketListOptions): Promise<LocalBucketListPage>;
  };
  readonly listPage: (
    prefix?: string,
    options?: LocalBucketListOptions,
  ) => Promise<LocalBucketListPage>;
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
  readonly inspector: {
    readonly list: (request: {
      readonly prefix?: string;
      readonly cursor?: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<{
      readonly items: readonly { readonly key: string; readonly metadata?: BucketObjectMetadata }[];
      readonly nextCursor?: string;
    }>;
    readonly preview: (request: {
      readonly key: string;
      readonly offset: number;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<
      | {
          readonly bytes: Uint8Array;
          readonly metadata: BucketObjectMetadata;
          readonly totalBytes: number;
        }
      | undefined
    >;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L45)

### LocalBucketProviderOptions (interface)

Owned root, object policy and default pagination settings for a local bucket.

**Signature**

```ts
export interface LocalBucketProviderOptions extends LocalBucketPolicy {
  readonly root?: string;
  readonly stateRoot?: string;
  readonly policy?: LocalBucketPolicy;
  readonly pageSize?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L17)

### LocalBucketUnsupportedCapability (type alias)

Bucket capability that the filesystem implementation explicitly does not provide.

**Signature**

```ts
type LocalBucketUnsupportedCapability = {
  readonly capability: BucketCapability;
  readonly operation: BucketOperation;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L86)

### StoredLocalBucketObject (type alias)

Versioned object envelope storing verified bytes as base64.

**Signature**

```ts
type StoredLocalBucketObject = typeof StoredBucketObject.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/buckets.types.ts#L42)

## `keys.ts`

### assertContainedPath

Rejects a resolved path that escapes the owned root.

**Signature**

```ts
declare const assertContainedPath: (root: string, candidate: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/keys.ts#L77)

### encodeBucketKey

Encodes a normalized key into a filesystem-safe object identity.

**Signature**

```ts
declare const encodeBucketKey: (key: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/keys.ts#L67)

### normalizeBucketKey

Validates an object key without normalizing away an attempted escape.

**Signature**

```ts
declare const normalizeBucketKey: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/keys.ts#L11)

### normalizeBucketPrefix

Validates a list prefix while allowing the conventional trailing slash.

**Signature**

```ts
declare const normalizeBucketPrefix: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/keys.ts#L36)

## `pagination.ts`

### DEFAULT_BUCKET_PAGE_SIZE

**Signature**

```ts
declare const DEFAULT_BUCKET_PAGE_SIZE: 100;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/pagination.ts#L7)

### MAX_BUCKET_PAGE_SIZE

**Signature**

```ts
declare const MAX_BUCKET_PAGE_SIZE: 1000;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/pagination.ts#L8)

### paginateKeys

Returns a stable page of sorted keys using a prefix-bound cursor.

**Signature**

```ts
declare const paginateKeys: (
  keys: readonly string[],
  prefix: string,
  options: LocalBucketListOptions | undefined,
) => LocalBucketListPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/pagination.ts#L17)

## `provider.ts`

### LocalBucketService (class)

Owns bucket admission, object IO and ordered inspection.

**Signature**

```ts
declare class LocalBucketService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/provider.ts#L29)

### createLocalBucketProvider

Creates a filesystem bucket with the established Promise and overload contracts.

**Signature**

```ts
declare const createLocalBucketProvider: (
  optionsOrRoot: LocalBucketProviderOptions | string,
  policy?: LocalBucketPolicy,
) => LocalBucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/provider.ts#L39)

### createLocalBucketProviderForTest

The same constructor is deterministic when supplied an isolated temporary root.

**Signature**

```ts
declare const createLocalBucketProviderForTest: (
  optionsOrRoot: LocalBucketProviderOptions | string,
  policy?: LocalBucketPolicy,
) => LocalBucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/provider.ts#L47)

### localBucketLayer

Provides a bucket service and closes its admission gate with the scope.

**Example**

```ts
import { Effect } from "effect";
import { LocalBucketService, localBucketLayer } from "./provider.js";

const program = Effect.gen(function* () {
  const bucket = yield* LocalBucketService;
  yield* bucket.put("hello.txt", new TextEncoder().encode("hello"));
  return yield* bucket.head("hello.txt");
});
await Effect.runPromise(
  program.pipe(Effect.provide(localBucketLayer({ root: "/tmp/example-bucket" }))),
);
```

**Signature**

```ts
declare const localBucketLayer: (
  options: LocalBucketProviderOptions,
) => Layer.Layer<LocalBucketService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/provider.ts#L66)

### makeLocalBucketService

Validates construction and creates one bucket lifecycle owner.

**Signature**

```ts
declare const makeLocalBucketService: (
  optionsOrRoot: string | LocalBucketProviderOptions,
  policy?: LocalBucketPolicy | undefined,
) => Effect.Effect<LocalBucketEffects, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/provider.ts#L79)

## `types.ts`

### LOCAL_BUCKET_CAPABILITIES

**Signature**

```ts
declare const LOCAL_BUCKET_CAPABILITIES: Readonly<BucketCapabilities>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L24)

### LOCAL_BUCKET_RESERVED_PREFIXES

**Signature**

```ts
declare const LOCAL_BUCKET_RESERVED_PREFIXES: ReadonlyArray<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L29)

### LocalBucketKeyError (class)

Preserves the public local bucket key error identity and stable error code.

**Signature**

```ts
declare class LocalBucketKeyError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L32)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_KEY_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L33)

### LocalBucketListOptions

**Signature**

```ts
declare const LocalBucketListOptions: LocalBucketListOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L16)

### LocalBucketListPage

**Signature**

```ts
declare const LocalBucketListPage: LocalBucketListPage;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L17)

### LocalBucketObjectMetadata

**Signature**

```ts
declare const LocalBucketObjectMetadata: LocalBucketObjectMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L18)

### LocalBucketPaginationError (class)

Preserves the public local bucket pagination error identity and stable error code.

**Signature**

```ts
declare class LocalBucketPaginationError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L62)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_CURSOR_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L63)

### LocalBucketPolicy

**Signature**

```ts
declare const LocalBucketPolicy: LocalBucketPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L14)

### LocalBucketPolicyError (class)

Preserves the public local bucket policy error identity and stable error code.

**Signature**

```ts
declare class LocalBucketPolicyError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L42)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_POLICY_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L43)

### LocalBucketProvider

**Signature**

```ts
declare const LocalBucketProvider: LocalBucketProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L20)

### LocalBucketProviderOptions

**Signature**

```ts
declare const LocalBucketProviderOptions: LocalBucketProviderOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L15)

### LocalBucketStateError (class)

Preserves the public local bucket state error identity and stable error code.

**Signature**

```ts
declare class LocalBucketStateError {
  constructor(message = "Bucket state is invalid");
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L52)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_BUCKET_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L53)

### LocalBucketUnsupportedCapability

**Signature**

```ts
declare const LocalBucketUnsupportedCapability: LocalBucketUnsupportedCapability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L21)

### StoredLocalBucketObject

**Signature**

```ts
declare const StoredLocalBucketObject: {
  readonly version: 1;
  readonly metadata: { readonly [x: string]: string };
  readonly key: string;
  readonly size: number;
  readonly contentHash: string;
  readonly etag: string;
  readonly data: string;
  readonly contentType?: string;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/buckets/types.ts#L19)

## `cache.types.ts`

### LocalCacheCapabilities (interface)

Truthful persistence, atomicity and capacity guarantees for the local cache.

**Signature**

```ts
export interface LocalCacheCapabilities extends CacheCapabilities {
  readonly persistence: "memory-only" | "restart-recovery";
  readonly singleFlight: "generation-local";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L53)

### LocalCacheEvictionPolicy (type alias)

Eviction policy supported by the bounded in-memory cache.

**Signature**

```ts
type LocalCacheEvictionPolicy = "lru";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L9)

### LocalCachePolicy (interface)

Normalized TTL, encoded-value and total-cache limits.

**Signature**

```ts
export interface LocalCachePolicy {
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly maxEntries: number;
  readonly maxBytes: number;
  readonly evictionPolicy: LocalCacheEvictionPolicy;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L31)

### LocalCacheProvider (type alias)

Public cache operations and local lifecycle/inspection surface.

**Signature**

```ts
type LocalCacheProvider = Omit<CacheProvider, "capabilities"> & {
  readonly capabilities: Readonly<LocalCacheCapabilities>;
  readonly cacheId: string;
  readonly schemaVersion: string | number;
  readonly policy: Readonly<LocalCachePolicy>;
  readonly snapshot: () => LocalCacheSnapshot;
  readonly stateRoot?: string;
  readonly ready: () => Promise<void>;
  readonly close: () => Promise<void>;
  readonly get: (key: unknown, context?: CacheOperationContext) => Promise<unknown | undefined>;
  readonly set: (
    key: unknown,
    value: unknown,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => Promise<void>;
  readonly delete: (key: unknown, context?: CacheOperationContext) => Promise<void>;
  readonly has: (key: unknown, context?: CacheOperationContext) => Promise<boolean>;
  readonly getOrSet: (
    key: unknown,
    produce: () => unknown | Promise<unknown>,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => Promise<unknown>;
  readonly increment: (
    key: unknown,
    delta: number,
    options?: CacheOperationOptions,
    context?: CacheOperationContext,
  ) => Promise<number>;
  readonly inspector: {
    readonly scan: (request: {
      readonly search?: string;
      readonly cursor?: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<{ readonly items: readonly unknown[]; readonly nextCursor?: string }>;
    readonly value: (request: {
      readonly key: string;
      readonly limit: number;
      readonly signal: AbortSignal;
    }) => Promise<unknown | undefined>;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L59)

### LocalCacheProviderOptions (interface)

Cache bounds, persistence, clock and safe observation hooks.

**Signature**

```ts
export interface LocalCacheProviderOptions {
  /** Provider-owned profile directory; enables atomic restart snapshots. */
  readonly stateRoot?: string;
  readonly cacheId?: string;
  readonly schemaVersion?: string | number;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly maxEntries?: number;
  readonly maxBytes?: number;
  readonly evictionPolicy?: LocalCacheEvictionPolicy;
  /** Injectable clock used for TTL and deadline checks. */
  readonly clock?: () => number;
  /** Alias for clock, kept for small deterministic test seams. */
  readonly now?: () => number;
  /** Receives safe counters only; keys and values are never included. */
  readonly onSnapshot?: (snapshot: LocalCacheSnapshot) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L12)

### LocalCacheSnapshot (interface)

Safe cache counters and effective policy without keys or values.

**Signature**

```ts
export interface LocalCacheSnapshot {
  readonly version: 1;
  readonly cacheId: string;
  readonly schemaVersion: string | number;
  readonly entries: number;
  readonly bytes: number;
  readonly evictions: number;
  readonly hits: number;
  readonly misses: number;
  readonly inFlight: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/cache.types.ts#L40)

## `inspector.ts`

### createLocalCacheInspector

Projects bounded cache metadata and previews from the same byte-LRU store.

**Signature**

```ts
declare const createLocalCacheInspector: (
  store: LocalCacheStore,
  clock: () => number,
) => LocalCacheProvider["inspector"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/inspector.ts#L10)

## `keys.ts`

### createLocalCacheKey

Builds a deterministic namespace key without exposing the raw key to logs.

**Signature**

```ts
declare const createLocalCacheKey: (
  cacheId: string,
  schemaVersion: string | number,
  key: unknown,
) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/keys.ts#L38)

### normalizeCacheId

Validates the namespace used to isolate canonical cache keys.

**Signature**

```ts
declare const normalizeCacheId: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/keys.ts#L9)

### normalizeSchemaVersion

Validates the cache schema namespace without changing its public representation.

**Signature**

```ts
declare const normalizeSchemaVersion: (value: unknown) => string | number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/keys.ts#L21)

### serializeLocalCacheValue

Serializes supported JSON values for byte accounting and cloning.

**Signature**

```ts
declare const serializeLocalCacheValue: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/keys.ts#L55)

## `policy.ts`

### assertActive

Rejects an aborted or expired operation before cache or bucket IO.

**Signature**

```ts
declare const assertActive: (
  context: CacheOperationContext | undefined,
  clock: () => number,
) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L62)

### byteLength

Measures UTF-8 bytes for cache key and value capacity accounting.

**Signature**

```ts
declare const byteLength: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L92)

### clone

Copies cache values through their supported JSON representation.

**Signature**

```ts
declare const clone: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L101)

### normalizePolicy

Validates provider limits and normalizes effective policy defaults.

**Signature**

```ts
declare const normalizePolicy: (options: LocalCacheProviderOptions) => LocalCachePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L18)

### normalizeTtl

Resolves entry TTL against defaults and the maximum allowed lifetime.

**Signature**

```ts
declare const normalizeTtl: (value: unknown, policy: LocalCachePolicy) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L44)

### readClock

Checks that the injected clock returns a usable finite timestamp.

**Signature**

```ts
declare const readClock: (clock: () => number) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/policy.ts#L79)

## `provider.ts`

### LocalCacheService (class)

Cache state, producer admission and durable writes share one owner.

**Signature**

```ts
declare class LocalCacheService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/provider.ts#L28)

### createLocalCacheProvider

Creates the existing Promise cache API over an Effect service.

**Signature**

```ts
declare const createLocalCacheProvider: (options?: LocalCacheProviderOptions) => LocalCacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/provider.ts#L37)

### localCacheLayer

Provides a cache and commits its final snapshot at scope exit.

**Example**

```ts
import { Effect } from "effect";
import { LocalCacheService, localCacheLayer } from "./provider.js";

const program = Effect.gen(function* () {
  const cache = yield* LocalCacheService;
  yield* cache.set("answer", 42);
  return yield* cache.get("answer");
});
await Effect.runPromise(program.pipe(Effect.provide(localCacheLayer())));
```

**Signature**

```ts
declare const localCacheLayer: (
  options?: LocalCacheProviderOptions,
) => Layer.Layer<LocalCacheService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/provider.ts#L60)

### makeLocalCacheService

Acquires the cache's indexes, serialization permit and producer coordination.

**Signature**

```ts
declare const makeLocalCacheService: (
  options?: LocalCacheProviderOptions,
) => Effect.Effect<LocalCacheEffects, LocalOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/provider.ts#L75)

## `store.ts`

### LocalCacheRead

**Signature**

```ts
declare const LocalCacheRead: LocalCacheRead;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L11)

### LocalCacheStore (class)

Pure byte-bounded LRU state owned by LocalCacheService; callers supply clock values.

**Signature**

```ts
declare class LocalCacheStore { constructor(private readonly policy: LocalCachePolicy) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L20)

### read (method)

Reads an entry, expires stale values, and updates recency and hit/miss counters.

**Signature**

```ts
declare const read: (key: string, now: number) => LocalCacheRead;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L32)

### write (method)

Replaces an entry and evicts least-recently-used values until both bounds hold.

**Signature**

```ts
declare const write: (
  key: string,
  value: unknown,
  bytes: number,
  expiresAt: number | undefined,
) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L49)

### remove (method)

Removes one entry and adjusts encoded byte accounting; reports whether it existed.

**Signature**

```ts
declare const remove: (key: string) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L64)

### purgeExpired (method)

Removes every expired entry without changing hit/miss counters.

**Signature**

```ts
declare const purgeExpired: (now: number) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L73)

### snapshot (method)

Copies safe counters without exposing cached values or keys.

**Signature**

```ts
declare const snapshot: () => LocalCacheStoreSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L80)

### exportState (method)

Copies all entries and recency counters for the owning service's durable snapshot.

**Signature**

```ts
declare const exportState: () => LocalCacheStoreState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L91)

### restore (method)

Validates snapshot entries, rebuilds accounting, and reapplies current policy limits.

**Signature**

```ts
declare const restore: (state: LocalCacheStoreState) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L106)

### clear (method)

Releases all cached entries while preserving historical counters.

**Signature**

```ts
declare const clear: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L145)

### evict (method)

Evicts by recency using a bounded linear scan of the in-memory entries.

**Signature**

```ts
declare const evict: () => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L151)

### LocalCacheStoreEntry

**Signature**

```ts
declare const LocalCacheStoreEntry: LocalCacheStoreEntry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L13)

### LocalCacheStoreSnapshot

**Signature**

```ts
declare const LocalCacheStoreSnapshot: LocalCacheStoreSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L12)

### LocalCacheStoreState

**Signature**

```ts
declare const LocalCacheStoreState: LocalCacheStoreState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L14)

### MISSING

**Signature**

```ts
declare const MISSING: unique symbol;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.ts#L17)

## `store.types.ts`

### Entry (interface)

Mutable LRU entry with encoded-byte accounting and recency sequence.

**Signature**

```ts
export interface Entry {
  readonly key: string;
  readonly value: unknown;
  readonly bytes: number;
  readonly expiresAt?: number;
  lastUsed: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.types.ts#L4)

### LocalCacheRead (interface)

Cache read result distinguishing absence from an expired value.

**Signature**

```ts
export interface LocalCacheRead {
  readonly value: unknown | typeof MISSING;
  readonly expired: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.types.ts#L13)

### LocalCacheStoreEntry (interface)

Serializable cache entry including expiration and recency metadata.

**Signature**

```ts
export interface LocalCacheStoreEntry {
  readonly key: string;
  readonly value: unknown;
  readonly bytes: number;
  readonly expiresAt?: number;
  readonly lastUsed: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.types.ts#L28)

### LocalCacheStoreSnapshot (interface)

Safe counters maintained by the pure LRU state.

**Signature**

```ts
export interface LocalCacheStoreSnapshot {
  readonly entries: number;
  readonly bytes: number;
  readonly evictions: number;
  readonly hits: number;
  readonly misses: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.types.ts#L19)

### LocalCacheStoreState (interface)

Complete cache snapshot used to restore counters and LRU ordering.

**Signature**

```ts
export interface LocalCacheStoreState extends Omit<LocalCacheStoreSnapshot, "entries"> {
  readonly sequence: number;
  readonly entries: readonly LocalCacheStoreEntry[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/store.types.ts#L37)

## `types.ts`

### LOCAL_CACHE_CAPABILITIES

**Signature**

```ts
declare const LOCAL_CACHE_CAPABILITIES: Readonly<{
  readonly increment: true;
  readonly persistence: "memory-only";
  readonly singleFlight: "generation-local";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L18)

### LOCAL_CACHE_DURABLE_CAPABILITIES

**Signature**

```ts
declare const LOCAL_CACHE_DURABLE_CAPABILITIES: Readonly<{
  readonly increment: true;
  readonly persistence: "restart-recovery";
  readonly singleFlight: "generation-local";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L24)

### LocalCacheCapabilities

**Signature**

```ts
declare const LocalCacheCapabilities: LocalCacheCapabilities;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L14)

### LocalCacheEvictionPolicy

**Signature**

```ts
declare const LocalCacheEvictionPolicy: "lru";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L10)

### LocalCacheKeyError (class)

Preserves the public local cache key error identity and stable error code.

**Signature**

```ts
declare class LocalCacheKeyError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L31)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_KEY_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L32)

### LocalCachePolicy

**Signature**

```ts
declare const LocalCachePolicy: LocalCachePolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L12)

### LocalCachePolicyError (class)

Preserves the public local cache policy error identity and stable error code.

**Signature**

```ts
declare class LocalCachePolicyError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L51)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_POLICY_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L52)

### LocalCacheProvider

**Signature**

```ts
declare const LocalCacheProvider: LocalCacheProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L15)

### LocalCacheProviderOptions

**Signature**

```ts
declare const LocalCacheProviderOptions: LocalCacheProviderOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L11)

### LocalCacheSnapshot

**Signature**

```ts
declare const LocalCacheSnapshot: LocalCacheSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L13)

### LocalCacheStateError (class)

Preserves the public local cache state error identity and stable error code.

**Signature**

```ts
declare class LocalCacheStateError {
  constructor(message = "Cache provider state is invalid");
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L61)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L62)

### LocalCacheValueError (class)

Preserves the public local cache value error identity and stable error code.

**Signature**

```ts
declare class LocalCacheValueError {
  constructor();
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L41)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_CACHE_VALUE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/cache/types.ts#L42)

## `admin-contracts.ts`

### EVENT_ADMIN_PROTOCOL

**Signature**

```ts
declare const EVENT_ADMIN_PROTOCOL: "relkit.events.admin";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L46)

### EVENT_ADMIN_VERSION

**Signature**

```ts
declare const EVENT_ADMIN_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L47)

### EventAdminAction

**Signature**

```ts
declare const EventAdminAction: "retry";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L26)

### EventAdminActionContract

**Signature**

```ts
declare const EventAdminActionContract: EventAdminActionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L42)

### EventAdminActionOutcome

**Signature**

```ts
declare const EventAdminActionOutcome: EventAdminActionOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L27)

### EventAdminActionRecord

**Signature**

```ts
declare const EventAdminActionRecord: EventAdminActionRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L41)

### EventAdminActionRequest

**Signature**

```ts
declare const EventAdminActionRequest: EventAdminActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L39)

### EventAdminActionSink

**Signature**

```ts
declare const EventAdminActionSink: EventAdminActionSink;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L43)

### EventAdminMode

**Signature**

```ts
declare const EventAdminMode: EventAdminMode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L25)

### EventAdminVersion

**Signature**

```ts
declare const EventAdminVersion: EventAdminVersion;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L28)

### EventContract

**Signature**

```ts
declare const EventContract: EventContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L31)

### EventContractInput

**Signature**

```ts
declare const EventContractInput: EventContractInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L30)

### EventDeadLetterContract

**Signature**

```ts
declare const EventDeadLetterContract: EventDeadLetterContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L35)

### EventDeliveryContract

**Signature**

```ts
declare const EventDeliveryContract: EventDeliveryContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L34)

### EventPublicationContract

**Signature**

```ts
declare const EventPublicationContract: EventPublicationContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L33)

### EventQueryContract

**Signature**

```ts
declare const EventQueryContract: EventQueryContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L38)

### EventQueryRequest

**Signature**

```ts
declare const EventQueryRequest: EventQueryRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L37)

### EventRetryRequest

**Signature**

```ts
declare const EventRetryRequest: EventAdminActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L40)

### EventTriggerCapabilityContract

**Signature**

```ts
declare const EventTriggerCapabilityContract: EventTriggerCapabilityContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L36)

### EventTriggerContract

**Signature**

```ts
declare const EventTriggerContract: EventTriggerContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L32)

### EventVersioned

**Signature**

```ts
declare const EventVersioned: EventVersioned;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.ts#L29)

## `admin-contracts.types.ts`

### EventAdminAction (type alias)

Supported audited event administration action.

**Signature**

```ts
type EventAdminAction = "retry";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L10)

### EventAdminActionContract (interface)

Versioned mutation response containing status and audit record.

**Signature**

```ts
export interface EventAdminActionContract extends EventAdminVersion {
  readonly action: EventAdminAction;
  readonly status: EventDeliveryContract;
  readonly record: EventAdminActionRecord;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L157)

### EventAdminActionOutcome (type alias)

Whether an event administration action was applied or rejected.

**Signature**

```ts
type EventAdminActionOutcome = "applied" | "rejected";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L13)

### EventAdminActionRecord (interface)

Immutable audit record for an applied or rejected event mutation.

**Signature**

```ts
export interface EventAdminActionRecord extends EventAdminVersion {
  readonly actionId: string;
  readonly action: EventAdminAction;
  readonly deliveryId: string;
  readonly eventInstanceId?: string;
  readonly triggerId?: string;
  readonly mode: EventAdminMode;
  readonly outcome: EventAdminActionOutcome;
  readonly requestedAt: number;
  readonly fromState?: Exclude<JobQueueState, "accepted">;
  readonly toState?: Exclude<JobQueueState, "accepted">;
  readonly errorCode?: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L141)

### EventAdminActionRequest (interface)

Event mutation request carrying delivery identity and optional audit reason.

**Signature**

```ts
export interface EventAdminActionRequest {
  readonly protocol?: typeof EVENT_ADMIN_PROTOCOL;
  readonly version?: typeof EVENT_ADMIN_VERSION;
  readonly deliveryId: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L130)

### EventAdminActionSink (type alias)

Optional audit sink isolated from the event action outcome.

**Signature**

```ts
type EventAdminActionSink = (record: EventAdminActionRecord) => MaybePromise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L164)

### EventAdminMode (type alias)

Environment mode controlling event administration mutations.

**Signature**

```ts
type EventAdminMode = "development" | "test" | "production";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L7)

### EventAdminVersion (interface)

Protocol identity carried by event administration contracts.

**Signature**

```ts
export interface EventAdminVersion {
  readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
  readonly version: typeof EVENT_ADMIN_VERSION;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L16)

### EventContract (interface)

Versioned declared event identity and schema metadata for inspection.

**Signature**

```ts
export interface EventContract extends EventVersioned, EventContractInput {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L37)

### EventContractInput (interface)

The serializable event contract registered by the active graph.

**Signature**

```ts
export interface EventContractInput {
  readonly id: string;
  readonly version: number;
  readonly input: JsonValue;
  readonly sensitiveFields?: readonly string[];
  readonly source?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L28)

### EventDeadLetterContract (interface)

Versioned dead-letter status with safe retry/failure metadata.

**Signature**

```ts
export interface EventDeadLetterContract extends EventDeliveryContract {
  readonly state: "dead-lettered";
  readonly failure: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L87)

### EventDeliveryContract (interface)

Safe delivery state shared by current and dead-lettered attempts.

**Signature**

```ts
export interface EventDeliveryContract extends EventVersioned {
  readonly cursor: number;
  readonly sequence: number;
  readonly deliveryId: string;
  readonly eventInstanceId: string;
  readonly eventId: string;
  readonly version: number;
  readonly triggerId: string;
  readonly state: Exclude<JobQueueState, "accepted">;
  readonly attempt: number;
  readonly duplicate: boolean;
  readonly timestamp: number;
  readonly leaseExpiresAt?: number;
  readonly failure?: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L70)

### EventPublicationContract (interface)

Safe publication metadata; payload data is intentionally not projected.

**Signature**

```ts
export interface EventPublicationContract extends EventVersioned {
  readonly sequence: number;
  readonly timestamp: number;
  readonly accepted: true;
  readonly instanceId: string;
  readonly eventId: string;
  readonly version: number;
  readonly occurredAt: string;
  readonly publishedAt: string;
  readonly key?: string;
  readonly correlationId?: string;
  readonly originRequestId?: string;
  readonly producerTraceId?: string;
  readonly attributes: Readonly<Record<string, string | number | boolean>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L53)

### EventQueryContract (interface)

Versioned bounded event, publication and delivery inspection response.

**Signature**

```ts
export interface EventQueryContract extends EventAdminVersion {
  readonly events: readonly EventContract[];
  readonly triggers: readonly EventTriggerContract[];
  readonly capabilities: readonly EventTriggerCapabilityContract[];
  readonly publications: readonly EventPublicationContract[];
  readonly items: readonly EventDeliveryContract[];
  readonly deliveries: readonly EventDeliveryContract[];
  readonly deadLetters: readonly EventDeadLetterContract[];
  readonly nextCursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L118)

### EventQueryRequest (interface)

Event, trigger, state and pagination filters for local inspection.

**Signature**

```ts
export interface EventQueryRequest {
  readonly protocol?: typeof EVENT_ADMIN_PROTOCOL;
  readonly version?: typeof EVENT_ADMIN_VERSION;
  readonly eventId?: string;
  readonly eventVersion?: number;
  readonly triggerId?: string;
  readonly state?: Exclude<JobQueueState, "accepted">;
  readonly states?: readonly Exclude<JobQueueState, "accepted">[];
  readonly cursor?: string;
  readonly limit?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L105)

### EventRetryRequest (type alias)

Dead-letter retry request preserving event admin protocol identity.

**Signature**

```ts
type EventRetryRequest = EventAdminActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L138)

### EventTriggerCapabilityContract (interface)

Versioned truthful delivery capabilities for a registered trigger.

**Signature**

```ts
export interface EventTriggerCapabilityContract extends EventAdminVersion {
  readonly triggerId: string;
  readonly delivery: "ephemeral" | "durable";
  readonly persistence: "none" | "restart-recovery";
  readonly restartRecovery: boolean;
  readonly atLeastOnce: boolean;
  readonly exactlyOnce: false;
  readonly ordering: "unsupported";
  readonly orderedByKey: false;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L93)

### EventTriggerContract (interface)

Exact event and delivery metadata for one generated event trigger.

**Signature**

```ts
export interface EventTriggerContract extends EventAdminVersion {
  readonly id: string;
  readonly targetFunctionId?: string;
  readonly eventId: string;
  readonly eventVersion: number;
  readonly delivery: "ephemeral" | "durable";
  readonly profile?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L40)

### EventVersioned (interface)

Protocol identity carried by public event inspection contracts.

**Signature**

```ts
export interface EventVersioned {
  readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
  readonly protocolVersion: typeof EVENT_ADMIN_VERSION;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-contracts.types.ts#L22)

## `admin-errors.ts`

Preserves the public event admin error identity and stable error code.

### EventAdminError (class)

Preserves the public event admin error identity and stable error code.

**Signature**

```ts
declare class EventAdminError { constructor(
    readonly code: string,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin-errors.ts#L2)

## `admin.ts`

### "./admin-contracts.js" (namespace export)

Re-exports all named exports from the "./admin-contracts.js" module.

**Signature**

```ts
export * from "./admin-contracts.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.ts#L39)

### EventAdmin

**Signature**

```ts
declare const EventAdmin: EventAdmin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.ts#L37)

### EventAdminError

**Signature**

```ts
declare const EventAdminError: typeof EventAdminError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.ts#L40)

### EventAdminOptions

**Signature**

```ts
declare const EventAdminOptions: EventAdminOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.ts#L37)

### createEventAdmin

Exposes versioned event inspection and an audited local dead-letter retry.

**Signature**

```ts
declare const createEventAdmin: (router: EventRouter, options?: EventAdminOptions) => EventAdmin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.ts#L47)

## `admin.types.ts`

### EventAdmin (interface)

Versioned event inspection and audited dead-letter retry interface.

**Signature**

```ts
export interface EventAdmin {
  readonly protocol: typeof EVENT_ADMIN_PROTOCOL;
  readonly version: typeof EVENT_ADMIN_VERSION;
  readonly query: (request?: EventQueryRequest) => EventQueryContract;
  readonly retry: (request: string | EventAdminActionRequest) => Promise<EventAdminActionContract>;
  readonly actions: () => readonly EventAdminActionRecord[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.types.ts#L24)

### EventAdminOptions (interface)

Event administration mode plus isolated audit and clock hooks.

**Signature**

```ts
export interface EventAdminOptions {
  readonly mode?: EventAdminMode;
  readonly environment?: EventAdminMode;
  readonly enabled?: boolean;
  readonly now?: () => number;
  readonly createActionId?: () => string;
  readonly onAction?: EventAdminActionSink;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/admin.types.ts#L14)

## `delivery-types.ts`

### EVENT_DELIVERY_CAPABILITIES

**Signature**

```ts
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
  readonly persistence: "restart-recovery";
  readonly restartRecovery: true;
  readonly atLeastOnce: true;
  readonly exactlyOnce: false;
  readonly ordering: "unsupported";
  readonly orderedByKey: false;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L24)

### EventDelivery

**Signature**

```ts
declare const EventDelivery: EventDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L21)

### EventDeliveryBinding

**Signature**

```ts
declare const EventDeliveryBinding: EventDeliveryBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L16)

### EventDeliveryBoundary

**Signature**

```ts
declare const EventDeliveryBoundary: EventDeliveryBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L14)

### EventDeliveryCapabilities

**Signature**

```ts
declare const EventDeliveryCapabilities: Readonly<{
  readonly persistence: "restart-recovery";
  readonly restartRecovery: true;
  readonly atLeastOnce: true;
  readonly exactlyOnce: false;
  readonly ordering: "unsupported";
  readonly orderedByKey: false;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L13)

### EventDeliveryInvocationOptions

**Signature**

```ts
declare const EventDeliveryInvocationOptions: EventDeliveryInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L15)

### EventDeliveryLedgerRecord

**Signature**

```ts
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L19)

### EventDeliveryOptions

**Signature**

```ts
declare const EventDeliveryOptions: EventDeliveryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L17)

### EventDeliveryResult

**Signature**

```ts
declare const EventDeliveryResult: EventDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L18)

### EventDeliverySnapshot

**Signature**

```ts
declare const EventDeliverySnapshot: EventDeliverySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery-types.ts#L20)

## `delivery.ts`

### EVENT_DELIVERY_CAPABILITIES

**Signature**

```ts
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
  readonly persistence: "restart-recovery";
  readonly restartRecovery: true;
  readonly atLeastOnce: true;
  readonly exactlyOnce: false;
  readonly ordering: "unsupported";
  readonly orderedByKey: false;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L35)

### EventDelivery

**Signature**

```ts
declare const EventDelivery: EventDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L37)

### EventDeliveryBinding

**Signature**

```ts
declare const EventDeliveryBinding: EventDeliveryBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L38)

### EventDeliveryBoundary

**Signature**

```ts
declare const EventDeliveryBoundary: EventDeliveryBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L39)

### EventDeliveryLedgerRecord

**Signature**

```ts
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L40)

### EventDeliveryOptions

**Signature**

```ts
declare const EventDeliveryOptions: EventDeliveryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L41)

### EventDeliveryResult

**Signature**

```ts
declare const EventDeliveryResult: EventDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L42)

### EventDeliverySnapshot

**Signature**

```ts
declare const EventDeliverySnapshot: EventDeliverySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L43)

### LocalEventDeliveryService (class)

One trigger owns durable admission, retry transitions and handler concurrency.

**Signature**

```ts
declare class LocalEventDeliveryService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L47)

### createEventDelivery

Opens durable at-least-once delivery behind its existing Promise API.

**Signature**

```ts
declare const createEventDelivery: (
  root: string,
  binding: EventDeliveryBinding,
  options?: EventDeliveryOptions,
) => Promise<EventDelivery>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L59)

### eventDeliveryLayer

Provides one trigger's delivery service with scope-owned shutdown.

**Signature**

```ts
declare const eventDeliveryLayer: (
  root: string,
  binding: EventDeliveryBinding,
  options?: EventDeliveryOptions,
) => Layer.Layer<LocalEventDeliveryService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L75)

### makeEventDelivery

Recovers a trigger and composes its serialized admission and bounded execution.

**Signature**

```ts
declare const makeEventDelivery: (
  root: string,
  binding: EventDeliveryBinding,
  options?: EventDeliveryOptions | undefined,
) => Effect.Effect<EventDeliveryEffects, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.ts#L95)

## `delivery.types.ts`

### EventDelivery (interface)

Compatibility interface for accepting, executing and inspecting durable deliveries.

**Signature**

```ts
export interface EventDelivery {
  readonly triggerId: string;
  readonly capabilities: EventDeliveryCapabilities;
  readonly accept: (envelope: UnknownEventEnvelope) => Promise<EventDeliveryResult>;
  readonly deliver: (envelope: UnknownEventEnvelope) => Promise<EventDeliveryResult>;
  readonly runNext: (deliveryId?: string) => Promise<EventDeliveryResult | undefined>;
  readonly retry: (deliveryId: string) => Promise<EventDeliveryResult>;
  readonly drain: () => Promise<readonly EventDeliveryResult[]>;
  readonly recover: (now?: number) => Promise<readonly EventDeliveryLedgerRecord[]>;
  readonly snapshot: () => EventDeliverySnapshot;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L82)

### EventDeliveryBinding (interface)

Trigger identity and executable target for a durable delivery owner.

**Signature**

```ts
export interface EventDeliveryBinding {
  readonly id: string;
  readonly invoke: (
    envelope: UnknownEventEnvelope,
    options?: EventDeliveryInvocationOptions,
  ) => Promise<unknown>;
  readonly profile?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L22)

### EventDeliveryBoundary (type alias)

Durable delivery commit milestones exposed to hooks.

**Signature**

```ts
type EventDeliveryBoundary = JobStoreBoundary | "handler-success-before-ack";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L12)

### EventDeliveryCapabilities (type alias)

Actual durability, restart, overflow and cancellation guarantees.

**Signature**

```ts
type EventDeliveryCapabilities = typeof EVENT_DELIVERY_CAPABILITIES;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L9)

### EventDeliveryInvocationOptions (interface)

Attempt metadata and cancellation supplied to a delivery target.

**Signature**

```ts
export interface EventDeliveryInvocationOptions {
  readonly attempt: number;
  readonly replayed: boolean;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L15)

### EventDeliveryLedgerRecord (interface)

Persisted delivery envelope joined with its latest queue state.

**Signature**

```ts
export interface EventDeliveryLedgerRecord extends EventDeliveryRecord {
  readonly cursor: number;
  readonly state: EventDeliveryResult["state"];
  readonly attempt: number;
  readonly duplicate: boolean;
  readonly leaseOwner?: string;
  readonly leaseExpiresAt?: number;
  readonly failure?: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L62)

### EventDeliveryOptions (interface)

Backlog, concurrency, retry and durable-boundary configuration.

**Signature**

```ts
export interface EventDeliveryOptions {
  readonly now?: () => number;
  readonly random?: () => number;
  readonly ownerToken?: string;
  readonly leaseDurationMs?: number;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly onBoundary?: (boundary: EventDeliveryBoundary) => void | Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L35)

### EventDeliveryResult (interface)

Delivery outcome including acceptance and actual persistence guarantees.

**Signature**

```ts
export interface EventDeliveryResult {
  readonly deliveryId: string;
  readonly triggerId: string;
  readonly eventInstanceId: string;
  readonly accepted: boolean;
  readonly persisted: boolean;
  readonly status: "queued" | "completed" | "failed";
  readonly state: "available" | "leased" | "delayed" | "completed" | "dead-lettered";
  readonly attempt: number;
  readonly duplicate: boolean;
  readonly value?: unknown;
  readonly error?: unknown;
  readonly failure?: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L46)

### EventDeliverySnapshot (interface)

Safe delivery counters and durable ledger inspection.

**Signature**

```ts
export interface EventDeliverySnapshot {
  readonly cursor: number;
  readonly records: readonly EventDeliveryRecord[];
  readonly ledger: readonly EventDeliveryLedgerRecord[];
  readonly counts: JobQueueCounts;
  readonly capabilities: typeof EVENT_DELIVERY_CAPABILITIES;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/delivery.types.ts#L73)

## `ephemeral.ts`

### DEFAULT_EPHEMERAL_CAPACITY

**Signature**

```ts
declare const DEFAULT_EPHEMERAL_CAPACITY: 100;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L24)

### EPHEMERAL_DELIVERY_CAPABILITIES

**Signature**

```ts
declare const EPHEMERAL_DELIVERY_CAPABILITIES: Readonly<{
  readonly persistence: "none";
  readonly restartRecovery: false;
  readonly dropPolicy: "drop-newest";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L25)

### EphemeralDelivery

**Signature**

```ts
declare const EphemeralDelivery: EphemeralDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L20)

### EphemeralDeliveryEffects

**Signature**

```ts
declare const EphemeralDeliveryEffects: EphemeralDeliveryEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L21)

### EphemeralDeliveryResult

**Signature**

```ts
declare const EphemeralDeliveryResult: EphemeralDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L18)

### EphemeralDeliverySnapshot

**Signature**

```ts
declare const EphemeralDeliverySnapshot: EphemeralDeliverySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L19)

### LocalEphemeralService (class)

Capacity, counters and native handler completion share one service owner.

**Signature**

```ts
declare class LocalEphemeralService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L32)

### createEphemeralDelivery

Constructs a transient delivery service behind the Promise boundary.

**Signature**

```ts
declare const createEphemeralDelivery: (
  invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
  requestedCapacity?: number,
) => EphemeralDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L43)

### ephemeralDeliveryLayer

Supplies transient delivery and drains admitted handlers at scope exit.

**Signature**

```ts
declare const ephemeralDeliveryLayer: (
  invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
  capacity?: number,
) => Layer.Layer<LocalEphemeralService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L61)

### makeEphemeralDelivery

Owns bounded admission and safe counters using Ref and Semaphore.

**Signature**

```ts
declare const makeEphemeralDelivery: (
  invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
  capacity?: any,
) => Effect.Effect<EphemeralDeliveryEffects, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.ts#L77)

## `ephemeral.types.ts`

### EphemeralDelivery (interface)

Public transient delivery interface with explicit drain and synchronous counters.

**Signature**

```ts
export interface EphemeralDelivery {
  readonly deliver: (envelope: UnknownEventEnvelope) => Promise<EphemeralDeliveryResult>;
  readonly drain: () => Promise<void>;
  readonly snapshot: () => EphemeralDeliverySnapshot;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.types.ts#L31)

### EphemeralDeliveryEffects (interface)

Effect contract for bounded transient delivery without a hidden backlog.

**Signature**

```ts
export interface EphemeralDeliveryEffects {
  readonly deliver: (envelope: UnknownEventEnvelope) => Effect.Effect<EphemeralDeliveryResult>;
  readonly drain: () => Effect.Effect<void>;
  readonly snapshot: () => Effect.Effect<EphemeralDeliverySnapshot>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.types.ts#L38)

### EphemeralDeliveryResult (interface)

Transient handler outcome with explicit nonpersistent capacity guarantees.

**Signature**

```ts
export interface EphemeralDeliveryResult {
  readonly accepted: boolean;
  readonly persisted: false;
  readonly status: "completed" | "failed" | "dropped";
  readonly capacity: number;
  readonly dropPolicy: "drop-newest";
  readonly restartRecovery: false;
  readonly value?: unknown;
  readonly error?: unknown;
  readonly dropReason?: "capacity";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.types.ts#L5)

### EphemeralDeliverySnapshot (interface)

Safe admission, completion, failure and overflow counters.

**Signature**

```ts
export interface EphemeralDeliverySnapshot {
  readonly capacity: number;
  readonly inFlight: number;
  readonly admitted: number;
  readonly completed: number;
  readonly failed: number;
  readonly dropped: number;
  readonly persistence: "none";
  readonly restartRecovery: false;
  readonly dropPolicy: "drop-newest";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/ephemeral.types.ts#L18)

## `log.ts`

### EVENT_LOG_VERSION

**Signature**

```ts
declare const EVENT_LOG_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L31)

### EventLog

**Signature**

```ts
declare const EventLog: EventLog;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L27)

### EventLogBoundary

**Signature**

```ts
declare const EventLogBoundary: JobStoreBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L22)

### EventLogInput

**Signature**

```ts
declare const EventLogInput: EventLogInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L28)

### EventLogOptions

**Signature**

```ts
declare const EventLogOptions: EventLogOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L24)

### EventLogPaths

**Signature**

```ts
declare const EventLogPaths: JobStorePaths;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L23)

### EventLogRecord

**Signature**

```ts
declare const EventLogRecord: EventLogRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L25)

### EventLogSnapshot

**Signature**

```ts
declare const EventLogSnapshot: EventLogSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L26)

### EventLogStateError (class)

Preserves the public event log state error identity and stable error code.

**Signature**

```ts
declare class EventLogStateError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L34)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_LOG_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L35)

### createEventLog

Opens the durable accepted-event log and repairs invalid records on startup.

**Signature**

```ts
declare const createEventLog: (
  requestedRoot: string,
  options?: EventLogOptions,
) => Promise<EventLog>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L56)

### createEventLogPaths

Builds the stable event journal and metadata paths below the owned root.

**Signature**

```ts
declare const createEventLogPaths: (root: string) => EventLogPaths;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.ts#L47)

## `log.types.ts`

### EventLog (interface)

Promise event log operations and synchronous recovered snapshot.

**Signature**

```ts
export interface EventLog {
  readonly root: string;
  readonly paths: EventLogPaths;
  readonly append: (envelope: EventLogInput) => Promise<EventLogRecord>;
  readonly snapshot: () => EventLogSnapshot;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L38)

### EventLogBoundary (type alias)

Durable event-log commit milestones exposed to hooks.

**Signature**

```ts
type EventLogBoundary = JobStoreBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L12)

### EventLogInput (type alias)

Event envelope input before journal sequence assignment.

**Signature**

```ts
type EventLogInput = UnknownEventEnvelope | EventPublishResult<string, number, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L47)

### EventLogOptions (interface)

Event-log validation and durable commit hook configuration.

**Signature**

```ts
export interface EventLogOptions extends Pick<JobStoreOptions, "now" | "onBoundary"> {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L18)

### EventLogPaths (type alias)

Owned paths for durable event records and derived metadata.

**Signature**

```ts
type EventLogPaths = ReturnType<typeof createJobStorePaths>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L15)

### EventLogRecord (interface)

Accepted event envelope with its durable journal identity.

**Signature**

```ts
export interface EventLogRecord {
  readonly version: typeof EVENT_LOG_VERSION;
  readonly sequence: number;
  readonly kind: "accepted";
  readonly accepted: true;
  readonly timestamp: number;
  readonly envelope: UnknownEventEnvelope;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L21)

### EventLogSnapshot (interface)

Immutable persisted event records and recovery metadata.

**Signature**

```ts
export interface EventLogSnapshot {
  readonly records: readonly EventLogRecord[];
  readonly index: JobStoreIndex;
  readonly checkpoint: JobStoreCheckpoint;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/log.types.ts#L31)

## `provider.ts`

### LocalEventEffects

**Signature**

```ts
declare const LocalEventEffects: LocalEventEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L19)

### LocalEventProvider

**Signature**

```ts
declare const LocalEventProvider: LocalEventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L19)

### LocalEventService (class)

Publication and delivery orchestration for one local event provider.

**Signature**

```ts
declare class LocalEventService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L22)

### createLocalEventProvider

Acquires a scoped event provider behind its established Promise surface.

**Signature**

```ts
declare const createLocalEventProvider: (root: string) => Promise<LocalEventProvider>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L31)

### localEventLayer

Supplies publication and its supervised delivery workers as one layer.

**Example**

```ts
import { Effect } from "effect";
import { LocalEventService, localEventLayer } from "./provider.js";

const program = Effect.gen(function* () {
  const events = yield* LocalEventService;
  yield* events.health();
});
await Effect.runPromise(program.pipe(Effect.provide(localEventLayer("/tmp/example-events"))));
```

**Signature**

```ts
declare const localEventLayer: (
  root: string,
) => Layer.Layer<LocalEventService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L74)

### makeLocalEventService

Owns log, router, worker fibers and background failure state.

**Signature**

```ts
declare const makeLocalEventService: (
  root: string,
) => Effect.Effect<LocalEventEffects, LocalOperationError, Scope.Scope>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.ts#L83)

## `provider.types.ts`

### LocalEventEffects (interface)

Effect event methods owned by the provider scope.

**Signature**

```ts
export interface LocalEventEffects {
  readonly query: (
    request?: EventQueryRequest,
  ) => Effect.Effect<EventQueryContract, LocalOperationError>;
  readonly registerContract: (contract: unknown) => Effect.Effect<void, LocalOperationError>;
  readonly registerTrigger: (
    binding: EventRouterTrigger,
  ) => Effect.Effect<void, LocalOperationError>;
  readonly publish: (
    payload: unknown,
    options: EventPublishOptions,
    context: EventOperationContext,
  ) => Effect.Effect<EventProviderResult, LocalOperationError>;
  readonly health: () => Effect.Effect<void, LocalOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.types.ts#L21)

### LocalEventProvider (interface)

Public event registration, publication and explicit close operations.

**Signature**

```ts
export interface LocalEventProvider extends EventProvider {
  readonly registerContract: EventRouter["registerContract"];
  readonly registerTrigger: EventRouter["registerTrigger"];
  readonly query: (request?: EventQueryRequest) => Promise<EventQueryContract>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/provider.types.ts#L13)

## `router-model.types.ts`

### EventDeliveryResult (interface)

Delivery outcome including acceptance and actual persistence guarantees.

**Signature**

```ts
export interface EventDeliveryResult {
  readonly triggerId: string;
  readonly delivery: "ephemeral" | "durable";
  readonly deliveryId?: string;
  readonly eventInstanceId?: string;
  readonly accepted: boolean;
  readonly persisted: boolean;
  readonly status: "queued" | "completed" | "failed" | "dropped";
  readonly state?: "available" | "leased" | "delayed" | "completed" | "dead-lettered";
  readonly attempt?: number;
  readonly duplicate?: boolean;
  readonly capacity?: number;
  readonly dropPolicy?: "drop-newest";
  readonly restartRecovery?: false;
  readonly dropReason?: "capacity";
  readonly value?: unknown;
  readonly error?: unknown;
  readonly failure?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L13)

### EventFanoutResult (interface)

Publication result containing each matching trigger delivery outcome.

**Signature**

```ts
export interface EventFanoutResult {
  readonly event: UnknownEventEnvelope;
  readonly matchedTriggerIds: readonly string[];
  readonly deliveries: readonly EventDeliveryResult[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L92)

### EventRouter (interface)

Compatibility router interface for registration, fanout, inspection and lifecycle.

**Signature**

```ts
export interface EventRouter {
  readonly root: string;
  readonly registerContract: (contract: unknown) => Promise<void>;
  readonly registerTrigger: (binding: EventRouterTrigger) => Promise<void>;
  readonly route: (
    event: EventRouterInput,
    options?: EventRouterRouteOptions,
  ) => Promise<EventFanoutResult>;
  readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
  readonly drain: () => Promise<readonly EventDeliveryResult[]>;
  readonly retry: (deliveryId: string) => Promise<EventDeliveryResult>;
  readonly snapshot: () => EventRouterSnapshot;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L99)

### EventRouterInput (type alias)

Publication input accepted as a log record or event envelope.

**Signature**

```ts
type EventRouterInput = EventLogRecord | EventLogInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L115)

### EventRouterOptions (interface)

Storage and delivery construction settings for the local router.

**Signature**

```ts
export interface EventRouterOptions {
  readonly onBoundary?: (
    boundary: EventDeliveryBoundary,
    triggerId: string,
  ) => void | Promise<void>;
  readonly now?: () => number;
  readonly random?: () => number;
  readonly ownerToken?: string;
  readonly leaseDurationMs?: number;
  readonly ephemeralCapacity?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L51)

### EventRouterRouteOptions (interface)

Fanout options controlling immediate worker execution.

**Signature**

```ts
export interface EventRouterRouteOptions {
  readonly run?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L64)

### EventRouterSnapshot (interface)

Immutable contracts, triggers, publications and delivery status inspection.

**Signature**

```ts
export interface EventRouterSnapshot {
  readonly records: readonly EventDeliveryRecord[];
  readonly contracts: readonly EventContractInput[];
  readonly triggers: readonly EventTriggerSnapshot[];
  readonly publications: readonly EventLogRecord[];
  readonly deliveries: readonly EventDeliveryLedgerRecord[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L69)

### EventRouterTrigger (interface)

Declared trigger identity, event match and executable target binding.

**Signature**

```ts
export interface EventRouterTrigger {
  readonly id: string;
  readonly targetFunctionId?: string;
  readonly eventId: string;
  readonly eventVersion: number;
  readonly delivery: "ephemeral" | "durable";
  readonly profile?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
  readonly invoke: (
    envelope: UnknownEventEnvelope,
    options?: EventDeliveryInvocationOptions,
  ) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L34)

### EventTriggerSnapshot (interface)

Safe trigger configuration and runtime delivery counters.

**Signature**

```ts
export interface EventTriggerSnapshot {
  readonly ephemeral?: import("./ephemeral.js").EphemeralDeliverySnapshot;
  readonly id: string;
  readonly targetFunctionId?: string;
  readonly eventId: string;
  readonly eventVersion: number;
  readonly delivery: "ephemeral" | "durable";
  readonly profile?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-model.types.ts#L78)

## `router-records.ts`

### EVENT_DELIVERY_VERSION

**Signature**

```ts
declare const EVENT_DELIVERY_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L8)

### EventDeliveryRecord

**Signature**

```ts
declare const EventDeliveryRecord: EventDeliveryRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L6)

### EventRouterStateError (class)

Preserves the public event router state error identity and stable error code.

**Signature**

```ts
declare class EventRouterStateError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L11)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_EVENT_ROUTER_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L12)

### appendDeliveryAcceptance

Appends delivery acceptance before acknowledging durable fanout.

**Signature**

```ts
declare const appendDeliveryAcceptance: (
  store: JobStore,
  envelope: UnknownEventEnvelope,
  triggerId: string,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L86)

### makeDeliveryId

Derives a stable identity from the publication and target trigger.

**Signature**

```ts
declare const makeDeliveryId: (eventInstanceId: string, triggerId: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L74)

### normalizeDelivery

Validates the durable or ephemeral delivery mode.

**Signature**

```ts
declare const normalizeDelivery: (value: unknown) => "ephemeral" | "durable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L24)

### normalizeEnvelope

Validates the envelope and copies its JSON payload and safe attributes.

**Signature**

```ts
declare const normalizeEnvelope: (input: unknown) => UnknownEventEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L35)

### toDeliveryRecord

Projects a durable journal record into its delivery identity and envelope.

**Signature**

```ts
declare const toDeliveryRecord: (record: JobRecord) => EventDeliveryRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L56)

### toJson

Copies an unknown value into canonical JSON for stable durable encoding.

**Signature**

```ts
declare const toJson: (value: DeliveryData) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L109)

### validateDeliveryData

Rejects malformed delivery identities or envelopes during record replay.

**Signature**

```ts
declare const validateDeliveryData: (value: JsonValue) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.ts#L65)

## `router-records.types.ts`

### DeliveryData (interface)

Versioned persisted delivery identity and canonical envelope payload.

**Signature**

```ts
export interface DeliveryData {
  readonly version: typeof EVENT_DELIVERY_VERSION;
  readonly deliveryId: string;
  readonly eventInstanceId: string;
  readonly triggerId: string;
  readonly envelope: UnknownEventEnvelope;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.types.ts#L16)

### EventDeliveryRecord (interface)

Durable acceptance record connecting one publication and trigger.

**Signature**

```ts
export interface EventDeliveryRecord {
  readonly version: typeof EVENT_DELIVERY_VERSION;
  readonly sequence: number;
  readonly timestamp: number;
  readonly deliveryId: string;
  readonly eventInstanceId: string;
  readonly triggerId: string;
  readonly envelope: UnknownEventEnvelope;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router-records.types.ts#L5)

## `router.ts`

### EVENT_DELIVERY_VERSION

**Signature**

```ts
declare const EVENT_DELIVERY_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L47)

### EventDeliveryRecord

**Signature**

```ts
declare const EventDeliveryRecord: EventDeliveryRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L48)

### EventDeliveryResult

**Signature**

```ts
declare const EventDeliveryResult: EventDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L37)

### EventFanoutResult

**Signature**

```ts
declare const EventFanoutResult: EventFanoutResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L38)

### EventRouter

**Signature**

```ts
declare const EventRouter: EventRouter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L39)

### EventRouterInput

**Signature**

```ts
declare const EventRouterInput: EventRouterInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L40)

### EventRouterOptions

**Signature**

```ts
declare const EventRouterOptions: EventRouterOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L41)

### EventRouterRouteOptions

**Signature**

```ts
declare const EventRouterRouteOptions: EventRouterRouteOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L42)

### EventRouterSnapshot

**Signature**

```ts
declare const EventRouterSnapshot: EventRouterSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L43)

### EventRouterStateError

**Signature**

```ts
declare const EventRouterStateError: typeof EventRouterStateError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L47)

### EventRouterTrigger

**Signature**

```ts
declare const EventRouterTrigger: EventRouterTrigger;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L44)

### EventTriggerSnapshot

**Signature**

```ts
declare const EventTriggerSnapshot: EventTriggerSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L45)

### createEventRouter

Routes accepted envelopes to independently delivered exact-event triggers.

**Signature**

```ts
declare const createEventRouter: (
  requestedRoot: string,
  options?: EventRouterOptions,
) => Promise<EventRouter>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/events/router.ts#L54)

## `index.ts`

### "./agent-state/index.js" (namespace export)

Re-exports all named exports from the "./agent-state/index.js" module.

**Signature**

```ts
export * from "./agent-state/index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L56)

### "./buckets/index.js" (namespace export)

Re-exports all named exports from the "./buckets/index.js" module.

**Signature**

```ts
export * from "./buckets/index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L1)

### "./cache/index.js" (namespace export)

Re-exports all named exports from the "./cache/index.js" module.

**Signature**

```ts
export * from "./cache/index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L2)

### "./events/admin.js" (namespace export)

Re-exports all named exports from the "./events/admin.js" module.

**Signature**

```ts
export * from "./events/admin.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L33)

### "./events/log.js" (namespace export)

Re-exports all named exports from the "./events/log.js" module.

**Signature**

```ts
export * from "./events/log.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L29)

### "./events/router.js" (namespace export)

Re-exports all named exports from the "./events/router.js" module.

**Signature**

```ts
export * from "./events/router.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L30)

### "./jobs/admin.js" (namespace export)

Re-exports all named exports from the "./jobs/admin.js" module.

**Signature**

```ts
export * from "./jobs/admin.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L28)

### "./jobs/queue-utils.js" (namespace export)

Re-exports all named exports from the "./jobs/queue-utils.js" module.

**Signature**

```ts
export * from "./jobs/queue-utils.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L4)

### "./jobs/queue.js" (namespace export)

Re-exports all named exports from the "./jobs/queue.js" module.

**Signature**

```ts
export * from "./jobs/queue.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L3)

### "./jobs/retry.js" (namespace export)

Re-exports all named exports from the "./jobs/retry.js" module.

**Signature**

```ts
export * from "./jobs/retry.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L16)

### "./realtime/index.js" (namespace export)

Re-exports all named exports from the "./realtime/index.js" module.

**Signature**

```ts
export * from "./realtime/index.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L55)

### "./runtime-capabilities.js" (namespace export)

Re-exports all named exports from the "./runtime-capabilities.js" module.

**Signature**

```ts
export * from "./runtime-capabilities.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L54)

### CompiledSchedule

**Signature**

```ts
declare const CompiledSchedule: CompiledSchedule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L19)

### DEFAULT_EPHEMERAL_CAPACITY

**Signature**

```ts
declare const DEFAULT_EPHEMERAL_CAPACITY: 100;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L36)

### DurableEventDeliveryResult

**Signature**

```ts
declare const DurableEventDeliveryResult: EventDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L51)

### EPHEMERAL_DELIVERY_CAPABILITIES

**Signature**

```ts
declare const EPHEMERAL_DELIVERY_CAPABILITIES: Readonly<{
  readonly persistence: "none";
  readonly restartRecovery: false;
  readonly dropPolicy: "drop-newest";
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L37)

### EVENT_DELIVERY_CAPABILITIES

**Signature**

```ts
declare const EVENT_DELIVERY_CAPABILITIES: Readonly<{
  readonly persistence: "restart-recovery";
  readonly restartRecovery: true;
  readonly atLeastOnce: true;
  readonly exactlyOnce: false;
  readonly ordering: "unsupported";
  readonly orderedByKey: false;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L44)

### EphemeralDelivery

**Signature**

```ts
declare const EphemeralDelivery: EphemeralDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L40)

### EphemeralDeliveryResult

**Signature**

```ts
declare const EphemeralDeliveryResult: EphemeralDeliveryResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L41)

### EphemeralDeliverySnapshot

**Signature**

```ts
declare const EphemeralDeliverySnapshot: EphemeralDeliverySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L42)

### EventDelivery

**Signature**

```ts
declare const EventDelivery: EventDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L46)

### EventDeliveryBinding

**Signature**

```ts
declare const EventDeliveryBinding: EventDeliveryBinding;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L47)

### EventDeliveryBoundary

**Signature**

```ts
declare const EventDeliveryBoundary: EventDeliveryBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L48)

### EventDeliveryLedgerRecord

**Signature**

```ts
declare const EventDeliveryLedgerRecord: EventDeliveryLedgerRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L49)

### EventDeliveryOptions

**Signature**

```ts
declare const EventDeliveryOptions: EventDeliveryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L50)

### EventDeliverySnapshot

**Signature**

```ts
declare const EventDeliverySnapshot: EventDeliverySnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L52)

### JobRecord

**Signature**

```ts
declare const JobRecord: {
  readonly version: 1;
  readonly sequence: number;
  readonly instanceId: string;
  readonly kind: string;
  readonly timestamp: number;
  readonly data: Json;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L7)

### JobRecordInput

**Signature**

```ts
declare const JobRecordInput: JobRecordInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L8)

### JobStore

**Signature**

```ts
declare const JobStore: JobStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L9)

### JobStoreBoundary

**Signature**

```ts
declare const JobStoreBoundary: JobStoreBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L10)

### JobStoreCheckpoint

**Signature**

```ts
declare const JobStoreCheckpoint: {
  readonly version: 1;
  readonly commit: number;
  readonly sequence: number;
  readonly offset: number;
  readonly recordCount: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L11)

### JobStoreIndex

**Signature**

```ts
declare const JobStoreIndex: {
  readonly version: 1;
  readonly commit: number;
  readonly entries: {
    readonly [x: string]: { readonly sequence: number; readonly offset: number };
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L12)

### JobStoreOptions

**Signature**

```ts
declare const JobStoreOptions: JobStoreOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L13)

### JobStoreSnapshot

**Signature**

```ts
declare const JobStoreSnapshot: JobStoreSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L14)

### LocalEventProvider

**Signature**

```ts
declare const LocalEventProvider: LocalEventProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L32)

### ScheduleEnqueue

**Signature**

```ts
declare const ScheduleEnqueue: ScheduleEnqueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L21)

### ScheduleEnqueueContext

**Signature**

```ts
declare const ScheduleEnqueueContext: ScheduleEnqueueContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L20)

### ScheduleRun

**Signature**

```ts
declare const ScheduleRun: ScheduleRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L25)

### ScheduleValidationError

**Signature**

```ts
declare const ScheduleValidationError: typeof ScheduleValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L17)

### Scheduler

**Signature**

```ts
declare const Scheduler: Scheduler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L26)

### SchedulerClock

**Signature**

```ts
declare const SchedulerClock: SchedulerClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L23)

### SchedulerOptions

**Signature**

```ts
declare const SchedulerOptions: SchedulerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L24)

### SchedulerRegistration

**Signature**

```ts
declare const SchedulerRegistration: SchedulerRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L22)

### compileSchedule

**Signature**

```ts
declare const compileSchedule: (
  schedule: ScheduleDefinition,
  options?: { readonly currentDate?: Date },
) => CompiledSchedule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L17)

### createEphemeralDelivery

**Signature**

```ts
declare const createEphemeralDelivery: (
  invoke: (envelope: UnknownEventEnvelope) => Promise<unknown>,
  requestedCapacity?: number,
) => EphemeralDelivery;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L35)

### createEventDelivery

**Signature**

```ts
declare const createEventDelivery: (
  root: string,
  binding: EventDeliveryBinding,
  options?: EventDeliveryOptions,
) => Promise<EventDelivery>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L44)

### createJobStore

**Signature**

```ts
declare const createJobStore: (
  requestedRoot: string,
  options?: JobStoreOptions,
) => Promise<JobStore>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L5)

### createLocalEventProvider

**Signature**

```ts
declare const createLocalEventProvider: (root: string) => Promise<LocalEventProvider>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L31)

### createScheduler

**Signature**

```ts
declare const createScheduler: (options?: SchedulerOptions) => Scheduler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/index.ts#L17)

## `admin-contracts.ts`

### JOB_ADMIN_PROTOCOL

**Signature**

```ts
declare const JOB_ADMIN_PROTOCOL: "relkit.jobs.admin";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L36)

### JOB_ADMIN_VERSION

**Signature**

```ts
declare const JOB_ADMIN_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L37)

### JobActionContract

**Signature**

```ts
declare const JobActionContract: JobActionContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L32)

### JobActionRequest

**Signature**

```ts
declare const JobActionRequest: JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L27)

### JobAdminAction

**Signature**

```ts
declare const JobAdminAction: JobAdminAction;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L21)

### JobAdminActionOutcome

**Signature**

```ts
declare const JobAdminActionOutcome: JobAdminActionOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L22)

### JobAdminActionRecord

**Signature**

```ts
declare const JobAdminActionRecord: JobAdminActionRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L31)

### JobAdminActionSink

**Signature**

```ts
declare const JobAdminActionSink: JobAdminActionSink;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L33)

### JobAdminMode

**Signature**

```ts
declare const JobAdminMode: JobAdminMode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L20)

### JobAdminVersion

**Signature**

```ts
declare const JobAdminVersion: JobAdminVersion;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L23)

### JobCancelRequest

**Signature**

```ts
declare const JobCancelRequest: JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L29)

### JobDeadLetterRequest

**Signature**

```ts
declare const JobDeadLetterRequest: JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L30)

### JobQueryContract

**Signature**

```ts
declare const JobQueryContract: JobQueryContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L26)

### JobQueryRequest

**Signature**

```ts
declare const JobQueryRequest: JobQueryRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L25)

### JobRetryRequest

**Signature**

```ts
declare const JobRetryRequest: JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L28)

### JobStatusContract

**Signature**

```ts
declare const JobStatusContract: JobStatusContract;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.ts#L24)

## `admin-contracts.types.ts`

### JobActionContract (interface)

Versioned job mutation result including status and audit record.

**Signature**

```ts
export interface JobActionContract extends JobAdminVersion {
  readonly action: JobAdminAction;
  readonly status: JobStatusContract;
  readonly record: JobAdminActionRecord;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L84)

### JobActionRequest (interface)

Base job administration request with target identity and audit reason.

**Signature**

```ts
export interface JobActionRequest {
  readonly protocol?: typeof JOB_ADMIN_PROTOCOL;
  readonly version?: typeof JOB_ADMIN_VERSION;
  readonly instanceId: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L53)

### JobAdminAction (type alias)

Supported audited queue administration action.

**Signature**

```ts
type JobAdminAction = "retry" | "cancel" | "dead-letter";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L9)

### JobAdminActionOutcome (type alias)

Whether an administration action was applied or rejected.

**Signature**

```ts
type JobAdminActionOutcome = "applied" | "rejected";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L12)

### JobAdminActionRecord (interface)

Immutable audit record retained for each applied or rejected job action.

**Signature**

```ts
export interface JobAdminActionRecord extends JobAdminVersion {
  readonly actionId: string;
  readonly action: JobAdminAction;
  readonly instanceId: string;
  readonly mode: JobAdminMode;
  readonly outcome: JobAdminActionOutcome;
  readonly requestedAt: number;
  readonly fromState?: JobQueueState;
  readonly toState?: JobQueueState;
  readonly errorCode?: string;
  readonly reason?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L70)

### JobAdminActionSink (type alias)

Optional notification sink whose rejection cannot change the action outcome.

**Signature**

```ts
type JobAdminActionSink = (record: JobAdminActionRecord) => MaybePromise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L91)

### JobAdminMode (type alias)

Environment mode controlling local administration mutations.

**Signature**

```ts
type JobAdminMode = "development" | "test" | "production";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L6)

### JobAdminVersion (interface)

Protocol identity carried by job administration contracts.

**Signature**

```ts
export interface JobAdminVersion {
  readonly protocol: typeof JOB_ADMIN_PROTOCOL;
  readonly version: typeof JOB_ADMIN_VERSION;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L15)

### JobCancelRequest (type alias)

Job cancellation request with optional audit reason.

**Signature**

```ts
type JobCancelRequest = JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L64)

### JobDeadLetterRequest (type alias)

Job dead-letter request with optional audit reason.

**Signature**

```ts
type JobDeadLetterRequest = JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L67)

### JobQueryContract (interface)

Versioned bounded page of safe job status records.

**Signature**

```ts
export interface JobQueryContract extends JobAdminVersion {
  readonly items: readonly JobStatusContract[];
  readonly counts: JobQueueCounts;
  readonly nextCursor?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L46)

### JobQueryRequest (interface)

Optional identity, state and pagination filters for job inspection.

**Signature**

```ts
export interface JobQueryRequest {
  readonly protocol?: typeof JOB_ADMIN_PROTOCOL;
  readonly version?: typeof JOB_ADMIN_VERSION;
  readonly instanceId?: string;
  readonly state?: JobQueueState;
  readonly states?: readonly JobQueueState[];
  readonly cursor?: string;
  readonly limit?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L35)

### JobRetryRequest (type alias)

Job retry request with optional policy override.

**Signature**

```ts
type JobRetryRequest = JobActionRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L61)

### JobStatusContract (interface)

Safe, versioned state returned to inspector consumers.

**Signature**

```ts
export interface JobStatusContract extends JobAdminVersion {
  readonly instanceId: string;
  readonly state: JobQueueState;
  readonly profile: string;
  readonly attempt: number;
  readonly acceptedAt: number;
  readonly order: number;
  readonly availableAt?: number;
  readonly leaseExpiresAt?: number;
  readonly idempotencyExpiresAt?: number;
  readonly failure?: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-contracts.types.ts#L21)

## `admin-errors.ts`

Preserves the public job admin error identity and stable error code.

### JobAdminError (class)

Preserves the public job admin error identity and stable error code.

**Signature**

```ts
declare class JobAdminError { constructor(
    readonly code: string,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin-errors.ts#L2)

## `admin.ts`

### "./admin-contracts.js" (namespace export)

Re-exports all named exports from the "./admin-contracts.js" module.

**Signature**

```ts
export * from "./admin-contracts.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.ts#L40)

### JobAdmin

**Signature**

```ts
declare const JobAdmin: JobAdmin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.ts#L38)

### JobAdminError

**Signature**

```ts
declare const JobAdminError: typeof JobAdminError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.ts#L41)

### JobAdminOptions

**Signature**

```ts
declare const JobAdminOptions: JobAdminOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.ts#L38)

### createJobAdmin

Exposes versioned local job inspection and explicitly audited mutations.

**Signature**

```ts
declare const createJobAdmin: (queue: JobQueue, options?: JobAdminOptions) => JobAdmin;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.ts#L48)

## `admin.types.ts`

### JobAdmin (interface)

Versioned job inspection and audited development mutation interface.

**Signature**

```ts
export interface JobAdmin {
  readonly protocol: typeof JOB_ADMIN_PROTOCOL;
  readonly version: typeof JOB_ADMIN_VERSION;
  readonly status: (instanceId: string) => JobStatusContract | undefined;
  readonly query: (request?: JobQueryRequest) => JobQueryContract;
  readonly retry: (request: string | JobActionRequest) => Promise<JobActionContract>;
  readonly cancel: (request: string | JobActionRequest) => Promise<JobActionContract>;
  readonly deadLetter: (request: string | JobActionRequest) => Promise<JobActionContract>;
  readonly actions: () => readonly JobAdminActionRecord[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.types.ts#L25)

### JobAdminOptions (interface)

Local administration mode and isolated audit/clock hooks.

**Signature**

```ts
export interface JobAdminOptions {
  readonly mode?: JobAdminMode;
  readonly environment?: JobAdminMode;
  readonly enabled?: boolean;
  readonly now?: () => number;
  readonly createActionId?: () => string;
  readonly onAction?: JobAdminActionSink;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/admin.types.ts#L15)

## `queue-utils.ts`

### JOB_QUEUE_STATES

**Signature**

```ts
declare const JOB_QUEUE_STATES: readonly [
  "accepted",
  "available",
  "leased",
  "delayed",
  "completed",
  "dead-lettered",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L42)

### JobFailureKind

**Signature**

```ts
declare const JobFailureKind: JobFailureKind;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L29)

### JobFailureMetadata

**Signature**

```ts
declare const JobFailureMetadata: JobFailureMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L32)

### JobFailureOutcome

**Signature**

```ts
declare const JobFailureOutcome: JobFailureOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L30)

### JobFailureRetry

**Signature**

```ts
declare const JobFailureRetry: JobFailureRetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L31)

### JobIdempotencyDefinition

**Signature**

```ts
declare const JobIdempotencyDefinition: JobIdempotencyDefinition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L24)

### JobIdempotencyRecord

**Signature**

```ts
declare const JobIdempotencyRecord: JobIdempotencyRecord;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L25)

### JobQueue

**Signature**

```ts
declare const JobQueue: JobQueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L39)

### JobQueueAcceptance

**Signature**

```ts
declare const JobQueueAcceptance: JobQueueAcceptance;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L28)

### JobQueueAdminRetryOptions

**Signature**

```ts
declare const JobQueueAdminRetryOptions: JobQueueAdminRetryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L36)

### JobQueueCounts

**Signature**

```ts
declare const JobQueueCounts: Readonly<
  Record<"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered", number>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L37)

### JobQueueEnqueue

**Signature**

```ts
declare const JobQueueEnqueue: JobQueueEnqueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L33)

### JobQueueEntry

**Signature**

```ts
declare const JobQueueEntry: JobQueueEntry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L26)

### JobQueueLeaseOptions

**Signature**

```ts
declare const JobQueueLeaseOptions: JobQueueLeaseOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L34)

### JobQueueOptions

**Signature**

```ts
declare const JobQueueOptions: JobQueueOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L38)

### JobQueueState

**Signature**

```ts
declare const JobQueueState:
  "accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L22)

### JobQueueStateError (class)

Preserves the public job queue state error identity and stable error code.

**Signature**

```ts
declare class JobQueueStateError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L52)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_QUEUE_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L53)

### JobQueueTransitionOptions

**Signature**

```ts
declare const JobQueueTransitionOptions: JobQueueTransitionOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L35)

### JobState

**Signature**

```ts
declare const JobState:
  "accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L23)

### MutableQueueState

**Signature**

```ts
declare const MutableQueueState: MutableQueueState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L27)

### assertTime

Rejects times outside the nonnegative safe millisecond range.

**Signature**

```ts
declare const assertTime: (value: number, label: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L75)

### transitions

**Signature**

```ts
declare const transitions: Readonly<
  Record<
    "accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered",
    ReadonlyArray<"accepted" | "completed" | "available" | "leased" | "delayed" | "dead-lettered">
  >
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.ts#L61)

## `queue-utils.types.ts`

### JobFailureKind (type alias)

Public classification of a failed queue attempt.

**Signature**

```ts
type JobFailureKind = "application" | "provider" | "cancellation" | "timeout" | "defect";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L54)

### JobFailureMetadata (interface)

Public, JSON-safe failure data retained with a delayed or dead-lettered job.

**Signature**

```ts
export interface JobFailureMetadata {
  readonly kind: JobFailureKind;
  readonly outcome: JobFailureOutcome;
  readonly code: string;
  readonly message: string;
  readonly data?: JsonValue;
  readonly status?: number;
  readonly retry?: JobFailureRetry;
  readonly afterMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L64)

### JobFailureOutcome (type alias)

Public terminal or retry outcome of a failed queue attempt.

**Signature**

```ts
type JobFailureOutcome = "declared-error" | "provider-failure" | "cancelled" | "timeout" | "defect";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L57)

### JobFailureRetry (type alias)

Retry hint retained in safe failure metadata.

**Signature**

```ts
type JobFailureRetry = "never" | "later";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L61)

### JobIdempotencyDefinition (interface)

Caller deduplication identity and retention policy for a queue acceptance.

**Signature**

```ts
export interface JobIdempotencyDefinition {
  readonly key: string;
  readonly retentionMs: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L11)

### JobIdempotencyRecord (interface)

Persisted acceptance identity and expiry used for deduplication.

**Signature**

```ts
export interface JobIdempotencyRecord {
  readonly key: string;
  readonly expiresAt: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L17)

### JobQueue (interface)

Promise mutation and synchronous inspection contract for one durable queue.

**Signature**

```ts
export interface JobQueue {
  readonly ownerToken: string;
  readonly ready: () => Promise<void>;
  readonly enqueue: (input: JobQueueEnqueue) => Promise<JobQueueAcceptance>;
  readonly acquire: (
    instanceId?: string,
    options?: JobQueueLeaseOptions,
  ) => Promise<JobQueueEntry | undefined>;
  readonly renew: (instanceId: string, options?: JobQueueLeaseOptions) => Promise<JobQueueEntry>;
  readonly transition: (
    instanceId: string,
    state: JobQueueState,
    options?: JobQueueTransitionOptions,
  ) => Promise<JobQueueEntry>;
  /** Requeues one dead letter as a fresh attempt without widening normal transitions. */
  readonly adminRetry: (
    instanceId: string,
    options?: JobQueueAdminRetryOptions,
  ) => Promise<JobQueueEntry>;
  /** Moves one eligible nonterminal entry to a dead letter with safe metadata. */
  readonly adminDeadLetter: (
    instanceId: string,
    failure: JobFailureMetadata,
  ) => Promise<JobQueueEntry>;
  readonly recover: (now?: number) => Promise<readonly JobQueueEntry[]>;
  readonly expire: (now?: number) => Promise<readonly JobQueueEntry[]>;
  readonly selectAvailable: (limit?: number, now?: number) => readonly JobQueueEntry[];
  readonly get: (instanceId: string) => JobQueueEntry | undefined;
  readonly counts: () => JobQueueCounts;
  readonly snapshot: () => readonly JobQueueEntry[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L118)

### JobQueueAcceptance (interface)

Durable acceptance information returned by queue admission.

**Signature**

```ts
export interface JobQueueAcceptance extends JobQueueEntry {
  readonly accepted: true;
  readonly duplicate: boolean;
  readonly idempotencyKey?: string;
  readonly idempotencyExpiresAt?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L46)

### JobQueueAdminRetryOptions (interface)

Administrative retry preconditions and next-availability settings.

**Signature**

```ts
export interface JobQueueAdminRetryOptions {
  readonly availableAt?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L101)

### JobQueueCounts (type alias)

Entry counts grouped by durable queue lifecycle state.

**Signature**

```ts
type JobQueueCounts = Readonly<Record<JobQueueState, number>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L106)

### JobQueueEnqueue (interface)

Input required to accept a job into the local durable queue.

**Signature**

```ts
export interface JobQueueEnqueue {
  readonly input: JsonValue;
  readonly profile?: string;
  readonly instanceId?: string;
  readonly acceptedAt?: number;
  readonly idempotency?: JobIdempotencyDefinition;
  readonly propagation?: TracePropagation;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L76)

### JobQueueEntry (interface)

Durable queue state including acceptance, lease, retry and failure metadata.

**Signature**

```ts
export interface JobQueueEntry {
  readonly instanceId: string;
  readonly state: JobQueueState;
  readonly input: JsonValue;
  readonly profile: string;
  readonly attempt: number;
  readonly acceptedAt: number;
  readonly order: number;
  readonly availableAt?: number;
  readonly leaseOwner?: string;
  readonly leaseExpiresAt?: number;
  readonly idempotency?: JobIdempotencyRecord;
  readonly failure?: JobFailureMetadata;
  readonly propagation?: TracePropagation;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L23)

### JobQueueLeaseOptions (interface)

Caller ownership and duration settings for acquiring a lease.

**Signature**

```ts
export interface JobQueueLeaseOptions {
  readonly leaseDurationMs?: number;
  readonly leaseExpiresAt?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L86)

### JobQueueOptions (interface)

Clock, persistence and policy options for a local queue.

**Signature**

```ts
export interface JobQueueOptions {
  readonly now?: () => number;
  readonly createInstanceId?: () => string;
  readonly ownerToken?: string;
  readonly leaseDurationMs?: number;
  readonly idempotency?: JobIdempotencyDefinition;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L109)

### JobQueueState (type alias)

Persisted lifecycle states supported by the local durable queue.

**Signature**

```ts
type JobQueueState = (typeof JOB_QUEUE_STATES)[number];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L5)

### JobQueueTransitionOptions (interface)

Expected state, ownership and metadata for a durable transition.

**Signature**

```ts
export interface JobQueueTransitionOptions extends JobQueueLeaseOptions {
  readonly expectedState?: JobQueueState;
  readonly attempt?: number;
  readonly availableAt?: number;
  readonly leaseOwner?: string;
  readonly failure?: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L92)

### JobState (type alias)

Compatibility alias for the durable queue lifecycle state.

**Signature**

```ts
type JobState = JobQueueState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L8)

### MutableQueueState (interface)

In-memory queue index and next acceptance order owned by serialized mutations.

**Signature**

```ts
export interface MutableQueueState {
  readonly entries: Map<string, JobQueueEntry>;
  nextOrder: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue-utils.types.ts#L40)

## `queue.ts`

### "./queue-utils.js" (namespace export)

Re-exports all named exports from the "./queue-utils.js" module.

**Signature**

```ts
export * from "./queue-utils.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue.ts#L29)

### JOB_QUEUE_STATES

**Signature**

```ts
declare const JOB_QUEUE_STATES: readonly [
  "accepted",
  "available",
  "leased",
  "delayed",
  "completed",
  "dead-lettered",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue.ts#L28)

### JobQueueStateError

**Signature**

```ts
declare const JobQueueStateError: typeof JobQueueStateError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue.ts#L28)

### createJobQueue

Provides durable queue state plus process-owned leases.

**Signature**

```ts
declare const createJobQueue: (store: JobStore, options?: JobQueueOptions) => JobQueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/queue.ts#L36)

## `retry.ts`

### RandomSource

**Signature**

```ts
declare const RandomSource: RandomSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L23)

### RetryClassification

**Signature**

```ts
declare const RetryClassification: RetryClassification;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L21)

### RetryOptions

**Signature**

```ts
declare const RetryOptions: RetryOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L25)

### RetryPlan

**Signature**

```ts
declare const RetryPlan: RetryPlan;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L24)

### RetryState

**Signature**

```ts
declare const RetryState: RetryState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L22)

### applyRetry

Applies one leased attempt's retry/dead-letter outcome durably.

**Signature**

```ts
declare const applyRetry: (
  queue: Pick<JobQueue, "get" | "transition">,
  instanceId: string,
  policy: RetryPolicy,
  failure: unknown,
  options?: RetryOptions,
) => Promise<JobQueueEntry>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L101)

### calculateRetryDelay

Calculates a bounded, integer delay for a one-based completed attempt.

**Signature**

```ts
declare const calculateRetryDelay: (
  policy: RetryPolicy,
  attempt: number,
  random?: RandomSource,
) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L45)

### classifyFailure

Uses the declared error policy; non-declared failures are not retried.

**Signature**

```ts
declare const classifyFailure: (value: unknown) => RetryClassification;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L32)

### planRetry

Combines normalized failure classification, attempt limits and retry jitter into a retry plan.

**Signature**

```ts
declare const planRetry: (
  policy: RetryPolicy,
  attempt: number,
  failure: unknown,
  options?: Pick<RetryOptions, "random">,
) => RetryPlan;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L72)

### safeFailureMetadata

Copies the public failure envelope so persisted metadata cannot retain arbitrary error objects.

**Signature**

```ts
declare const safeFailureMetadata: (value: unknown) => JobFailureMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.ts#L126)

## `retry.types.ts`

### RandomSource (type alias)

Replaceable source of values in [0, 1) for deterministic jitter.

**Signature**

```ts
type RandomSource = () => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.types.ts#L10)

### RetryClassification (type alias)

Whether the normalized failure permits another attempt.

**Signature**

```ts
type RetryClassification = "retryable" | "non-retryable";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.types.ts#L4)

### RetryOptions (interface)

Clock, jitter and transition options for applying retry policy.

**Signature**

```ts
export interface RetryOptions {
  readonly now?: () => number;
  readonly random?: RandomSource;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.types.ts#L22)

### RetryPlan (interface)

Validated retry classification, delay and safe failure metadata.

**Signature**

```ts
export interface RetryPlan {
  readonly classification: RetryClassification;
  readonly state: RetryState;
  readonly attempt: number;
  readonly delayMs: number;
  readonly failure: JobFailureMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.types.ts#L13)

### RetryState (type alias)

Durable queue outcome selected by retry policy.

**Signature**

```ts
type RetryState = "delayed" | "dead-lettered";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/retry.types.ts#L7)

## `schedule-definition.ts`

### ScheduleValidationError (class)

Preserves the public schedule validation error identity and stable error code.

**Signature**

```ts
declare class ScheduleValidationError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L7)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_SCHEDULE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L8)

### compileSchedule

Validates a static schedule and hides the cron parser behind native dates.

**Signature**

```ts
declare const compileSchedule: (
  schedule: ScheduleDefinition,
  options?: { readonly currentDate?: Date },
) => CompiledSchedule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L21)

### isRecord

Checks for a non-null, non-array object before inspecting unknown fields.

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L94)

### parseNext

Computes the next cron occurrence within the configured timezone.

**Signature**

```ts
declare const parseNext: (cron: string, timezone: string, currentDate: Date) => Date;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L59)

### requiredText

Rejects missing or blank schedule identifiers.

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L74)

### validDate

Rejects invalid clock dates before scheduling work.

**Signature**

```ts
declare const validDate: (value: Date, name: string) => Date;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/schedule-definition.ts#L84)

## `scheduler.ts`

### CompiledSchedule

**Signature**

```ts
declare const CompiledSchedule: CompiledSchedule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L29)

### LocalSchedulerService (class)

Owns schedule registrations, next-fire positions and active overlap counters.

**Signature**

```ts
declare class LocalSchedulerService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L55)

### ScheduleEnqueue

**Signature**

```ts
declare const ScheduleEnqueue: ScheduleEnqueue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L31)

### ScheduleEnqueueContext

**Signature**

```ts
declare const ScheduleEnqueueContext: ScheduleEnqueueContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L30)

### ScheduleRun

**Signature**

```ts
declare const ScheduleRun: ScheduleRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L35)

### ScheduleValidationError

**Signature**

```ts
declare const ScheduleValidationError: typeof ScheduleValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L27)

### Scheduler

**Signature**

```ts
declare const Scheduler: Scheduler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L36)

### SchedulerClock

**Signature**

```ts
declare const SchedulerClock: SchedulerClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L33)

### SchedulerOptions

**Signature**

```ts
declare const SchedulerOptions: SchedulerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L34)

### SchedulerRegistration

**Signature**

```ts
declare const SchedulerRegistration: SchedulerRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L32)

### compileSchedule

**Signature**

```ts
declare const compileSchedule: (
  schedule: ScheduleDefinition,
  options?: { readonly currentDate?: Date },
) => CompiledSchedule;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L27)

### createScheduler

Runs due schedules against an injected clock without owning or calling handlers.

**Signature**

```ts
declare const createScheduler: (options?: SchedulerOptions) => Scheduler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L43)

### makeSchedulerService

Creates lazy registration, inspection and due-work operations over one owned state.

**Signature**

```ts
declare const makeSchedulerService: (
  options?: SchedulerOptions | undefined,
) => Effect.Effect<SchedulerEffects, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L84)

### schedulerLayer

Provides an explicitly driven scheduler without starting an automatic timer.

**Example**

```ts
import { Effect } from "effect";
import { LocalSchedulerService, schedulerLayer } from "./scheduler.js";

const program = Effect.gen(function* () {
  const scheduler = yield* LocalSchedulerService;
  return yield* scheduler.runDue();
});
await Effect.runPromise(program.pipe(Effect.provide(schedulerLayer())));
```

**Signature**

```ts
declare const schedulerLayer: (
  options?: SchedulerOptions,
) => Layer.Layer<LocalSchedulerService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.ts#L75)

## `scheduler.types.ts`

### CompiledSchedule (interface)

Validated cron schedule with its normalized timezone and identity.

**Signature**

```ts
export interface CompiledSchedule {
  readonly id: string;
  readonly cron: string;
  readonly timezone: string;
  readonly input: JsonValue;
  readonly overlap: ScheduleOverlap;
  readonly nextFireAt: Date;
  readonly nextFire: (currentDate: Date) => Date;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L14)

### ScheduleEnqueue (type alias)

The scheduler only emits work through the common job enqueue/invocation seam.

**Signature**

```ts
type ScheduleEnqueue = (input: JsonValue, context: ScheduleEnqueueContext) => MaybePromise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L31)

### ScheduleEnqueueContext (interface)

Occurrence identity and time supplied when enqueueing scheduled work.

**Signature**

```ts
export interface ScheduleEnqueueContext {
  readonly scheduleId: string;
  readonly fireAt: Date;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L25)

### ScheduleRun (interface)

Result of processing one due schedule occurrence.

**Signature**

```ts
export interface ScheduleRun {
  readonly scheduleId: string;
  readonly fireAt: Date;
  readonly status: "enqueued" | "skipped";
  readonly result?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L55)

### ScheduleState (interface)

Registered schedule and its current next-fire/overlap bookkeeping.

**Signature**

```ts
export interface ScheduleState {
  readonly compiled: CompiledSchedule;
  readonly enqueue: ScheduleEnqueue;
  nextFireAt: number;
  active: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L63)

### Scheduler (interface)

Explicitly driven scheduler with registration, due-work execution and inspection.

**Signature**

```ts
export interface Scheduler {
  readonly register: (schedule: ScheduleDefinition, enqueue: ScheduleEnqueue) => CompiledSchedule;
  readonly nextFire: (scheduleId: string) => Date | undefined;
  readonly runDue: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
  readonly tick: (currentDate?: Date | number) => Promise<readonly ScheduleRun[]>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L71)

### SchedulerClock (interface)

Replaceable clock used by scheduler calculations.

**Signature**

```ts
export interface SchedulerClock {
  readonly now: () => Date | number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L43)

### SchedulerEffects (type alias)

Lazy scheduler operations shared by live composition and deterministic test substitutes.

**Signature**

```ts
type SchedulerEffects = {
  readonly [K in keyof Scheduler]: Scheduler[K] extends (...args: infer A) => infer R
    ? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
    : never;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L7)

### SchedulerOptions (interface)

Clock and scheduling behavior supplied by the local scheduler owner.

**Signature**

```ts
export interface SchedulerOptions {
  readonly clock?: SchedulerClock;
  readonly now?: () => Date | number;
  readonly schedules?: readonly SchedulerRegistration[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L48)

### SchedulerRegistration (interface)

Schedule declaration paired with its enqueue callback.

**Signature**

```ts
export interface SchedulerRegistration {
  readonly schedule: ScheduleDefinition;
  readonly enqueue: ScheduleEnqueue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/scheduler.types.ts#L37)

## `store.ts`

### JobIndexEntry

**Signature**

```ts
declare const JobIndexEntry: { readonly sequence: number; readonly offset: number };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L40)

### JobRecord

**Signature**

```ts
declare const JobRecord: {
  readonly version: 1;
  readonly sequence: number;
  readonly instanceId: string;
  readonly kind: string;
  readonly timestamp: number;
  readonly data: Json;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L39)

### JobRecordInput

**Signature**

```ts
declare const JobRecordInput: JobRecordInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L38)

### JobStore

**Signature**

```ts
declare const JobStore: JobStore;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L44)

### JobStoreBoundary

**Signature**

```ts
declare const JobStoreBoundary: JobStoreBoundary;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L36)

### JobStoreCheckpoint

**Signature**

```ts
declare const JobStoreCheckpoint: {
  readonly version: 1;
  readonly commit: number;
  readonly sequence: number;
  readonly offset: number;
  readonly recordCount: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L42)

### JobStoreEffects

**Signature**

```ts
declare const JobStoreEffects: JobStoreEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L45)

### JobStoreIndex

**Signature**

```ts
declare const JobStoreIndex: {
  readonly version: 1;
  readonly commit: number;
  readonly entries: {
    readonly [x: string]: { readonly sequence: number; readonly offset: number };
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L41)

### JobStoreOptions

**Signature**

```ts
declare const JobStoreOptions: JobStoreOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L37)

### JobStoreSnapshot

**Signature**

```ts
declare const JobStoreSnapshot: JobStoreSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L43)

### JobStoreStateError (class)

Preserves the public job store state error identity and stable error code.

**Signature**

```ts
declare class JobStoreStateError {
  constructor(message: string);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L51)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_JOB_STORE_STATE_INVALID"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L52)

### LocalJobStoreService (class)

A durable journal whose serialization and lifecycle have one owner.

**Signature**

```ts
declare class LocalJobStoreService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L61)

### STORE_VERSION

**Signature**

```ts
declare const STORE_VERSION: 1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L48)

### createJobStore

Opens the journal through the established Promise interface.

**Signature**

```ts
declare const createJobStore: (
  requestedRoot: string,
  options?: JobStoreOptions,
) => Promise<JobStore>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L71)

### jobStoreLayer

Supplies and closes a durable journal through a scope-owned layer.

**Example**

```ts
import { Effect } from "effect";
import { LocalJobStoreService, jobStoreLayer } from "./store.js";

const program = Effect.gen(function* () {
  const journal = yield* LocalJobStoreService;
  return yield* journal.snapshot();
});
await Effect.runPromise(program.pipe(Effect.provide(jobStoreLayer("/tmp/example-journal"))));
```

**Signature**

```ts
declare const jobStoreLayer: (
  root: string,
  options?: JobStoreOptions,
) => Layer.Layer<LocalJobStoreService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L102)

### makeJobStore

Recovers a journal before exposing serialized append operations.

**Signature**

```ts
declare const makeJobStore: (
  requestedRoot: string,
  options?: JobStoreOptions | undefined,
) => Effect.Effect<JobStoreEffects, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.ts#L116)

## `store.types.ts`

### JobIndexEntry (type alias)

Latest record sequence and byte offset for one job instance.

**Signature**

```ts
type JobIndexEntry = typeof JobIndexEntrySchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L36)

### JobRecord (type alias)

Versioned durable journal record with ordered sequence and timestamp.

**Signature**

```ts
type JobRecord = typeof JobRecordSchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L33)

### JobRecordInput (interface)

Canonical JSON record input before sequence and timestamp assignment.

**Signature**

```ts
export interface JobRecordInput {
  readonly instanceId: string;
  readonly kind: string;
  readonly data: JsonValue;
  readonly timestamp?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L25)

### JobStore (interface)

Compatibility journal interface with durable append and explicit close.

**Signature**

```ts
export interface JobStore {
  readonly root: string;
  readonly paths: Readonly<ReturnType<typeof createJobStorePaths>>;
  readonly append: (input: JobRecordInput) => Promise<JobRecord>;
  readonly snapshot: () => JobStoreSnapshot;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L52)

### JobStoreBoundary (type alias)

Durable commit milestones available to fault-injection and observation hooks.

**Signature**

```ts
type JobStoreBoundary = "record-fsynced" | "index-committed" | "checkpoint-committed";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L13)

### JobStoreCheckpoint (type alias)

Committed sequence, record count and byte offset used for recovery.

**Signature**

```ts
type JobStoreCheckpoint = typeof JobCheckpointSchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L42)

### JobStoreEffects (interface)

Effect operations for a durable journal and its committed snapshot.

**Signature**

```ts
export interface JobStoreEffects {
  readonly root: string;
  readonly paths: JobStore["paths"];
  readonly append: (input: JobRecordInput) => Effect.Effect<JobRecord, LocalOperationError>;
  readonly snapshot: () => Effect.Effect<JobStoreSnapshot>;
  readonly close: () => Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L61)

### JobStoreIndex (type alias)

Versioned index rebuilt from the durable journal.

**Signature**

```ts
type JobStoreIndex = typeof JobIndexSchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L39)

### JobStoreOptions (interface)

Clock, record validation and durable-boundary hooks for journal ownership.

**Signature**

```ts
export interface JobStoreOptions {
  readonly now?: () => number;
  /** Test-only failure seam; an error rejects append before acknowledgement. */
  readonly onBoundary?: (boundary: JobStoreBoundary) => void | Promise<void>;
  /** Optional semantic guard used by durable stores layered on this record format. */
  readonly validateData?: (data: JsonValue) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L16)

### JobStoreSnapshot (interface)

Immutable recovered records, index and checkpoint.

**Signature**

```ts
export interface JobStoreSnapshot {
  readonly records: readonly JobRecord[];
  readonly index: JobStoreIndex;
  readonly checkpoint: JobStoreCheckpoint;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/jobs/store.types.ts#L45)

## `common.ts`

### LocalRealtimeError (class)

Preserves the public local realtime error identity and stable error code.

**Signature**

```ts
declare class LocalRealtimeError { constructor(
    readonly code: string,
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L6)

### checkpoint

Builds the current journal checkpoint from the persisted sequence.

**Signature**

```ts
declare const checkpoint: (
  scope: RealtimeScope,
  state: LocalRealtimeState,
  sequence: number,
  historyStart: number,
  expiresAt: string,
) => ChannelCheckpoint;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L78)

### emptyPartition

Creates an empty retained event and presence partition.

**Signature**

```ts
declare const emptyPartition: (sequence: number) => StoredRealtimePartition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L37)

### encodedBytes

Measures canonical JSON bytes for admission limits.

**Signature**

```ts
declare const encodedBytes: (value: unknown) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L46)

### partitionKey

Encodes the channel and scope into a stable realtime partition key.

**Signature**

```ts
declare const partitionKey: (scope: RealtimeScope) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L21)

### prunePartition

Removes expired events and enforces retention bounds without renumbering sequences.

**Signature**

```ts
declare const prunePartition: (
  partition: StoredRealtimePartition,
  now: number,
) => StoredRealtimePartition;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L56)

### scopeGap

Constructs a replay gap describing the requested checkpoint and current scope.

**Signature**

```ts
declare const scopeGap: (
  expected: RealtimeScope,
  actual: ChannelCheckpoint,
  providerEpoch: string,
) => "foreign" | "policy" | "session" | "provider-reset" | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/common.ts#L101)

## `provider.ts`

### LocalRealtimeProviderOptions

**Signature**

```ts
declare const LocalRealtimeProviderOptions: LocalRealtimeProviderOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L18)

### LocalRealtimeService (class)

Realtime operations sharing one persisted-state transaction owner.

**Signature**

```ts
declare class LocalRealtimeService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L21)

### createLocalRealtimeProvider

Provides realtime operations using filesystem-shared state.

**Signature**

```ts
declare const createLocalRealtimeProvider: (
  root: string,
  options?: LocalRealtimeProviderOptions,
) => RealtimeProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L31)

### createRealtimeProviderFromStore

Substitutes an existing Promise storage adapter at the compatibility edge.

**Signature**

```ts
declare const createRealtimeProviderFromStore: (
  store: RealtimeStateStore,
  pollingMs?: number,
) => RealtimeProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L46)

### makeRealtimeService

Composes realtime behavior over an Effect transaction interface.

**Signature**

```ts
declare const makeRealtimeService: (
  store: RealtimeStateStoreEffects,
  pollingMs?: number,
) => RealtimeEffects;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L91)

### realtimeLayer

Builds one live realtime service through a substitutable layer.

**Example**

```ts
import { Effect } from "effect";
import { LocalRealtimeService, realtimeLayer } from "./provider.js";

const program = Effect.gen(function* () {
  const realtime = yield* LocalRealtimeService;
  return yield* realtime.getEpoch();
});
await Effect.runPromise(program.pipe(Effect.provide(realtimeLayer("/tmp/example-realtime"))));
```

**Signature**

```ts
declare const realtimeLayer: (
  root: string,
  pollingMs?: number,
) => Layer.Layer<LocalRealtimeService, LocalOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.ts#L78)

## `provider.types.ts`

### LocalRealtimeProviderOptions (interface)

Polling configuration for filesystem-shared realtime observations.

**Signature**

```ts
export interface LocalRealtimeProviderOptions {
  readonly pollingMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.types.ts#L6)

### RealtimeEffects (type alias)

Effect methods corresponding to the established realtime provider surface.

**Signature**

```ts
type RealtimeEffects = {
  readonly [K in Exclude<keyof RealtimeProvider, "capabilities">]: RealtimeProvider[K] extends (
    ...args: infer A
  ) => infer R
    ? (...args: A) => Effect.Effect<Awaited<R>, LocalOperationError>
    : never;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/provider.types.ts#L11)

## `state.ts`

### LOCAL_REALTIME_STATE_VERSION

**Signature**

```ts
declare const LOCAL_REALTIME_STATE_VERSION: 2;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L16)

### LocalRealtimeState

**Signature**

```ts
declare const LocalRealtimeState: {
  readonly version: 2;
  readonly providerEpoch: string;
  readonly sequence: number;
  readonly revision: number;
  readonly retainedBytes: number;
  readonly partitions: {
    readonly [x: string]: {
      readonly historyStart: number;
      readonly events: ReadonlyArray<{
        readonly sequence: number;
        readonly eventId: string;
        readonly event: string;
        readonly payload: unknown;
        readonly encodedBytes: number;
        readonly createdAt: string;
        readonly expiresAt: string;
      }>;
      readonly presence: ReadonlyArray<{
        readonly expiresAt: string;
        readonly leaseId: string;
        readonly connectionId: string;
        readonly opaqueMemberId?: string;
        readonly memberInfo?: unknown;
      }>;
    };
  };
  readonly receipts: {
    readonly [x: string]: {
      readonly semanticDigest: string;
      readonly expiresAt: string;
      readonly receipt: {
        readonly accepted: true;
        readonly profile: string;
        readonly providerEpoch: string;
        readonly checkpoint: {
          readonly applicationId: string;
          readonly environment: string;
          readonly profile: string;
          readonly providerEpoch: string;
          readonly sequence: string;
          readonly expiresAt: string;
          readonly historyStart: string;
          readonly channelId: string;
          readonly partition: string;
          readonly policyEpoch: string;
          readonly identityScope: string;
          readonly sessionEpoch: string;
          readonly tenantScope?: string;
        };
        readonly duplicate: boolean;
        readonly eventId: string;
        readonly operationId?: OperationId;
      };
    };
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L13)

### StoredAppendReceipt

**Signature**

```ts
declare const StoredAppendReceipt: {
  readonly semanticDigest: string;
  readonly expiresAt: string;
  readonly receipt: {
    readonly accepted: true;
    readonly profile: string;
    readonly providerEpoch: string;
    readonly checkpoint: {
      readonly applicationId: string;
      readonly environment: string;
      readonly profile: string;
      readonly providerEpoch: string;
      readonly sequence: string;
      readonly expiresAt: string;
      readonly historyStart: string;
      readonly channelId: string;
      readonly partition: string;
      readonly policyEpoch: string;
      readonly identityScope: string;
      readonly sessionEpoch: string;
      readonly tenantScope?: string;
    };
    readonly duplicate: boolean;
    readonly eventId: string;
    readonly operationId?: OperationId;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L12)

### StoredPresenceLease

**Signature**

```ts
declare const StoredPresenceLease: {
  readonly expiresAt: string;
  readonly leaseId: string;
  readonly connectionId: string;
  readonly opaqueMemberId?: string;
  readonly memberInfo?: unknown;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L10)

### StoredRealtimeEvent

**Signature**

```ts
declare const StoredRealtimeEvent: {
  readonly sequence: number;
  readonly eventId: string;
  readonly event: string;
  readonly payload: unknown;
  readonly encodedBytes: number;
  readonly createdAt: string;
  readonly expiresAt: string;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L9)

### StoredRealtimePartition

**Signature**

```ts
declare const StoredRealtimePartition: {
  readonly historyStart: number;
  readonly events: ReadonlyArray<{
    readonly sequence: number;
    readonly eventId: string;
    readonly event: string;
    readonly payload: unknown;
    readonly encodedBytes: number;
    readonly createdAt: string;
    readonly expiresAt: string;
  }>;
  readonly presence: ReadonlyArray<{
    readonly expiresAt: string;
    readonly leaseId: string;
    readonly connectionId: string;
    readonly opaqueMemberId?: string;
    readonly memberInfo?: unknown;
  }>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L11)

### emptyRealtimeState

Creates format-v1 realtime state with an epoch and empty partition/receipt indexes.

**Signature**

```ts
declare const emptyRealtimeState: (epoch?: string) => LocalRealtimeState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.ts#L23)

## `state.types.ts`

### LocalRealtimeState (type alias)

Complete validated version-two realtime snapshot.

**Signature**

```ts
type LocalRealtimeState = typeof RealtimeState.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.types.ts#L10)

### StoredAppendReceipt (type alias)

Idempotent append acknowledgement with semantic digest and expiry.

**Signature**

```ts
type StoredAppendReceipt = typeof AppendReceipt.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.types.ts#L22)

### StoredPresenceLease (type alias)

Connection lease decoded before expiry and capacity decisions.

**Signature**

```ts
type StoredPresenceLease = typeof PresenceLease.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.types.ts#L16)

### StoredRealtimeEvent (type alias)

Stored ordered event whose application payload remains opaque.

**Signature**

```ts
type StoredRealtimeEvent = typeof RealtimeEvent.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.types.ts#L13)

### StoredRealtimePartition (type alias)

Atomic partition history and presence representation.

**Signature**

```ts
type StoredRealtimePartition = typeof RealtimePartition.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/state.types.ts#L19)

## `storage.types.ts`

### RealtimeStateStore (interface)

Existing Promise transaction seam for third-party storage adapters.

**Signature**

```ts
export interface RealtimeStateStore {
  readonly read: () => Promise<LocalRealtimeState>;
  readonly update: <Value>(
    change: (state: LocalRealtimeState) => {
      readonly state: LocalRealtimeState;
      readonly value: Value;
    },
  ) => Promise<Value>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/storage.types.ts#L6)

### RealtimeStateStoreEffects (interface)

Effect operations sharing one transactional initialization and lock owner.

**Signature**

```ts
export interface RealtimeStateStoreEffects {
  readonly read: () => Effect.Effect<LocalRealtimeState, LocalOperationError>;
  readonly update: <Value>(
    change: (state: LocalRealtimeState) => {
      readonly state: LocalRealtimeState;
      readonly value: Value;
    },
  ) => Effect.Effect<Value, LocalOperationError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/realtime/storage.types.ts#L17)

## `runtime-capabilities.ts`

### LocalJobProvider

**Signature**

```ts
declare const LocalJobProvider: LocalJobProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/runtime-capabilities.ts#L8)

### createLocalJobProvider

Creates a profile-owned durable queue provider through its established synchronous constructor.

**Signature**

```ts
declare const createLocalJobProvider: {
  (root: string, profile: string): LocalJobProvider;
  (root: string, profile: string, executionModel: "task"): JobsAdapterRuntime;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/runtime-capabilities.ts#L34)

### createLocalObservabilityProvider

Creates an isolated synchronous JSON collector without recursively observing sink writes.

**Signature**

```ts
declare const createLocalObservabilityProvider: () => Readonly<{
  collect: (record: JsonValue) => void;
  emit: (record: JsonValue) => void;
  read: () => readonly JsonValue[];
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/runtime-capabilities.ts#L51)

## `runtime-capabilities.types.ts`

### LocalJobProvider (interface)

Public local native-job adapter with worker and lifecycle capabilities.

**Signature**

```ts
export interface LocalJobProvider {
  readonly createQueue: (context: {
    readonly jobId: string;
    readonly idempotency?: JobIdempotencyDefinition;
  }) => Promise<JobQueue>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/providers-local/src/runtime-capabilities.types.ts#L5)

---

# All public APIs
Source: https://relkit.dev/docs/api/public

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

Find a package below, then use its **All exported APIs** table to jump to any value or type.

The export-map audit covers **38 supported packages**, **104 import paths**, and **2663 distinct declarations**. Aliases point to the same declaration.

| Reference                                                            | Supported imports                                                                                                                                                                                                                                                                                                                         | Start here                                                          |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Application](/docs/api/app#public-imports)                          | `@relkit/app`, `@relkit/app/schema`, `@relkit/app/config`, `@relkit/app/routes`, `@relkit/app/functions`, `@relkit/app/events`, `@relkit/app/realtime`, `@relkit/app/agents`, `@relkit/app/jobs`, `@relkit/app/jobs/legacy`, `@relkit/app/tasks`, `@relkit/app/cache`, `@relkit/app/tools`, `@relkit/app/buckets`, `@relkit/app/services` | [Usage and examples](/docs/learn/concepts/application)              |
| [Configuration](/docs/api/config#public-imports)                     | `@relkit/config`                                                                                                                                                                                                                                                                                                                          | [Usage and examples](/docs/learn/concepts/environment)              |
| [Provider authoring](/docs/api/provider#public-imports)              | `@relkit/provider`                                                                                                                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/integrations/provider-authoring) |
| [Local providers](/docs/api/providers-local#public-imports)          | `@relkit/providers-local`                                                                                                                                                                                                                                                                                                                 | [Usage and examples](/docs/modules/integrations/local-providers)    |
| [Local history](/docs/api/observability-local#public-imports)        | `@relkit/observability-local`, `@relkit/observability-local/worker`                                                                                                                                                                                                                                                                       | [Usage and examples](/docs/modules/operations/inspector)            |
| [CLI automation](/docs/api/cli-api#public-imports)                   | `@relkit/cli`, `@relkit/cli/help`, `@relkit/cli/editor`, `@relkit/cli/scaffolding`                                                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/cli/automation)                  |
| [Project generator](/docs/api/create-relkit#public-imports)          | `create-relkit`, `create-relkit/cli`, `create-relkit/launcher`, `create-relkit/catalog-resolution`                                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/cli/automation)                  |
| [CLI launcher](/docs/api/relkit#public-imports)                      | `relkit`                                                                                                                                                                                                                                                                                                                                  | [Usage and examples](/docs/modules/cli/automation)                  |
| [Schema](/docs/api/schema#public-imports)                            | `@relkit/schema`                                                                                                                                                                                                                                                                                                                          | [Usage and examples](/docs/learn/concepts/schemas)                  |
| [Functions](/docs/api/functions#public-imports)                      | `@relkit/functions`                                                                                                                                                                                                                                                                                                                       | [Usage and examples](/docs/learn/concepts/functions)                |
| [Services](/docs/api/services#public-imports)                        | `@relkit/services`                                                                                                                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/service/define)                  |
| [Drizzle](/docs/api/drizzle#public-imports)                          | `@relkit/drizzle`, `@relkit/drizzle/sqlite`, `@relkit/drizzle/pg`, `@relkit/drizzle/mysql`                                                                                                                                                                                                                                                | [Usage and examples](/docs/modules/database)                        |
| [Better Auth](/docs/api/better-auth#public-imports)                  | `@relkit/better-auth`, `@relkit/better-auth/react`, `@relkit/better-auth/drizzle`                                                                                                                                                                                                                                                         | [Usage and examples](/docs/modules/auth)                            |
| [Routes](/docs/api/routes#public-imports)                            | `@relkit/routes`                                                                                                                                                                                                                                                                                                                          | [Usage and examples](/docs/modules/http/define)                     |
| [Events](/docs/api/events#public-imports)                            | `@relkit/events`, `@relkit/events/effect`                                                                                                                                                                                                                                                                                                 | [Usage and examples](/docs/modules/events)                          |
| [Jobs](/docs/api/jobs#public-imports)                                | `@relkit/jobs`, `@relkit/jobs/adapter`, `@relkit/jobs/server`, `@relkit/jobs/legacy`                                                                                                                                                                                                                                                      | [Usage and examples](/docs/modules/jobs/quickstart)                 |
| [Buckets](/docs/api/buckets#public-imports)                          | `@relkit/buckets`                                                                                                                                                                                                                                                                                                                         | [Usage and examples](/docs/modules/storage/define)                  |
| [Cache](/docs/api/cache#public-imports)                              | `@relkit/cache`                                                                                                                                                                                                                                                                                                                           | [Usage and examples](/docs/modules/caching/define)                  |
| [Tools](/docs/api/tools#public-imports)                              | `@relkit/tools`                                                                                                                                                                                                                                                                                                                           | [Usage and examples](/docs/modules/ai/tools)                        |
| [Agents](/docs/api/agents#public-imports)                            | `@relkit/agents`, `@relkit/agents/client-events`                                                                                                                                                                                                                                                                                          | [Usage and examples](/docs/modules/ai/approvals)                    |
| [LangChain](/docs/api/integrations/langchain#public-imports)         | `@relkit/langchain`, `@relkit/langchain/runtime`, `@relkit/langchain/continuation-validation`, `@relkit/langchain/testing`                                                                                                                                                                                                                | [Usage and examples](/docs/modules/ai)                              |
| [Client](/docs/api/client#public-imports)                            | `@relkit/client`, `@relkit/client/server`, `@relkit/client/server/tanstack-query`, `@relkit/client/tanstack-query`, `@relkit/client/react`, `@relkit/client/jobs`, `@relkit/client/build/next`, `@relkit/client/build/vite`                                                                                                               | [Usage and examples](/docs/modules/http/generated-clients)          |
| [Realtime](/docs/api/realtime#public-imports)                        | `@relkit/realtime`, `@relkit/realtime/operation-id`                                                                                                                                                                                                                                                                                       | [Usage and examples](/docs/modules/realtime)                        |
| [Testing](/docs/api/testing#public-imports)                          | `@relkit/testing`, `@relkit/testing/drizzle`, `@relkit/testing/better-auth`                                                                                                                                                                                                                                                               | [Usage and examples](/docs/modules/operations/testing)              |
| [Standalone Inspector](/docs/api/inspector#public-imports)           | `@relkit/inspector`                                                                                                                                                                                                                                                                                                                       | [Usage and examples](/docs/modules/operations/inspector)            |
| [AWS](/docs/api/integrations/aws#public-imports)                     | `@relkit/aws`, `@relkit/aws/host`, `@relkit/aws/infrastructure`, `@relkit/aws/access`                                                                                                                                                                                                                                                     | [Usage and examples](/docs/modules/deployment)                      |
| [Integration catalog](/docs/api/integrations/catalog#public-imports) | `@relkit/integrations`                                                                                                                                                                                                                                                                                                                    | [Usage and examples](/docs/modules/integrations)                    |
| [Cloudflare](/docs/api/integrations/cloudflare#public-imports)       | `@relkit/cloudflare`, `@relkit/cloudflare/runtime`                                                                                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/integrations)                    |
| [Docker](/docs/api/integrations/docker#public-imports)               | `@relkit/docker`, `@relkit/docker/runtime`                                                                                                                                                                                                                                                                                                | [Usage and examples](/docs/modules/jobs/bindings)                   |
| [Local](/docs/api/integrations/local#public-imports)                 | `@relkit/local`, `@relkit/local/runtime`                                                                                                                                                                                                                                                                                                  | [Usage and examples](/docs/modules/integrations)                    |
| [OTLP](/docs/api/integrations/otlp#public-imports)                   | `@relkit/otlp`, `@relkit/otlp/runtime`                                                                                                                                                                                                                                                                                                    | [Usage and examples](/docs/modules/operations/observability)        |
| [Pulumi](/docs/api/integrations/pulumi#public-imports)               | `@relkit/pulumi`, `@relkit/pulumi/engine`                                                                                                                                                                                                                                                                                                 | [Usage and examples](/docs/modules/jobs/deployment)                 |
| [Redis](/docs/api/integrations/redis#public-imports)                 | `@relkit/redis`, `@relkit/redis/runtime`, `@relkit/redis/local-recipe`                                                                                                                                                                                                                                                                    | [Usage and examples](/docs/modules/integrations)                    |
| [S3](/docs/api/integrations/s3#public-imports)                       | `@relkit/s3`, `@relkit/s3/runtime`, `@relkit/s3/local-recipe`                                                                                                                                                                                                                                                                             | [Usage and examples](/docs/modules/integrations)                    |
| [Sentry](/docs/api/integrations/sentry#public-imports)               | `@relkit/sentry`, `@relkit/sentry/runtime`                                                                                                                                                                                                                                                                                                | [Usage and examples](/docs/modules/operations/observability)        |
| [Inngest](/docs/api/integrations/inngest#public-imports)             | `@relkit/inngest`, `@relkit/inngest/runtime`, `@relkit/inngest/local-recipe`, `@relkit/inngest/deployment`                                                                                                                                                                                                                                | [Usage and examples](/docs/modules/jobs/bindings)                   |
| [Trigger.dev](/docs/api/integrations/trigger#public-imports)         | `@relkit/trigger`, `@relkit/trigger/runtime`, `@relkit/trigger/local-recipe`, `@relkit/trigger/deployment`                                                                                                                                                                                                                                | [Usage and examples](/docs/modules/jobs/docker)                     |
| [Effect MQ](/docs/api/integrations/effect-mq#public-imports)         | `@relkit/effect-mq`, `@relkit/effect-mq/runtime`, `@relkit/effect-mq/local-recipe`, `@relkit/effect-mq/deployment`                                                                                                                                                                                                                        | [Usage and examples](/docs/modules/jobs/schedules)                  |

## Internal packages and subpaths

The following packages are explicitly described as internal or empty compatibility packages, or use an `/internal` export path. They are inventoried but are not supported application imports. Public re-exports from their implementation files are documented through the supported facade above.

- `@relkit/agents/internal/agent-client`
- `@relkit/agents/internal/agent-telemetry`
- `@relkit/agents/internal/agent-validation`
- `@relkit/agents/internal/agent-validation-schema`
- `@relkit/agents/internal/agent-validation-value`
- `@relkit/agents/internal/approval`
- `@relkit/agents/internal/capture`
- `@relkit/agents/internal/capture-policy`
- `@relkit/agents/internal/client-contract-schema.types`
- `@relkit/agents/internal/client-events`
- `@relkit/agents/internal/define-agent-error`
- `@relkit/agents/internal/define-agent-limits`
- `@relkit/agents/internal/define-agent-support`
- `@relkit/agents/internal/generated-function`
- `@relkit/agents/internal/model-selection`
- `@relkit/agents/internal/observability`
- `@relkit/agents/internal/runtime-events`
- `@relkit/agents/internal/state-control-requests.types`
- `@relkit/agents/internal/state-provider.types`
- `@relkit/agents/internal/state-receipts.types`
- `@relkit/agents/internal/state-thread-requests.types`
- `@relkit/agents/internal/state.types`
- `@relkit/agents/internal/thread-transition`
- `@relkit/app/internal/runtime`
- `@relkit/cli/internal/tooling`
- `@relkit/client-generator`
- `@relkit/cloud-aws`
- `@relkit/compiler`
- `@relkit/config/internal/config`
- `@relkit/contracts`
- `@relkit/deploy`
- `@relkit/deploy-pulumi`
- `@relkit/diagnostics`
- `@relkit/drizzle/internal`
- `@relkit/engine`
- `@relkit/functions/internal`
- `@relkit/graph`
- `@relkit/inspector-api`
- `@relkit/invocation`
- `@relkit/local-service`
- `@relkit/observability`
- `@relkit/observability-local/internal/local-worker`
- `@relkit/openapi`
- `@relkit/provider/internal/dependencies`
- `@relkit/providers-standard`
- `@relkit/runtime-effect`
- `@relkit/runtime-hono`
- `@relkit/supervisor`
- `@relkit/testing/internal/fakes`
- `@relkit/testing/internal/jobs-utils`
- `@relkit/testing/internal/runtime-clock`
- `@relkit/testing/internal/testing-owner`
- `@relkit/testing/internal/work-ownership`
- `create-relkit/internal/add-transaction-files`
- `create-relkit/internal/add-types`
- `create-relkit/internal/build-catalog`
- `create-relkit/internal/catalog-resolution`
- `create-relkit/internal/dependency-patch-installation`
- `create-relkit/internal/dependency-patches`
- `create-relkit/internal/generate`
- `create-relkit/internal/generate-process`
- `create-relkit/internal/generator-cleanup`
- `create-relkit/internal/generator-errors`
- `create-relkit/internal/generator-filesystem`
- `create-relkit/internal/generator-filesystem.types`
- `create-relkit/internal/generator-paths`
- `create-relkit/internal/generator-process`
- `create-relkit/internal/generator-process.types`
- `create-relkit/internal/generator-prompt`
- `create-relkit/internal/generator-runtime`
- `create-relkit/internal/options`
- `create-relkit/internal/project-manifest.schemas`
- `create-relkit/internal/prompt-driver`
- `create-relkit/internal/prompt-driver.types`
- `create-relkit/internal/scaffold-catalog`
- `create-relkit/internal/scaffold-catalog.types`
- `create-relkit/internal/validate-paths`

---

# Realtime API
Source: https://relkit.dev/docs/api/realtime

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineChannel](/docs/api/realtime#definechannel)

For configuration and examples, read [realtime](/docs/modules/realtime), [access](/docs/modules/realtime/access), [react](/docs/modules/realtime/react).

## Frontend usage

[Subscribe to a channel](/docs/modules/realtime/react) shows the client side of this capability.

## Public imports

- `@relkit/realtime` — 75 exports
- `@relkit/realtime/operation-id` — 9 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                                 | Kind  | Import from                                         | Example                                                                       |
| --------------------------------------------------------------------------------------------------- | ----- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| [AcquirePresenceLease](/docs/api/realtime#acquirepresencelease-type-alias)                          | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#acquirepresencelease-type-alias)             |
| [AppendChannelEvent](/docs/api/realtime#appendchannelevent-interface)                               | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#appendchannelevent-interface)                |
| [AppendReceiptLookup](/docs/api/realtime#appendreceiptlookup-type-alias)                            | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#appendreceiptlookup-type-alias)              |
| [ChannelCheckpoint](/docs/api/realtime#channelcheckpoint-interface)                                 | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelcheckpoint-interface)                 |
| [ChannelClientPolicy](/docs/api/realtime#channelclientpolicy-type-alias)                            | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelclientpolicy-type-alias)              |
| [ChannelDescriptor](/docs/api/realtime#channeldescriptor-type-alias)                                | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeldescriptor-type-alias)                |
| [ChannelDescriptorAny](/docs/api/realtime#channeldescriptorany-type-alias)                          | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeldescriptorany-type-alias)             |
| [ChannelDescriptorData](/docs/api/realtime#channeldescriptordata-type-alias)                        | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeldescriptordata-type-alias)            |
| [ChannelEventPage](/docs/api/realtime#channeleventpage-interface)                                   | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeleventpage-interface)                  |
| [ChannelEventRecord](/docs/api/realtime#channeleventrecord-interface)                               | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeleventrecord-interface)                |
| [ChannelGrant](/docs/api/realtime#channelgrant-interface)                                           | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelgrant-interface)                      |
| [ChannelGuard](/docs/api/realtime#channelguard-type-alias)                                          | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelguard-type-alias)                     |
| [ChannelPresence](/docs/api/realtime#channelpresence-type-alias)                                    | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelpresence-type-alias)                  |
| [ChannelReplay](/docs/api/realtime#channelreplay-interface)                                         | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelreplay-interface)                     |
| [ChannelTriggerOptions](/docs/api/realtime#channeltriggeroptions-interface)                         | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channeltriggeroptions-interface)             |
| [ChannelValidationError](/docs/api/realtime#channelvalidationerror-class)                           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#channelvalidationerror-class)                |
| [CountPresence](/docs/api/realtime#countpresence-interface)                                         | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#countpresence-interface)                     |
| [createOperationId](/docs/api/realtime#createoperationid)                                           | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#createoperationid)                           |
| [createOperationIdEffect](/docs/api/realtime#createoperationideffect)                               | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#createoperationideffect)                     |
| [createProviderRealtimeDispatcher](/docs/api/realtime#createproviderrealtimedispatcher)             | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#createproviderrealtimedispatcher)            |
| [createProviderRealtimeDispatcherEffect](/docs/api/realtime#createproviderrealtimedispatchereffect) | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#createproviderrealtimedispatchereffect)      |
| [currentRealtimeDispatcher](/docs/api/realtime#currentrealtimedispatcher)                           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#currentrealtimedispatcher)                   |
| [currentRealtimeDispatcherEffect](/docs/api/realtime#currentrealtimedispatchereffect)               | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#currentrealtimedispatchereffect)             |
| [defineChannel](/docs/api/realtime#definechannel)                                                   | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#definechannel)                               |
| [defineChannelEffect](/docs/api/realtime#definechanneleffect)                                       | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#definechanneleffect)                         |
| [DefineChannelOptions](/docs/api/realtime#definechanneloptions-interface)                           | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#definechanneloptions-interface)              |
| [getChannelPresenceEffect](/docs/api/realtime#getchannelpresenceeffect)                             | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#getchannelpresenceeffect)                    |
| [isChannelDescriptor](/docs/api/realtime#ischanneldescriptor)                                       | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#ischanneldescriptor)                         |
| [isChannelDescriptorEffect](/docs/api/realtime#ischanneldescriptoreffect)                           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#ischanneldescriptoreffect)                   |
| [limitsForEffect](/docs/api/realtime#limitsforeffect-1)                                             | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#limitsforeffect-1)                           |
| [LookupAppendReceipt](/docs/api/realtime#lookupappendreceipt-interface)                             | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#lookupappendreceipt-interface)               |
| [MemberPresence](/docs/api/realtime#memberpresence-interface)                                       | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#memberpresence-interface)                    |
| [MemberPresenceDescriptor](/docs/api/realtime#memberpresencedescriptor-interface)                   | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#memberpresencedescriptor-interface)          |
| [observeRealtime](/docs/api/realtime#observerealtime)                                               | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#observerealtime)                             |
| [OperationIdEntropy](/docs/api/realtime#operationidentropy-class)                                   | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#operationidentropy-class)                    |
| [OperationIdEntropyLive](/docs/api/realtime#operationidentropylive)                                 | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#operationidentropylive)                      |
| [OperationIdError](/docs/api/realtime#operationiderror-class)                                       | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#operationiderror-class)                      |
| [OperationIdFailure](/docs/api/realtime#operationidfailure-class)                                   | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#operationidfailure-class)                    |
| [operationIdTimestamp](/docs/api/realtime#operationidtimestamp)                                     | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#operationidtimestamp)                        |
| [operationIdTimestampEffect](/docs/api/realtime#operationidtimestampeffect)                         | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#operationidtimestampeffect)                  |
| [parseOperationId](/docs/api/realtime#parseoperationid)                                             | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#parseoperationid)                            |
| [parseOperationIdEffect](/docs/api/realtime#parseoperationideffect)                                 | Value | `@relkit/realtime`, `@relkit/realtime/operation-id` | [API example](/docs/api/realtime#parseoperationideffect)                      |
| [PresenceLeaseRequest](/docs/api/realtime#presenceleaserequest-interface)                           | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#presenceleaserequest-interface)              |
| [PresenceMember](/docs/api/realtime#presencemember-interface)                                       | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#presencemember-interface)                    |
| [PresenceSnapshot](/docs/api/realtime#presencesnapshot-type-alias)                                  | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#presencesnapshot-type-alias)                 |
| [ProviderRealtimeDispatcherOptions](/docs/api/realtime#providerrealtimedispatcheroptions-interface) | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#providerrealtimedispatcheroptions-interface) |
| [providerSourceLayer](/docs/api/realtime#providersourcelayer)                                       | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#providersourcelayer)                         |
| [ReadChannelEvents](/docs/api/realtime#readchannelevents-interface)                                 | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#readchannelevents-interface)                 |
| [ReadPresenceRequest](/docs/api/realtime#readpresencerequest-type-alias)                            | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#readpresencerequest-type-alias)              |
| [readProviderPresenceEffect](/docs/api/realtime#readproviderpresenceeffect)                         | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#readproviderpresenceeffect)                  |
| [RealtimeActionError](/docs/api/realtime#realtimeactionerror-class)                                 | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeactionerror-class)                   |
| [RealtimeDispatcher](/docs/api/realtime#realtimedispatcher-interface)                               | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimedispatcher-interface)                |
| [RealtimeDispatcherError](/docs/api/realtime#realtimedispatchererror-class)                         | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimedispatchererror-class)               |
| [RealtimeDispatcherLive](/docs/api/realtime#realtimedispatcherlive)                                 | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimedispatcherlive)                      |
| [RealtimeDispatcherService](/docs/api/realtime#realtimedispatcherservice-class)                     | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimedispatcherservice-class)             |
| [RealtimeLimits](/docs/api/realtime#realtimelimits-interface)                                       | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimelimits-interface)                    |
| [RealtimeOperation](/docs/api/realtime#realtimeoperation-type-alias)                                | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeoperation-type-alias)                |
| [RealtimeProvider](/docs/api/realtime#realtimeprovider-interface)                                   | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeprovider-interface)                  |
| [RealtimeProviderError](/docs/api/realtime#realtimeprovidererror-class)                             | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeprovidererror-class)                 |
| [RealtimeProviderSource](/docs/api/realtime#realtimeprovidersource-class)                           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeprovidersource-class)                |
| [RealtimeProviderSourceService](/docs/api/realtime#realtimeprovidersourceservice-interface)         | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimeprovidersourceservice-interface)     |
| [RealtimeScope](/docs/api/realtime#realtimescope-interface)                                         | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimescope-interface)                     |
| [RealtimeTelemetry](/docs/api/realtime#realtimetelemetry-class)                                     | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimetelemetry-class)                     |
| [RealtimeTelemetryLive](/docs/api/realtime#realtimetelemetrylive)                                   | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimetelemetrylive)                       |
| [RealtimeTelemetryService](/docs/api/realtime#realtimetelemetryservice-interface)                   | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#realtimetelemetryservice-interface)          |
| [ReleasePresenceLease](/docs/api/realtime#releasepresencelease-type-alias)                          | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#releasepresencelease-type-alias)             |
| [RenewPresenceLease](/docs/api/realtime#renewpresencelease-type-alias)                              | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#renewpresencelease-type-alias)               |
| [runWithRealtimeDispatcher](/docs/api/realtime#runwithrealtimedispatcher)                           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#runwithrealtimedispatcher)                   |
| [runWithRealtimeDispatcherEffect](/docs/api/realtime#runwithrealtimedispatchereffect)               | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#runwithrealtimedispatchereffect)             |
| [setActiveRealtimeDispatcher](/docs/api/realtime#setactiverealtimedispatcher)                       | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#setactiverealtimedispatcher)                 |
| [setActiveRealtimeDispatcherEffect](/docs/api/realtime#setactiverealtimedispatchereffect)           | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#setactiverealtimedispatchereffect)           |
| [triggerChannelEffect](/docs/api/realtime#triggerchanneleffect)                                     | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#triggerchanneleffect)                        |
| [triggerProviderEffect](/docs/api/realtime#triggerprovidereffect)                                   | Value | `@relkit/realtime`                                  | [API example](/docs/api/realtime#triggerprovidereffect)                       |
| [TriggerReceipt](/docs/api/realtime#triggerreceipt-interface)                                       | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#triggerreceipt-interface)                    |
| [WaitForChannelEvents](/docs/api/realtime#waitforchannelevents-interface)                           | Type  | `@relkit/realtime`                                  | [API example](/docs/api/realtime#waitforchannelevents-interface)              |

## `channel-operations.ts`

### getChannelPresenceEffect

Reads a channel's presence snapshot in the Effect path.

**Example**

```ts
Effect.runPromise(getChannelPresenceEffect(channel, {}));
```

**Signature**

```ts
declare const getChannelPresenceEffect: (
  channel: ChannelDescriptorData,
  params: unknown,
) => Effect.Effect<
  PresenceSnapshot,
  ChannelValidationError | RealtimeDispatcherError | RealtimeProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-operations.ts#L85)

### runChannelPromise

Converts an Effect result to the legacy Promise rejection shape.

**Throws**

TypeError, Error, or the original provider rejection on failure.

**Example**

```ts
await runChannelPromise(triggerChannelEffect(channel, {}, "posted", "hello"));
```

**Signature**

```ts
declare const runChannelPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-operations.ts#L18)

### triggerChannelEffect

Validates and dispatches one channel event in the Effect path.

**Example**

```ts
Effect.runPromise(triggerChannelEffect(channel, {}, "posted", "hello"));
```

**Signature**

```ts
declare const triggerChannelEffect: (
  channel: ChannelDescriptorData,
  params: unknown,
  event: string,
  payload: unknown,
  options?: ChannelTriggerOptions | undefined,
) => Effect.Effect<
  TriggerReceipt,
  ChannelValidationError | RealtimeDispatcherError | RealtimeProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-operations.ts#L41)

## `channel-policy.ts`

### copyChannelClient

Copies a client policy.

**Throws**

TypeError for a malformed policy.

**Example**

```ts
copyChannelClient({ public: true });
```

**Signature**

```ts
declare const copyChannelClient: (value: unknown) => ChannelClientPolicy<ChannelGuard> | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L56)

### copyChannelClientEffect

Copies an authored client policy into a descriptor value.

**Example**

```ts
Effect.runSync(copyChannelClientEffect({ public: true }));
```

**Signature**

```ts
declare const copyChannelClientEffect: (
  value: unknown,
) => Effect.Effect<
  { public: true; authorize?: never } | { authorize: ChannelGuard; public?: never } | undefined,
  ChannelValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L21)

### copyChannelPresence

Copies a presence policy.

**Throws**

TypeError for malformed or unprotected member presence.

**Example**

```ts
copyChannelPresence("count", undefined);
```

**Signature**

```ts
declare const copyChannelPresence: (
  value: unknown,
  client: ChannelClientPolicy<ChannelGuard> | undefined,
) => ChannelPresence | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L116)

### copyChannelPresenceEffect

Copies presence and checks member authorization.

**Example**

```ts
Effect.runSync(copyChannelPresenceEffect("count", undefined));
```

**Signature**

```ts
declare const copyChannelPresenceEffect: (
  value: unknown,
  client: ChannelClientPolicy<ChannelGuard> | undefined,
) => Effect.Effect<
  | "count"
  | {
      member: MemberPresenceDescriptor["member"];
      resolve: MemberPresenceDescriptor["resolve"];
      maxMembers: number;
    }
  | undefined,
  ChannelValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L73)

### copyChannelReplay

Copies replay limits.

**Throws**

TypeError for invalid limits.

**Example**

```ts
copyChannelReplay({ retentionMs: 100, maxEvents: 10 });
```

**Signature**

```ts
declare const copyChannelReplay: (value: unknown) => ChannelReplay | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L155)

### copyChannelReplayEffect

Copies replay limits into a descriptor value.

**Example**

```ts
Effect.runSync(copyChannelReplayEffect({ retentionMs: 100, maxEvents: 10 }));
```

**Signature**

```ts
declare const copyChannelReplayEffect: (
  value: unknown,
) => Effect.Effect<
  { retentionMs: number; maxEvents: number } | undefined,
  ChannelValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-policy.ts#L127)

## `channel-validation.ts`

### assertChannelSchema

Asserts a Standard Schema v1 validator.

**Throws**

TypeError for a malformed schema.

**Example**

```ts
assertChannelSchema(schema, "params");
```

**Signature**

```ts
declare const assertChannelSchema: (
  value: unknown,
  name: string,
) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L84)

### assertChannelSchemaEffect

Validates a schema shape with a tagged error.

**Example**

```ts
Effect.runSync(assertChannelSchemaEffect(schema, "params"));
```

**Signature**

```ts
declare const assertChannelSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<undefined, ChannelValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L65)

### copyChannelEvents

Copies an event schema map.

**Throws**

TypeError for invalid names or schemas.

**Example**

```ts
copyChannelEvents({ changed: schema });
```

**Signature**

```ts
declare const copyChannelEvents: (value: unknown) => Readonly<Record<string, StandardSchemaV1>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L177)

### copyChannelEventsEffect

Copies and normalizes an authored event schema map.

**Example**

```ts
Effect.runSync(copyChannelEventsEffect({ changed: schema }));
```

**Signature**

```ts
declare const copyChannelEventsEffect: (
  value: unknown,
) => Effect.Effect<
  Readonly<Record<string, StandardSchemaV1<unknown, unknown>>>,
  ChannelValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L145)

### isChannelSchema

Checks a Standard Schema v1 validator.

**Example**

```ts
isChannelSchema(schema);
```

**Signature**

```ts
declare const isChannelSchema: (value: unknown) => value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L56)

### isChannelSchemaEffect

Checks the Standard Schema v1 shape in the Effect path.

**Example**

```ts
Effect.runSync(isChannelSchemaEffect(schema));
```

**Signature**

```ts
declare const isChannelSchemaEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L41)

### isRecord

Checks whether a value is a non-array record.

**Example**

```ts
isRecord({});
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L33)

### isRecordEffect

Checks an unknown value for the record shape in the Effect path.

**Example**

```ts
Effect.runSync(isRecordEffect({}));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L22)

### runChannelValidation

Runs a validation effect while retaining the public TypeError contract.

**Throws**

TypeError for a tagged validation failure.

**Example**

```ts
runChannelValidation(copyChannelEventsEffect({ posted: schema }));
```

**Signature**

```ts
declare const runChannelValidation: <A>(effect: Effect.Effect<A, ChannelValidationError>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L12)

### validateChannelValue

Validates a value through the Promise compatibility API.

**Throws**

TypeError when validation fails.

**Example**

```ts
await validateChannelValue(schema, value, "params");
```

**Signature**

```ts
declare const validateChannelValue: (
  schema: StandardSchemaV1,
  value: unknown,
  name: string,
) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L126)

### validateChannelValueEffect

Validates a value with a Standard Schema validator.

**Example**

```ts
Effect.runPromise(validateChannelValueEffect(schema, value, "params"));
```

**Signature**

```ts
declare const validateChannelValueEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  value: unknown,
  name: string,
) => Effect.Effect<unknown, ChannelValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel-validation.ts#L97)

## `channel.ts`

### defineChannel

Defines a typed channel for validated backend publication and observation.

**Throws**

TypeError for invalid channel options.

**Example**

```ts
import { defineChannel } from "@relkit/realtime";
import { z } from "@relkit/schema";
const alerts = defineChannel({
  id: "alerts",
  params: z.object({}),
  events: { posted: z.string() },
});
```

**Signature**

```ts
declare const defineChannel: <
  const Id extends string,
  const ParamsSchema extends StandardSchemaV1,
  const Events extends Readonly<Record<string, StandardSchemaV1>>,
  const Client extends ChannelClientPolicy<ChannelGuard<InferOutput<ParamsSchema>>> | undefined,
  const Presence extends ChannelPresence<InferOutput<ParamsSchema>> | undefined = undefined,
>(
  options: DefineChannelOptions<Id, ParamsSchema, Events, Client, Presence>,
) => ChannelDescriptor<Id, ParamsSchema, Events, Client, Presence>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L132)

Since v0.4.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/announcements/channels/announcements.channel.ts"
/** Declares public posted-announcement events with five-minute replay retention and a thousand-event limit. */
import { defineChannel } from "@relkit/app/realtime";
import { z } from "@relkit/app/schema";

const announcements = defineChannel({
  id: "announcements.feed",
  params: z.object({}),
  events: { posted: z.object({ message: z.string(), postedAt: z.string() }) },
  client: { public: true },
  replay: { retentionMs: 300_000, maxEvents: 1_000 },
});

export default announcements;
```

**Frontend**

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider. It subscribes to this declaration's `announcements.feed` channel:

```tsx title="src/Announcements.tsx"
"use client";

/** Combines the commerce announcement query with channel invalidation and reconnect recovery. */
import { useChannel, useRoute } from "@relkit/client/react";

/** Restores authoritative messages on publication, catch-up, and replay gaps.
 * @returns The current messages with query failure and channel status feedback. */
export function Announcements() {
  const messages = useRoute("GET /announcements", { input: {} });
  const channel = useChannel("announcements.feed", {
    params: {},
    on: {
      posted: () => {
        void messages.refetch();
      },
    },
    onCaughtUp: async () => {
      await messages.refetch();
    },
    onGap: async () => {
      await messages.refetch();
    },
  });

  if (messages.isError) return <p role="alert">{messages.error.message}</p>;
  return (
    <section>
      <p role="status">Channel: {channel.status}</p>
      {messages.isPending && <p>Loading messages…</p>}
      <ul>
        {messages.data?.messages.map((message, index) => (
          <li key={index}>{message}</li>
        ))}
      </ul>
    </section>
  );
}
```

`params: {}` selects the channel's empty partition schema. `posted` is a declared event, so its
callback is checked against the event map. The route query restores the authoritative messages
after updates, catch-up, or replay gaps. Backend `trigger()` publishes; the browser subscribes.

Reference: [`useChannel`](/docs/api/client#usechannel), [`useRealtime`](/docs/api/client#userealtime).
Continue with [subscription and recovery](/docs/modules/realtime/react).

### "./channel.types.js" (namespace export)

Re-exports all named exports from the "./channel.types.js" module.

**Signature**

```ts
export * from "./channel.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L31)

### defineChannelEffect

Constructs a typed channel descriptor through validated Effect operations.

**Example**

```ts
Effect.runSync(defineChannelEffect({ id: "news", params: schema, events: { posted: schema } }));
```

**Signature**

```ts
declare const defineChannelEffect: <
  const Id extends string,
  const ParamsSchema extends StandardSchemaV1,
  const Events extends Readonly<Record<string, StandardSchemaV1>>,
  const Client extends ChannelClientPolicy<ChannelGuard<InferOutput<ParamsSchema>>> | undefined,
  const Presence extends ChannelPresence<InferOutput<ParamsSchema>> | undefined = undefined,
>(
  options: DefineChannelOptions<Id, ParamsSchema, Events, Client, Presence>,
) => Effect.Effect<
  ChannelDescriptor<Id, ParamsSchema, Events, Client, Presence>,
  ChannelValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L38)

### getChannelPresenceEffect

**Signature**

```ts
declare const getChannelPresenceEffect: (
  channel: ChannelDescriptorData,
  params: unknown,
) => Effect.Effect<
  PresenceSnapshot,
  ChannelValidationError | RealtimeDispatcherError | RealtimeProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L32)

### isChannelDescriptor

Checks for a channel descriptor.

**Example**

```ts
isChannelDescriptor(channel);
```

**Signature**

```ts
declare const isChannelDescriptor: (value: unknown) => value is ChannelDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L162)

### isChannelDescriptorEffect

Checks for a channel descriptor in the Effect path.

**Example**

```ts
Effect.runSync(isChannelDescriptorEffect(channel));
```

**Signature**

```ts
declare const isChannelDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L150)

### triggerChannelEffect

**Signature**

```ts
declare const triggerChannelEffect: (
  channel: ChannelDescriptorData,
  params: unknown,
  event: string,
  payload: unknown,
  options?: ChannelTriggerOptions | undefined,
) => Effect.Effect<
  TriggerReceipt,
  ChannelValidationError | RealtimeDispatcherError | RealtimeProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.ts#L32)

## `channel.types.ts`

### ChannelClientPolicy (type alias)

Public access or an authorization guard, exclusively.

**Example**

```ts
const policy: ChannelClientPolicy<ChannelGuard> = { public: true };
```

**Signature**

```ts
type ChannelClientPolicy<Guard> =
  | { readonly public: true; readonly authorize?: never }
  | { readonly authorize: Guard; readonly public?: never };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L19)

### ChannelDescriptor (type alias)

A typed channel descriptor with backend publication methods.

**Example**

```ts
const channel: ChannelDescriptorAny = defineChannel(options);
```

**Signature**

```ts
type ChannelDescriptor<
  Id extends string,
  ParamsSchema extends StandardSchemaV1,
  Events extends Readonly<Record<string, StandardSchemaV1>>,
  Client extends ChannelClientPolicy<ChannelGuard<InferOutput<ParamsSchema>>> | undefined,
  Presence extends ChannelPresence<InferOutput<ParamsSchema>> | undefined,
> = DescriptorBase<"channel", Id> & {
  readonly params: ParamsSchema;
  readonly events: Events;
  readonly profile?: string;
  readonly client?: Client;
  readonly replay?: ChannelReplay;
  readonly presence?: Presence;
  /** Validates and publishes one event through the bound dispatcher.
   * @param params - Schema input for channel parameters.
   * @param event - One of the declared event names.
   * @param payload - Input for the selected event schema.
   * @param options - Optional idempotency key.
   * @returns A trigger receipt or validation/provider rejection.
   * @example await channel.trigger({ orderId: "o1" }, "changed", { status: "paid" });
   */
  readonly trigger: <Name extends Extract<keyof Events, string>>(
    params: InferInput<ParamsSchema>,
    event: Name,
    payload: InferInput<Events[Name]>,
    options?: { readonly idempotencyKey?: OperationId },
  ) => Promise<TriggerReceipt>;
} & ([Presence] extends [undefined]
    ? {}
    : {
        /** Reads validated presence through the bound dispatcher.
         * @param params - Schema input for channel parameters.
         * @returns Count or member presence, or a validation/provider rejection.
         * @example await channel.getPresence({ orderId: "o1" });
         */
        readonly getPresence: (
          params: InferInput<ParamsSchema>,
        ) => Promise<PresenceResult<Presence>>;
      });
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L49)

### ChannelDescriptorAny (type alias)

Erased descriptor type retained for existing public API consumers.

**Example**

```ts
const channel: ChannelDescriptorAny = registry.get("news");
```

**Signature**

```ts
type ChannelDescriptorAny = ChannelDescriptor<
  string,
  StandardSchemaV1,
  Readonly<Record<string, StandardSchemaV1>>,
  ChannelClientPolicy<ChannelGuard> | undefined,
  ChannelPresence | undefined
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L97)

### ChannelDescriptorData (type alias)

Descriptor data read by provider and transport boundaries.
Typed trigger methods remain on ChannelDescriptor; providers read only this data.

**Example**

```ts
const data: ChannelDescriptorData = defineChannel(options);
```

**Signature**

```ts
type ChannelDescriptorData = DescriptorBase<"channel", string> & {
  readonly params: StandardSchemaV1;
  readonly events: Readonly<Record<string, StandardSchemaV1>>;
  readonly profile?: string;
  readonly client?: ChannelClientPolicy<ChannelGuard>;
  readonly replay?: ChannelReplay;
  readonly presence?: ChannelPresence;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L108)

### ChannelGuard (type alias)

Authorizes channel parameters against an application context.

**Example**

```ts
const allow: ChannelGuard = async () => true;
```

**Signature**

```ts
type ChannelGuard<Params = unknown, Context = unknown> = (
  params: Params,
  context: Context,
) => MaybePromise<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L12)

### ChannelPresence (type alias)

Count-only or protected member presence.

**Example**

```ts
const presence: ChannelPresence = "count";
```

**Signature**

```ts
type ChannelPresence<Params = unknown, Context = unknown> =
  "count" | MemberPresenceDescriptor<StandardSchemaV1, Params, Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L37)

### ChannelReplay (interface)

Retention settings copied into a channel descriptor.

**Example**

```ts
const replay: ChannelReplay = { retentionMs: 60000, maxEvents: 100 };
```

**Signature**

```ts
export interface ChannelReplay {
  readonly retentionMs: number;
  readonly maxEvents: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L42)

### DefineChannelOptions (interface)

Authored channel options before validation and normalization.

**Example**

```ts
const options: DefineChannelOptions<
  "news",
  typeof schema,
  { posted: typeof schema },
  undefined,
  undefined
> = {
  id: "news",
  params: schema,
  events: { posted: schema },
};
```

**Signature**

```ts
export interface DefineChannelOptions<
  Id extends string,
  ParamsSchema extends StandardSchemaV1,
  Events extends Readonly<Record<string, StandardSchemaV1>>,
  Client extends ChannelClientPolicy<ChannelGuard<InferOutput<ParamsSchema>>> | undefined,
  Presence extends ChannelPresence<InferOutput<ParamsSchema>> | undefined,
> extends DescriptorMetadata {
  readonly id: Id;
  readonly params: ParamsSchema;
  readonly events: Events;
  readonly profile?: string;
  readonly client?: Client;
  readonly replay?: ChannelReplay;
  readonly presence?: Presence;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L119)

### MemberPresenceDescriptor (interface)

Describes validated member presence for a protected channel.

**Example**

```ts
const presence: MemberPresenceDescriptor<typeof schema> = {
  member: schema,
  resolve: async () => ({ name: "Ada" }),
  maxMembers: 10,
};
```

**Signature**

```ts
export interface MemberPresenceDescriptor<
  MemberSchema extends StandardSchemaV1 = StandardSchemaV1,
  Params = unknown,
  Context = unknown,
> {
  readonly member: MemberSchema;
  readonly resolve: (params: Params, context: Context) => MaybePromise<InferInput<MemberSchema>>;
  readonly maxMembers: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/channel.types.ts#L25)

## `dispatch.ts`

### "./dispatch.types.js" (namespace export)

Re-exports all named exports from the "./dispatch.types.js" module.

**Signature**

```ts
export * from "./dispatch.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L6)

### RealtimeDispatcherLive

Resolves the currently bound dispatcher when an Effect requests it.

**Example**

```ts
Effect.provide(currentRealtimeDispatcherEffect(), RealtimeDispatcherLive);
```

**Signature**

```ts
declare const RealtimeDispatcherLive: Layer.Layer<
  RealtimeDispatcherService,
  RealtimeDispatcherError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L19)

### RealtimeDispatcherService (class)

Injectable dispatcher for Effect-native channel operations.

**Example**

```ts
Effect.provide(currentRealtimeDispatcherEffect(), RealtimeDispatcherLive);
```

**Signature**

```ts
declare class RealtimeDispatcherService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L12)

### currentRealtimeDispatcher

Returns the dispatcher bound to the current generation.

**Throws**

Error when no dispatcher is active.

**Example**

```ts
currentRealtimeDispatcher();
```

**Signature**

```ts
declare const currentRealtimeDispatcher: () => RealtimeDispatcher;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L138)

### currentRealtimeDispatcherEffect

Resolves the current dispatcher with a typed missing-binding error.

**Example**

```ts
Effect.runPromise(currentRealtimeDispatcherEffect());
```

**Signature**

```ts
declare const currentRealtimeDispatcherEffect: () => Effect.Effect<
  RealtimeDispatcher,
  RealtimeDispatcherError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L117)

### runWithRealtimeDispatcher

Executes an action under a dispatcher scope.

**Throws**

The action's synchronous error or an Effect runtime defect.

**Example**

```ts
runWithRealtimeDispatcher(dispatcher, () => channel.trigger({}, "posted", "hello"));
```

**Signature**

```ts
declare const runWithRealtimeDispatcher: <Value>(
  dispatcher: RealtimeDispatcher,
  action: () => Value,
) => Value;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L93)

### runWithRealtimeDispatcherEffect

Runs an action with a dispatcher in async-local generation scope.

**Example**

```ts
Effect.runSync(runWithRealtimeDispatcherEffect(dispatcher, () => 1));
```

**Signature**

```ts
declare const runWithRealtimeDispatcherEffect: <Value>(
  dispatcher: RealtimeDispatcher,
  action: (signal: AbortSignal) => Value,
) => Effect.Effect<Awaited<Value>, RealtimeActionError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L65)

### setActiveRealtimeDispatcher

Sets the fallback dispatcher for code outside a generation scope.

**Example**

```ts
setActiveRealtimeDispatcher(dispatcher);
```

**Signature**

```ts
declare const setActiveRealtimeDispatcher: (dispatcher: RealtimeDispatcher | undefined) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L41)

### setActiveRealtimeDispatcherEffect

Changes the fallback dispatcher in the Effect path.

**Example**

```ts
Effect.runSync(setActiveRealtimeDispatcherEffect(dispatcher));
```

**Signature**

```ts
declare const setActiveRealtimeDispatcherEffect: (
  dispatcher: RealtimeDispatcher | undefined,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.ts#L30)

## `dispatch.types.ts`

### ChannelTriggerOptions (interface)

Options attached to a channel trigger request.

**Example**

```ts
const options: ChannelTriggerOptions = { idempotencyKey: id };
```

**Signature**

```ts
export interface ChannelTriggerOptions {
  readonly idempotencyKey?: OperationId;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.types.ts#L7)

### RealtimeDispatcher (interface)

A generation-bound dispatcher for validated realtime operations.

**Example**

```ts
const dispatcher: RealtimeDispatcher = {
  trigger: async () => receipt,
  getPresence: async () => presence,
};
```

**Signature**

```ts
export interface RealtimeDispatcher {
  /** Publishes a validated event.
   * @param request - Channel, parameters, event, payload, and optional idempotency key.
   * @param signal - Optional cancellation signal for in-flight work.
   * @returns A trigger receipt or a provider rejection.
   * @example await dispatcher.trigger({ channel, params: {}, event: "posted", payload: "hello" });
   */
  readonly trigger: (
    request: {
      readonly channel: ChannelDescriptorData;
      readonly params: unknown;
      readonly event: string;
      readonly payload: unknown;
      readonly options?: ChannelTriggerOptions;
    },
    signal?: AbortSignal,
  ) => MaybePromise<TriggerReceipt>;
  /** Reads the current presence snapshot.
   * @param request - Channel and validated parameters.
   * @param signal - Optional cancellation signal for in-flight work.
   * @returns Presence snapshot or a provider rejection.
   * @example await dispatcher.getPresence({ channel, params: {} });
   */
  readonly getPresence: (
    request: {
      readonly channel: ChannelDescriptorData;
      readonly params: unknown;
    },
    signal?: AbortSignal,
  ) => MaybePromise<PresenceSnapshot>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/dispatch.types.ts#L13)

## `index.ts`

### "./channel.js" (namespace export)

Re-exports all named exports from the "./channel.js" module.

**Signature**

```ts
export * from "./channel.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L1)

### "./dispatch.js" (namespace export)

Re-exports all named exports from the "./dispatch.js" module.

**Signature**

```ts
export * from "./dispatch.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L4)

### "./operation-id.js" (namespace export)

Re-exports all named exports from the "./operation-id.js" module.

**Signature**

```ts
export * from "./operation-id.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L3)

### "./provider-dispatcher.js" (namespace export)

Re-exports all named exports from the "./provider-dispatcher.js" module.

**Signature**

```ts
export * from "./provider-dispatcher.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L6)

### "./provider.js" (namespace export)

Re-exports all named exports from the "./provider.js" module.

**Signature**

```ts
export * from "./provider.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L2)

### "./realtime-errors.js" (namespace export)

Re-exports all named exports from the "./realtime-errors.js" module.

**Signature**

```ts
export * from "./realtime-errors.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L7)

### "./realtime-observability.js" (namespace export)

Re-exports all named exports from the "./realtime-observability.js" module.

**Signature**

```ts
export * from "./realtime-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L8)

### "./realtime-observability.types.js" (namespace export)

Re-exports all named exports from the "./realtime-observability.types.js" module.

**Signature**

```ts
export * from "./realtime-observability.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L9)

### "./types.js" (namespace export)

Re-exports all named exports from the "./types.js" module.

**Signature**

```ts
export * from "./types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/index.ts#L5)

## `operation-id.ts`

### OperationIdEntropy (class)

Injectable random-byte service for operation ID generation.

**Example**

```ts
Effect.provide(createOperationIdEffect(0), OperationIdEntropyLive);
```

**Signature**

```ts
declare class OperationIdEntropy
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L28)

### OperationIdEntropyLive

Cryptographic entropy for live UUIDv7 creation.

**Example**

```ts
Effect.provide(createOperationIdEffect(0), OperationIdEntropyLive);
```

**Signature**

```ts
declare const OperationIdEntropyLive: Layer.Layer<OperationIdEntropy, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L35)

### OperationIdError (class)

Compatibility error for invalid or expired operation IDs.

**Example**

```ts
new OperationIdError("OPERATION_ID_INVALID", "Operation ID must be a UUIDv7.");
```

**Signature**

```ts
declare class OperationIdError { constructor(
    readonly code: "OPERATION_ID_INVALID" | "IDEMPOTENCY_WINDOW_EXPIRED",
    message: string,
  ) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L10)

### createOperationId

Creates a UUIDv7 operation ID.

**Throws**

RangeError for an invalid timestamp.

**Example**

```ts
createOperationId(Date.now());
```

**Signature**

```ts
declare const createOperationId: (now?: number) => OperationId;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L151)

### createOperationIdEffect

Creates a UUIDv7 ID using Effect Clock and injectable entropy.

**Example**

```ts
Effect.runSync(Effect.provide(createOperationIdEffect(0), OperationIdEntropyLive));
```

**Signature**

```ts
declare const createOperationIdEffect: (
  now: number | undefined,
) => Effect.Effect<OperationId, OperationIdFailure, OperationIdEntropy>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L115)

### operationIdTimestamp

Extracts a UUIDv7 timestamp without validating the ID.

**Example**

```ts
operationIdTimestamp(id);
```

**Signature**

```ts
declare const operationIdTimestamp: (value: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L56)

### operationIdTimestampEffect

Extracts the first 48 timestamp bits without validating UUID syntax.

**Example**

```ts
Effect.runSync(operationIdTimestampEffect(id));
```

**Signature**

```ts
declare const operationIdTimestampEffect: (value: string) => Effect.Effect<number, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L45)

### parseOperationId

Parses a UUIDv7 operation ID through the compatibility API.

**Throws**

OperationIdError for an invalid or expired ID.

**Example**

```ts
parseOperationId(id, { now: Date.now() });
```

**Signature**

```ts
declare const parseOperationId: (value: string, options?: ParseOperationIdOptions) => OperationId;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L101)

### parseOperationIdEffect

Parses a UUIDv7 operation ID and enforces its receipt window.

**Example**

```ts
Effect.runSync(parseOperationIdEffect(id, { now: Date.now() }));
```

**Signature**

```ts
declare const parseOperationIdEffect: (
  value: string,
  options?: ParseOperationIdOptions | undefined,
) => Effect.Effect<OperationId, OperationIdFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.ts#L65)

## `operation-id.types.ts`

### OperationIdEntropyService (interface)

Injectable source of UUIDv7 random bytes.

**Example**

```ts
const source: OperationIdEntropyService = { bytes: () => Effect.succeed(new Uint8Array(16)) };
```

**Signature**

```ts
export interface OperationIdEntropyService {
  /** Produces sixteen independent bytes.
   * @returns An Effect of random bytes without a typed failure.
   * @example Effect.runSync(source.bytes());
   */
  readonly bytes: () => Effect.Effect<Uint8Array>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.types.ts#L14)

### ParseOperationIdOptions (interface)

Optional receipt-window clock controls for ID parsing.

**Example**

```ts
const options: ParseOperationIdOptions = { now: Date.now(), receiptWindowMs: 60000 };
```

**Signature**

```ts
export interface ParseOperationIdOptions {
  readonly now?: number;
  readonly receiptWindowMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/operation-id.types.ts#L6)

## `provider-dispatcher.ts`

### "./provider-dispatcher.types.js" (namespace export)

Re-exports all named exports from the "./provider-dispatcher.types.js" module.

**Signature**

```ts
export * from "./provider-dispatcher.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L13)

### RealtimeProviderSource (class)

Injectable profile-to-provider lookup.

**Example**

```ts
Effect.provide(triggerProviderEffect(options, request), providerSourceLayer(options));
```

**Signature**

```ts
declare class RealtimeProviderSource
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L18)

### createProviderRealtimeDispatcher

Creates a provider-backed realtime dispatcher.

**Throws**

An Effect runtime defect if construction cannot execute synchronously.

**Example**

```ts
const dispatcher = createProviderRealtimeDispatcher(options);
```

**Signature**

```ts
declare const createProviderRealtimeDispatcher: (
  options: ProviderRealtimeDispatcherOptions,
) => RealtimeDispatcher;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L195)

### createProviderRealtimeDispatcherEffect

Creates the compatibility dispatcher through the Effect path.

**Example**

```ts
Effect.runSync(createProviderRealtimeDispatcherEffect(options));
```

**Signature**

```ts
declare const createProviderRealtimeDispatcherEffect: (
  options: ProviderRealtimeDispatcherOptions,
) => Effect.Effect<RealtimeDispatcher, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L172)

### limitsForEffect

**Signature**

```ts
declare const limitsForEffect: (
  options: ProviderRealtimeDispatcherOptions,
) => Effect.Effect<RealtimeLimits, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L14)

### providerSourceLayer

Builds a provider resolver layer from authored dispatcher options.

**Example**

```ts
providerSourceLayer(options);
```

**Signature**

```ts
declare const providerSourceLayer: (
  options: ProviderRealtimeDispatcherOptions,
) => Layer.Layer<RealtimeProviderSource, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L27)

### readProviderPresenceEffect

Reads presence from a resolved provider.

**Example**

```ts
Effect.runPromise(
  Effect.provide(readProviderPresenceEffect(options, request), providerSourceLayer(options)),
);
```

**Signature**

```ts
declare const readProviderPresenceEffect: (
  options: ProviderRealtimeDispatcherOptions,
  request: { readonly channel: ChannelDescriptorData; readonly params: unknown },
) => Effect.Effect<PresenceSnapshot, RealtimeProviderError, RealtimeProviderSource>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L130)

### triggerProviderEffect

Sends a validated trigger to a resolved provider.

**Example**

```ts
Effect.runPromise(
  Effect.provide(triggerProviderEffect(options, request), providerSourceLayer(options)),
);
```

**Signature**

```ts
declare const triggerProviderEffect: (
  options: ProviderRealtimeDispatcherOptions,
  request: {
    readonly channel: ChannelDescriptorData;
    readonly params: unknown;
    readonly event: string;
    readonly payload: unknown;
    readonly options?: ChannelTriggerOptions;
  },
) => Effect.Effect<
  TriggerReceipt,
  RealtimeProviderError | OperationIdFailure,
  RealtimeProviderSource
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.ts#L66)

## `provider-dispatcher.types.ts`

### ProviderRealtimeDispatcherOptions (interface)

Configuration for a provider-backed generation dispatcher.

**Example**

```ts
const options: ProviderRealtimeDispatcherOptions = {
  applicationId: "app",
  environment: "dev",
  generationId: "g1",
  publicFingerprint: "p1",
  provider: async () => provider,
};
```

**Signature**

```ts
export interface ProviderRealtimeDispatcherOptions {
  readonly applicationId: string;
  readonly environment: string;
  readonly generationId: string;
  readonly publicFingerprint: string;
  /** Resolves a provider for one profile.
   * @param profile - Validated profile name.
   * @param signal - Optional cancellation signal for an in-flight lookup.
   * @returns A provider or lookup rejection.
   * @example await options.provider("default", controller.signal);
   */
  readonly provider: (
    profile: string,
    signal?: AbortSignal,
  ) => Promise<RealtimeProvider> | RealtimeProvider;
  readonly limits?: Partial<RealtimeLimits>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.types.ts#L8)

### RealtimeProviderSourceService (interface)

Injectable provider resolver used by Effect-native dispatcher operations.

**Example**

```ts
const source: RealtimeProviderSourceService = { resolve: () => Effect.succeed(provider) };
```

**Signature**

```ts
export interface RealtimeProviderSourceService {
  /** Resolves the provider configured for one profile.
   * @param profile - Validated profile name.
   * @returns An Effect of the provider or RealtimeProviderError.
   * @example Effect.runPromise(source.resolve("default"));
   */
  readonly resolve: (profile: string) => Effect.Effect<RealtimeProvider, RealtimeProviderError>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-dispatcher.types.ts#L29)

## `provider-encoding.ts`

### digestEffect

Hashes canonical JSON for partitions and idempotency.

**Example**

```ts
Effect.runSync(digestEffect({ id: "one" }));
```

**Signature**

```ts
declare const digestEffect: (value: unknown) => Effect.Effect<string, RealtimeProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-encoding.ts#L12)

### encodedBytesEffect

Measures an encoded event envelope.

**Example**

```ts
Effect.runSync(encodedBytesEffect({ event: "posted" }));
```

**Signature**

```ts
declare const encodedBytesEffect: (
  value: unknown,
) => Effect.Effect<number, RealtimeProviderError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-encoding.ts#L26)

### providerScopeEffect

Computes the immutable portion of a provider scope.

**Example**

```ts
Effect.runSync(providerScopeEffect(options, "news", "default", {}));
```

**Signature**

```ts
declare const providerScopeEffect: (
  options: ProviderRealtimeDispatcherOptions,
  channelId: string,
  profile: string,
  params: unknown,
) => Effect.Effect<
  {
    applicationId: string;
    environment: string;
    channelId: string;
    partition: string;
    profile: string;
    policyEpoch: string;
    providerEpoch: string;
    identityScope: string;
    sessionEpoch: string;
  },
  RealtimeProviderError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-encoding.ts#L43)

## `provider-limits.ts`

### limitsForEffect

Computes effective provider limits in the Effect path.

**Example**

```ts
Effect.runSync(limitsForEffect(options));
```

**Signature**

```ts
declare const limitsForEffect: (
  options: ProviderRealtimeDispatcherOptions,
) => Effect.Effect<RealtimeLimits, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider-limits.ts#L11)

## `provider.ts`

### "./provider.types.js" (namespace export)

Re-exports all named exports from the "./provider.types.js" module.

**Signature**

```ts
export * from "./provider.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.ts#L1)

## `provider.types.ts`

### AcquirePresenceLease (type alias)

Initial lease request.

**Example**

```ts
const request: AcquirePresenceLease = lease;
```

**Signature**

```ts
type AcquirePresenceLease = PresenceLeaseRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L102)

### AppendChannelEvent (interface)

Validated event append request including idempotency and retention settings.

**Example**

```ts
const append: AppendChannelEvent = {
  ...scope,
  event: "posted",
  payload: "hi",
  encodedBytes: 42,
  occurredAt: new Date().toISOString(),
  limits,
};
```

**Signature**

```ts
export interface AppendChannelEvent extends RealtimeScope {
  readonly operationId?: OperationId;
  readonly semanticDigest?: string;
  readonly event: string;
  readonly payload: unknown;
  readonly encodedBytes: number;
  readonly occurredAt: string;
  readonly receiptExpiresAt?: string;
  readonly retentionMs?: number;
  readonly maxEvents?: number;
  readonly limits: RealtimeLimits;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L24)

### AppendReceiptLookup (type alias)

Provider receipt lookup result.

**Example**

```ts
const result: AppendReceiptLookup = await provider.lookupAppendReceipt(lookup);
```

**Signature**

```ts
type AppendReceiptLookup = ReceiptLookup<TriggerReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L50)

### ChannelEventPage (interface)

Ordered provider replay page and its next checkpoint.

**Example**

```ts
const page: ChannelEventPage = await provider.readAfter(read);
```

**Signature**

```ts
export interface ChannelEventPage {
  readonly events: readonly ChannelEventRecord[];
  readonly checkpoint: ChannelCheckpoint;
  readonly hasMore: boolean;
  readonly gap?: "expired" | "foreign" | "future" | "policy" | "session" | "provider-reset";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L64)

### LookupAppendReceipt (interface)

Provider lookup for an existing idempotent append receipt.

**Example**

```ts
const lookup: LookupAppendReceipt = {
  ...scope,
  operationId: id,
  semanticDigest: digest,
  receiptWindowMs: 60000,
  now: new Date().toISOString(),
};
```

**Signature**

```ts
export interface LookupAppendReceipt extends RealtimeScope {
  readonly operationId: OperationId;
  readonly semanticDigest: string;
  readonly receiptWindowMs: number;
  readonly now: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L40)

### PresenceLeaseRequest (interface)

Presence lease mutation request; providers own lease persistence.

**Example**

```ts
const lease: PresenceLeaseRequest = {
  ...scope,
  leaseId: "l1",
  connectionId: "c1",
  expiresAt: new Date().toISOString(),
  maxMembers: 10,
  maxConnections: 10,
};
```

**Signature**

```ts
export interface PresenceLeaseRequest extends RealtimeScope {
  readonly leaseId: string;
  readonly connectionId: string;
  readonly opaqueMemberId?: string;
  readonly memberInfo?: unknown;
  readonly expiresAt: string;
  readonly maxMembers: number;
  readonly maxConnections: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L83)

### ReadChannelEvents (interface)

Bounded replay page request.

**Example**

```ts
const read: ReadChannelEvents = { ...scope, limit: 10, maxEncodedBytes: 4096 };
```

**Signature**

```ts
export interface ReadChannelEvents extends RealtimeScope {
  readonly after?: ChannelCheckpoint;
  readonly limit: number;
  readonly maxEncodedBytes: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L55)

### ReadPresenceRequest (type alias)

Presence read with a bounded member count.

**Example**

```ts
const read: ReadPresenceRequest = { ...scope, maxMembers: 10 };
```

**Signature**

```ts
type ReadPresenceRequest = RealtimeScope & {
  readonly maxMembers: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L96)

### RealtimeLimits (interface)

Provider-enforced bounds for event, connection, partition, and presence storage.

**Example**

```ts
const limits: RealtimeLimits = {
  maxEventBytes: 1024,
  maxRetainedBytes: 4096,
  maxPartitions: 10,
  maxConnections: 10,
  maxPresenceMembers: 10,
};
```

**Signature**

```ts
export interface RealtimeLimits {
  readonly maxEventBytes: number;
  readonly maxRetainedBytes: number;
  readonly maxPartitions: number;
  readonly maxConnections: number;
  readonly maxPresenceMembers: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L13)

### RealtimeProvider (interface)

Backend contract for ordered events, idempotency, and presence.
The caller owns aborting waitAfter; provider implementations own their internal resources.

**Example**

```ts
const epoch = await provider.getEpoch();
```

**Signature**

```ts
export interface RealtimeProvider {
  readonly capabilities: {
    readonly replay: "memory" | "retained";
    readonly presenceScope: "process" | "shared";
    readonly durability: "volatile" | "filesystem" | "redis-configured";
  };
  /** Reads the provider generation epoch.
   * @param signal - Optional cancellation signal for in-flight work.
   * @returns The epoch or a provider rejection.
   * @example await provider.getEpoch();
   */
  getEpoch(signal?: AbortSignal): Promise<string>;
  /** Appends a validated event.
   * @param request - Event and scope metadata.
   * @param signal - Optional cancellation signal; an implementation may already have committed an append when aborted.
   * @returns A receipt or a provider rejection.
   * @example await provider.append(append);
   */
  append(request: AppendChannelEvent, signal?: AbortSignal): Promise<TriggerReceipt>;
  /** Looks up an idempotent append receipt.
   * @param request - Receipt lookup key and time window.
   * @returns Existing receipt state or a provider rejection.
   * @example await provider.lookupAppendReceipt(lookup);
   */
  lookupAppendReceipt(request: LookupAppendReceipt): Promise<AppendReceiptLookup>;
  /** Reads an ordered, bounded event page.
   * @param request - Replay cursor and limits.
   * @returns A page or a provider rejection.
   * @example await provider.readAfter(read);
   */
  readAfter(request: ReadChannelEvents): Promise<ChannelEventPage>;
  /** Waits for events until a deadline or caller abort.
   * @param request - Cursor, deadline, and caller-owned abort signal.
   * @returns Completion or a provider rejection.
   * @example await provider.waitAfter(wait);
   */
  waitAfter(request: WaitForChannelEvents): Promise<void>;
  /** Reads current presence.
   * @param request - Scope and member limit.
   * @param signal - Optional cancellation signal for in-flight work.
   * @returns Presence snapshot or a provider rejection.
   * @example await provider.readPresence(read);
   */
  readPresence(request: ReadPresenceRequest, signal?: AbortSignal): Promise<PresenceSnapshot>;
  /** Acquires a presence lease.
   * @param request - Lease identity, expiry, and limits.
   * @returns Updated presence or a provider rejection.
   * @example await provider.acquirePresence(lease);
   */
  acquirePresence(request: AcquirePresenceLease): Promise<PresenceSnapshot>;
  /** Renews a presence lease.
   * @param request - Existing lease and next expiry.
   * @returns Updated presence or a provider rejection.
   * @example await provider.renewPresence(lease);
   */
  renewPresence(request: RenewPresenceLease): Promise<PresenceSnapshot>;
  /** Releases a presence lease.
   * @param request - Existing lease without expiry.
   * @returns Updated presence or a provider rejection.
   * @example await provider.releasePresence(release);
   */
  releasePresence(request: ReleasePresenceLease): Promise<PresenceSnapshot>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L116)

### ReleasePresenceLease (type alias)

Lease release request without an expiry.

**Example**

```ts
const request: ReleasePresenceLease = {
  ...scope,
  leaseId: "l1",
  connectionId: "c1",
  maxMembers: 10,
  maxConnections: 10,
};
```

**Signature**

```ts
type ReleasePresenceLease = Omit<PresenceLeaseRequest, "expiresAt">;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L110)

### RenewPresenceLease (type alias)

Existing lease renewal request.

**Example**

```ts
const request: RenewPresenceLease = lease;
```

**Signature**

```ts
type RenewPresenceLease = PresenceLeaseRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L106)

### WaitForChannelEvents (interface)

Abortable long-poll request owned by its caller.

**Example**

```ts
const wait: WaitForChannelEvents = {
  ...scope,
  after: checkpoint,
  deadlineMs: Date.now() + 1000,
  signal: controller.signal,
};
```

**Signature**

```ts
export interface WaitForChannelEvents extends RealtimeScope {
  readonly after: ChannelCheckpoint;
  readonly deadlineMs: number;
  readonly signal: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/provider.types.ts#L74)

## `realtime-errors.ts`

### ChannelValidationError (class)

Invalid authored channel data or an invalid channel operation.

**Example**

```ts
new ChannelValidationError({ operation: "channel.define", reason: "Missing events" });
```

**Signature**

```ts
declare class ChannelValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-errors.ts#L5)

### OperationIdFailure (class)

An operation ID is malformed or outside its receipt window.

**Example**

```ts
new OperationIdFailure({ code: "OPERATION_ID_INVALID", reason: "Invalid ID" });
```

**Signature**

```ts
declare class OperationIdFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-errors.ts#L33)

### RealtimeActionError (class)

An action thrown while entering a dispatcher scope.

**Example**

```ts
new RealtimeActionError({ operation: "dispatch.runWith", cause: new Error("failed") });
```

**Signature**

```ts
declare class RealtimeActionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-errors.ts#L19)

### RealtimeDispatcherError (class)

A realtime dispatcher was required but none was bound.

**Example**

```ts
new RealtimeDispatcherError({
  operation: "dispatch.current",
  reason: "No realtime dispatcher is active.",
});
```

**Signature**

```ts
declare class RealtimeDispatcherError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-errors.ts#L12)

### RealtimeProviderError (class)

A provider operation failed at the external adapter boundary.

**Example**

```ts
new RealtimeProviderError({ operation: "provider.trigger", cause: new Error("offline") });
```

**Signature**

```ts
declare class RealtimeProviderError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-errors.ts#L26)

## `realtime-observability.ts`

### RealtimeTelemetry (class)

Injectable realtime telemetry boundary.

**Example**

```ts
Effect.provide(Effect.succeed(1), RealtimeTelemetryLive);
```

**Signature**

```ts
declare class RealtimeTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-observability.ts#L9)

### RealtimeTelemetryLive

Live span and metric observer for realtime operations.

**Example**

```ts
Effect.provide(Effect.succeed(1), RealtimeTelemetryLive);
```

**Signature**

```ts
declare const RealtimeTelemetryLive: Layer.Layer<RealtimeTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-observability.ts#L16)

### observeRealtime

Observes a realtime operation using the supplied test service or live metrics.

**Example**

```ts
observeRealtime("channel.define", Effect.succeed(undefined));
```

**Signature**

```ts
declare const observeRealtime: <A, E, R>(
  operation: RealtimeOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-observability.ts#L28)

## `realtime-observability.types.ts`

### RealtimeOperation (type alias)

Bounded names used for realtime spans and metrics.

**Example**

```ts
const operation: RealtimeOperation = "channel.define";
```

**Signature**

```ts
type RealtimeOperation =
  | "channel.define"
  | "channel.isDescriptor"
  | "channel.trigger"
  | "channel.getPresence"
  | "channel.copyClient"
  | "channel.copyPresence"
  | "channel.copyEvents"
  | "channel.copyReplay"
  | "channel.assertSchema"
  | "channel.isSchema"
  | "channel.validateValue"
  | "channel.isRecord"
  | "dispatch.setActive"
  | "dispatch.runWith"
  | "dispatch.current"
  | "operationId.parse"
  | "operationId.timestamp"
  | "operationId.create"
  | "provider.createDispatcher"
  | "provider.resolve"
  | "provider.trigger"
  | "provider.getPresence"
  | "provider.scope"
  | "provider.digest"
  | "provider.bytes"
  | "provider.limits";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-observability.types.ts#L5)

### RealtimeTelemetryService (interface)

Substitutable observer for realtime operation tests and application telemetry.

**Example**

```ts
const observer: RealtimeTelemetryService = { observe: (_name, effect) => effect };
```

**Signature**

```ts
export interface RealtimeTelemetryService {
  /** Surrounds an operation without changing its result.
   * @param operation - A stable, bounded operation name.
   * @param effect - The operation to observe.
   * @returns The same success and error channels with telemetry attached.
   * @example observer.observe("channel.define", Effect.succeed(undefined));
   */
  readonly observe: <A, E, R>(
    operation: RealtimeOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/realtime-observability.types.ts#L35)

## `types.ts`

### ChannelCheckpoint (interface)

Replay cursor bound to the provider, policy, and session epochs.

**Example**

```ts
const checkpoint: ChannelCheckpoint = {
  ...scope,
  sequence: "1",
  historyStart: "1",
  expiresAt: new Date().toISOString(),
};
```

**Signature**

```ts
export interface ChannelCheckpoint extends RealtimeScope {
  readonly sequence: string;
  readonly historyStart: string;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L20)

### ChannelEventRecord (interface)

Stored channel event and checkpoint returned by replay.

**Example**

```ts
const record: ChannelEventRecord = {
  eventId: "e1",
  event: "posted",
  payload: "hi",
  checkpoint,
  encodedBytes: 20,
  createdAt: new Date().toISOString(),
};
```

**Signature**

```ts
export interface ChannelEventRecord {
  readonly eventId: string;
  readonly event: string;
  readonly payload: unknown;
  readonly checkpoint: ChannelCheckpoint;
  readonly encodedBytes: number;
  readonly createdAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L39)

### ChannelGrant (interface)

Authorized channel grant with a bounded replay window.

**Example**

```ts
const grant: ChannelGrant = {
  ...scope,
  grantId: "g",
  principalScope: "user",
  historyStart: "1",
  expiresAt: new Date().toISOString(),
};
```

**Signature**

```ts
export interface ChannelGrant extends RealtimeScope {
  readonly grantId: string;
  readonly principalScope: string;
  readonly historyStart: string;
  readonly expiresAt: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L29)

### CountPresence (interface)

Count-only presence snapshot and freshness state.

**Example**

```ts
const count: CountPresence = { connections: 1, status: "fresh", revision: "1", scope: "shared" };
```

**Signature**

```ts
export interface CountPresence {
  readonly connections: number | undefined;
  readonly status: "loading" | "fresh" | "stale" | "error";
  readonly revision: string | undefined;
  readonly scope: "process" | "shared";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L64)

### MemberPresence (interface)

Presence snapshot with a bounded member list.

**Example**

```ts
const members: MemberPresence<string> = {
  connections: 1,
  status: "fresh",
  revision: "1",
  scope: "shared",
  memberCount: 1,
  members: [{ id: "opaque", info: "Ada" }],
  membersTruncated: false,
};
```

**Signature**

```ts
export interface MemberPresence<Member = unknown> extends CountPresence {
  readonly memberCount: number | undefined;
  readonly members: readonly PresenceMember<Member>[];
  readonly membersTruncated: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L82)

### PresenceMember (interface)

Member identity and validated application-visible information.

**Example**

```ts
const member: PresenceMember<string> = { id: "opaque", info: "Ada" };
```

**Signature**

```ts
export interface PresenceMember<Member = unknown> {
  readonly id: string;
  readonly info: Member;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L74)

### PresenceSnapshot (type alias)

Count-only or member presence returned by a provider.

**Example**

```ts
const snapshot: PresenceSnapshot = await provider.readPresence(read);
```

**Signature**

```ts
type PresenceSnapshot<Member = unknown> = CountPresence | MemberPresence<Member>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L91)

### RealtimeScope (interface)

Identity and partition coordinates shared by all realtime provider requests.

**Example**

```ts
const scope: RealtimeScope = {
  applicationId: "app",
  environment: "dev",
  channelId: "news",
  partition: "p",
  profile: "default",
  policyEpoch: "v1",
  providerEpoch: "e1",
  identityScope: "public",
  sessionEpoch: "s1",
};
```

**Signature**

```ts
export interface RealtimeScope extends ExpectedClientIdentity {
  readonly applicationId: string;
  readonly environment: string;
  readonly tenantScope?: string;
  readonly channelId: string;
  readonly partition: string;
  readonly profile: string;
  readonly policyEpoch: string;
  readonly providerEpoch: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L6)

### TriggerReceipt (interface)

Provider acknowledgement for an accepted channel event.

**Example**

```ts
const receipt: TriggerReceipt = await channel.trigger({}, "posted", "hi");
```

**Signature**

```ts
export interface TriggerReceipt {
  readonly accepted: true;
  readonly operationId?: OperationId;
  readonly eventId: string;
  readonly checkpoint: ChannelCheckpoint;
  readonly profile: string;
  readonly providerEpoch: string;
  readonly duplicate: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/realtime/src/types.ts#L51)

---

# CLI launcher API
Source: https://relkit.dev/docs/api/relkit

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

For configuration and examples, read [automation](/docs/modules/cli/automation).

## Public imports

- `relkit` — 2 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                     | Kind  | Import from | Example                                        |
| ------------------------------------------------------- | ----- | ----------- | ---------------------------------------------- |
| [main](/docs/api/relkit#main)                           | Value | `relkit`    | [Module example](/docs/modules/cli/automation) |
| [resolveProjectCli](/docs/api/relkit#resolveprojectcli) | Value | `relkit`    | [Module example](/docs/modules/cli/automation) |

## `index.ts`

Lightweight launcher: create directly, or execute the compatible project-owned CLI.

### main

Launches one selected entry under Bun, preserving the child's terminal output.

**Signature**

```ts
declare const main: (argv?: readonly string[], cwd?: string) => Promise<number>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/relkit/src/index.ts#L48)

### resolveProjectCli

Resolves only the installed CLI declared by the nearest project manifest.

**Signature**

```ts
declare const resolveProjectCli: (cwd: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/relkit/src/index.ts#L15)

---

# Routes API
Source: https://relkit.dev/docs/api/routes

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineRoute](/docs/api/routes#defineroute)
- [defineMiddleware](/docs/api/routes#definemiddleware)

For configuration and examples, read [define](/docs/modules/http/define), [middleware](/docs/modules/http/middleware), [routes](/docs/modules/service/routes).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images), [connect react](/guides/frontend/connect-react), [register users in a transaction](/guides/database/register-users-in-a-transaction), [email password sign in](/guides/auth/email-password-sign-in), [create and build an api](/guides/cli/create-and-build-an-api).

## Frontend usage

[Call a defined route](/docs/modules/http/define#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/routes` — 91 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                | Kind  | Import from      | Example                                                                                                               |
| ---------------------------------------------------------------------------------- | ----- | ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| [assertRequestMapping](/docs/api/routes#assertrequestmapping)                      | Value | `@relkit/routes` | [API example](/docs/api/routes#assertrequestmapping)                                                                  |
| [assertRequestMappingEffect](/docs/api/routes#assertrequestmappingeffect)          | Value | `@relkit/routes` | [API example](/docs/api/routes#assertrequestmappingeffect)                                                            |
| [assertResponse](/docs/api/routes#assertresponse)                                  | Value | `@relkit/routes` | [API example](/docs/api/routes#assertresponse)                                                                        |
| [assertResponseEffect](/docs/api/routes#assertresponseeffect)                      | Value | `@relkit/routes` | [API example](/docs/api/routes#assertresponseeffect)                                                                  |
| [ContinueMapping](/docs/api/routes#continuemapping-interface)                      | Type  | `@relkit/routes` | [API example](/docs/api/routes#continuemapping-interface)                                                             |
| [defineMiddleware](/docs/api/routes#definemiddleware)                              | Value | `@relkit/routes` | [API example](/docs/api/routes#definemiddleware)                                                                      |
| [defineMiddlewareEffect](/docs/api/routes#definemiddlewareeffect)                  | Value | `@relkit/routes` | [API example](/docs/api/routes#definemiddlewareeffect)                                                                |
| [defineRequestTransform](/docs/api/routes#definerequesttransform)                  | Value | `@relkit/routes` | [API example](/docs/api/routes#definerequesttransform)                                                                |
| [defineRequestTransformEffect](/docs/api/routes#definerequesttransformeffect)      | Value | `@relkit/routes` | [API example](/docs/api/routes#definerequesttransformeffect)                                                          |
| [defineRoute](/docs/api/routes#defineroute)                                        | Value | `@relkit/routes` | [API example](/docs/api/routes#defineroute)                                                                           |
| [defineRouteEffect](/docs/api/routes#definerouteeffect)                            | Value | `@relkit/routes` | [API example](/docs/api/routes#definerouteeffect)                                                                     |
| [defineServiceRoutes](/docs/api/routes#defineserviceroutes)                        | Value | `@relkit/routes` | [API example](/docs/api/routes#defineserviceroutes)                                                                   |
| [defineServiceRoutesEffect](/docs/api/routes#defineservicerouteseffect)            | Value | `@relkit/routes` | [API example](/docs/api/routes#defineservicerouteseffect)                                                             |
| [defineTransform](/docs/api/routes#definetransform)                                | Value | `@relkit/routes` | [API example](/docs/api/routes#definetransform)                                                                       |
| [defineTransformEffect](/docs/api/routes#definetransformeffect)                    | Value | `@relkit/routes` | [API example](/docs/api/routes#definetransformeffect)                                                                 |
| [DefineTransformOptions](/docs/api/routes#definetransformoptions-interface)        | Type  | `@relkit/routes` | [API example](/docs/api/routes#definetransformoptions-interface)                                                      |
| [FunctionRouteDescriptor](/docs/api/routes#functionroutedescriptor-interface)      | Type  | `@relkit/routes` | [API example](/docs/api/routes#functionroutedescriptor-interface)                                                     |
| [FunctionRouteOptions](/docs/api/routes#functionrouteoptions-interface)            | Type  | `@relkit/routes` | [API example](/docs/api/routes#functionrouteoptions-interface)                                                        |
| [http](/docs/api/routes#http)                                                      | Value | `@relkit/routes` | [API example](/docs/api/routes#http)                                                                                  |
| [HttpBodyMapping](/docs/api/routes#httpbodymapping-interface)                      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpbodymapping-interface)                                                             |
| [HttpConstantMapping](/docs/api/routes#httpconstantmapping-interface)              | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpconstantmapping-interface)                                                         |
| [HttpCookieMapping](/docs/api/routes#httpcookiemapping-interface)                  | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpcookiemapping-interface)                                                           |
| [HttpDefaultMapping](/docs/api/routes#httpdefaultmapping-interface)                | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpdefaultmapping-interface)                                                          |
| [HttpDsl](/docs/api/routes#httpdsl-interface)                                      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpdsl-interface)                                                                     |
| [httpEffects](/docs/api/routes#httpeffects)                                        | Value | `@relkit/routes` | [API example](/docs/api/routes#httpeffects)                                                                           |
| [HttpHeaderMapping](/docs/api/routes#httpheadermapping-interface)                  | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpheadermapping-interface)                                                           |
| [HttpInputMapping](/docs/api/routes#httpinputmapping-interface)                    | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpinputmapping-interface)                                                            |
| [HttpMapping](/docs/api/routes#httpmapping-interface)                              | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmapping-interface)                                                                 |
| [HttpMappingNode](/docs/api/routes#httpmappingnode-type-alias)                     | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmappingnode-type-alias)                                                            |
| [HttpMappingOutput](/docs/api/routes#httpmappingoutput-type-alias)                 | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmappingoutput-type-alias)                                                          |
| [HttpMappingShape](/docs/api/routes#httpmappingshape-type-alias)                   | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmappingshape-type-alias)                                                           |
| [HttpMethod](/docs/api/routes#httpmethod-type-alias)                               | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmethod-type-alias)                                                                 |
| [HttpMultipartAllMapping](/docs/api/routes#httpmultipartallmapping-interface)      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmultipartallmapping-interface)                                                     |
| [HttpMultipartMapping](/docs/api/routes#httpmultipartmapping-interface)            | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpmultipartmapping-interface)                                                        |
| [HttpNestedMapping](/docs/api/routes#httpnestedmapping-interface)                  | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpnestedmapping-interface)                                                           |
| [HttpOptionalMapping](/docs/api/routes#httpoptionalmapping-interface)              | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpoptionalmapping-interface)                                                         |
| [HttpPathMapping](/docs/api/routes#httppathmapping-interface)                      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httppathmapping-interface)                                                             |
| [HttpPathSegmentsMapping](/docs/api/routes#httppathsegmentsmapping-interface)      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httppathsegmentsmapping-interface)                                                     |
| [HttpQueryMapping](/docs/api/routes#httpquerymapping-interface)                    | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpquerymapping-interface)                                                            |
| [HttpRateLimitKey](/docs/api/routes#httpratelimitkey-type-alias)                   | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpratelimitkey-type-alias)                                                           |
| [HttpRequestContentType](/docs/api/routes#httprequestcontenttype-type-alias)       | Type  | `@relkit/routes` | [API example](/docs/api/routes#httprequestcontenttype-type-alias)                                                     |
| [HttpRequestMapping](/docs/api/routes#httprequestmapping-type-alias)               | Type  | `@relkit/routes` | [API example](/docs/api/routes#httprequestmapping-type-alias)                                                         |
| [HttpResponseMapping](/docs/api/routes#httpresponsemapping-interface)              | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpresponsemapping-interface)                                                         |
| [HttpSourceOptions](/docs/api/routes#httpsourceoptions-interface)                  | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpsourceoptions-interface)                                                           |
| [HttpTransformDescriptor](/docs/api/routes#httptransformdescriptor-interface)      | Type  | `@relkit/routes` | [API example](/docs/api/routes#httptransformdescriptor-interface)                                                     |
| [HttpTransformMapping](/docs/api/routes#httptransformmapping-interface)            | Type  | `@relkit/routes` | [API example](/docs/api/routes#httptransformmapping-interface)                                                        |
| [HttpTransformRef](/docs/api/routes#httptransformref-interface)                    | Type  | `@relkit/routes` | [API example](/docs/api/routes#httptransformref-interface)                                                            |
| [HttpWholeBodyMapping](/docs/api/routes#httpwholebodymapping-interface)            | Type  | `@relkit/routes` | [API example](/docs/api/routes#httpwholebodymapping-interface)                                                        |
| [isHttpMapping](/docs/api/routes#ishttpmapping)                                    | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttpmapping)                                                                         |
| [isHttpMappingEffect](/docs/api/routes#ishttpmappingeffect)                        | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttpmappingeffect)                                                                   |
| [isHttpRequestMapping](/docs/api/routes#ishttprequestmapping)                      | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttprequestmapping)                                                                  |
| [isHttpRequestMappingEffect](/docs/api/routes#ishttprequestmappingeffect)          | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttprequestmappingeffect)                                                            |
| [isHttpResponseMapping](/docs/api/routes#ishttpresponsemapping)                    | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttpresponsemapping)                                                                 |
| [isHttpResponseMappingEffect](/docs/api/routes#ishttpresponsemappingeffect)        | Value | `@relkit/routes` | [API example](/docs/api/routes#ishttpresponsemappingeffect)                                                           |
| [isMiddlewareDecision](/docs/api/routes#ismiddlewaredecision)                      | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewaredecision)                                                                  |
| [isMiddlewareDecisionEffect](/docs/api/routes#ismiddlewaredecisioneffect)          | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewaredecisioneffect)                                                            |
| [isMiddlewareDescriptor](/docs/api/routes#ismiddlewaredescriptor)                  | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewaredescriptor)                                                                |
| [isMiddlewareDescriptorEffect](/docs/api/routes#ismiddlewaredescriptoreffect)      | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewaredescriptoreffect)                                                          |
| [isMiddlewarePath](/docs/api/routes#ismiddlewarepath)                              | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewarepath)                                                                      |
| [isMiddlewarePathEffect](/docs/api/routes#ismiddlewarepatheffect)                  | Value | `@relkit/routes` | [API example](/docs/api/routes#ismiddlewarepatheffect)                                                                |
| [isTransformRef](/docs/api/routes#istransformref)                                  | Value | `@relkit/routes` | [API example](/docs/api/routes#istransformref)                                                                        |
| [isTransformRefEffect](/docs/api/routes#istransformrefeffect)                      | Value | `@relkit/routes` | [API example](/docs/api/routes#istransformrefeffect)                                                                  |
| [MappingShapeOutput](/docs/api/routes#mappingshapeoutput-type-alias)               | Type  | `@relkit/routes` | [API example](/docs/api/routes#mappingshapeoutput-type-alias)                                                         |
| [MiddlewareContext](/docs/api/routes#middlewarecontext-interface)                  | Type  | `@relkit/routes` | [API example](/docs/api/routes#middlewarecontext-interface)                                                           |
| [MiddlewareDecisionMapping](/docs/api/routes#middlewaredecisionmapping-type-alias) | Type  | `@relkit/routes` | [API example](/docs/api/routes#middlewaredecisionmapping-type-alias)                                                  |
| [MiddlewareDescriptor](/docs/api/routes#middlewaredescriptor-interface)            | Type  | `@relkit/routes` | [API example](/docs/api/routes#middlewaredescriptor-interface)                                                        |
| [MiddlewareHandler](/docs/api/routes#middlewarehandler-type-alias)                 | Type  | `@relkit/routes` | [API example](/docs/api/routes#middlewarehandler-type-alias)                                                          |
| [NativeStreamFormat](/docs/api/routes#nativestreamformat-type-alias)               | Type  | `@relkit/routes` | [API example](/docs/api/routes#nativestreamformat-type-alias)                                                         |
| [RawHttpHandler](/docs/api/routes#rawhttphandler-type-alias)                       | Type  | `@relkit/routes` | [API example](/docs/api/routes#rawhttphandler-type-alias)                                                             |
| [RawRouteDescriptor](/docs/api/routes#rawroutedescriptor-interface)                | Type  | `@relkit/routes` | [API example](/docs/api/routes#rawroutedescriptor-interface)                                                          |
| [RawRouteOptions](/docs/api/routes#rawrouteoptions-interface)                      | Type  | `@relkit/routes` | [API example](/docs/api/routes#rawrouteoptions-interface)                                                             |
| [RespondMapping](/docs/api/routes#respondmapping-interface)                        | Type  | `@relkit/routes` | [API example](/docs/api/routes#respondmapping-interface)                                                              |
| [RouteClientPolicy](/docs/api/routes#routeclientpolicy-type-alias)                 | Type  | `@relkit/routes` | [API example](/docs/api/routes#routeclientpolicy-type-alias)                                                          |
| [RouteDescriptor](/docs/api/routes#routedescriptor-type-alias)                     | Type  | `@relkit/routes` | [API example](/docs/api/routes#routedescriptor-type-alias)                                                            |
| [RouteInputError](/docs/api/routes#routeinputerror-class)                          | Value | `@relkit/routes` | [API example](/docs/api/routes#routeinputerror-class)                                                                 |
| [RouteModuleContract](/docs/api/routes#routemodulecontract-type-alias)             | Type  | `@relkit/routes` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/route-modules.ts#L18)                        |
| [RouteModuleMethod](/docs/api/routes#routemodulemethod-type-alias)                 | Type  | `@relkit/routes` | [Module example](/docs/modules/http/define)                                                                           |
| [RouteOperation](/docs/api/routes#routeoperation-type-alias)                       | Type  | `@relkit/routes` | [API example](/docs/api/routes#routeoperation-type-alias)                                                             |
| [RouteOperationError](/docs/api/routes#routeoperationerror-class)                  | Value | `@relkit/routes` | [API example](/docs/api/routes#routeoperationerror-class)                                                             |
| [RouteRateLimit](/docs/api/routes#routeratelimit-interface)                        | Type  | `@relkit/routes` | [API example](/docs/api/routes#routeratelimit-interface)                                                              |
| [RouteTelemetry](/docs/api/routes#routetelemetry-class)                            | Value | `@relkit/routes` | [API example](/docs/api/routes#routetelemetry-class)                                                                  |
| [RouteTelemetryLive](/docs/api/routes#routetelemetrylive-1)                        | Value | `@relkit/routes` | [API example](/docs/api/routes#routetelemetrylive-1)                                                                  |
| [RouteTelemetryService](/docs/api/routes#routetelemetryservice-interface)          | Type  | `@relkit/routes` | [API example](/docs/api/routes#routetelemetryservice-interface)                                                       |
| [SERVICE_ROUTE_METHODS](/docs/api/routes#service_route_methods)                    | Value | `@relkit/routes` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/routes/tests/define-service-routes.test.ts#L26) |
| [ServiceRouteEntry](/docs/api/routes#servicerouteentry-type-alias)                 | Type  | `@relkit/routes` | [API example](/docs/api/routes#servicerouteentry-type-alias)                                                          |
| [ServiceRouteMethod](/docs/api/routes#serviceroutemethod-type-alias)               | Type  | `@relkit/routes` | [API example](/docs/api/routes#serviceroutemethod-type-alias)                                                         |
| [ServiceRouteOptions](/docs/api/routes#servicerouteoptions-type-alias)             | Type  | `@relkit/routes` | [API example](/docs/api/routes#servicerouteoptions-type-alias)                                                        |
| [ServiceRoutesOptions](/docs/api/routes#serviceroutesoptions-type-alias)           | Type  | `@relkit/routes` | [API example](/docs/api/routes#serviceroutesoptions-type-alias)                                                       |
| [ServiceRoutesResult](/docs/api/routes#serviceroutesresult-type-alias)             | Type  | `@relkit/routes` | [API example](/docs/api/routes#serviceroutesresult-type-alias)                                                        |
| [TransformOutput](/docs/api/routes#transformoutput-type-alias)                     | Type  | `@relkit/routes` | [API example](/docs/api/routes#transformoutput-type-alias)                                                            |
| [TransformReference](/docs/api/routes#transformreference-interface)                | Type  | `@relkit/routes` | [API example](/docs/api/routes#transformreference-interface)                                                          |

## `define-middleware.ts`

### defineMiddleware

Defines one automatically discovered path-scoped HTTP middleware handler.

**Throws**

TypeError for an invalid path or handler.

**Example**

```ts
import { defineMiddleware } from "@relkit/app/routes";

export default defineMiddleware("/orders/*", async (context, next) => {
  if (context.req.header("authorization") === undefined) {
    return context.json({ error: "unauthorized" }, 401);
  }
  await next();
});
```

**Signature**

```ts
declare const defineMiddleware: (
  path: string,
  handler: MiddlewareHandler,
) => MiddlewareDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L72)

Since v0.1.0

### MiddlewareContext

**Signature**

```ts
declare const MiddlewareContext: MiddlewareContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L15)

### MiddlewareDescriptor

**Signature**

```ts
declare const MiddlewareDescriptor: MiddlewareDescriptor<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L16)

### MiddlewareHandler

**Signature**

```ts
declare const MiddlewareHandler: MiddlewareHandler;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L17)

### defineMiddlewareEffect

Defines path-scoped middleware through a typed Effect.

**Example**

```ts
Effect.runSync(defineMiddlewareEffect("/orders/*", handler));
```

**Signature**

```ts
declare const defineMiddlewareEffect: (
  path: string,
  handler: MiddlewareHandler,
) => Effect.Effect<MiddlewareDescriptor<string>, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L26)

### isMiddlewareDescriptor

Checks a middleware descriptor synchronously.

**Example**

```ts
isMiddlewareDescriptor(value);
```

**Signature**

```ts
declare const isMiddlewareDescriptor: (value: unknown) => value is MiddlewareDescriptor;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L94)

### isMiddlewareDescriptorEffect

Checks a middleware descriptor through Effect.

**Example**

```ts
Effect.runSync(isMiddlewareDescriptorEffect(value));
```

**Signature**

```ts
declare const isMiddlewareDescriptorEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L84)

### isMiddlewarePath

Checks a middleware path synchronously.

**Example**

```ts
isMiddlewarePath("/orders/*");
```

**Signature**

```ts
declare const isMiddlewarePath: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L122)

### isMiddlewarePathEffect

Checks an HTTP middleware path through Effect.

**Example**

```ts
Effect.runSync(isMiddlewarePathEffect("/orders/*"));
```

**Signature**

```ts
declare const isMiddlewarePathEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.ts#L113)

## `define-middleware.types.ts`

### MiddlewareContext (interface)

Invocation-scoped capabilities provided to middleware.

**Example**

```ts
const context: MiddlewareContext = relkit;
```

**Signature**

```ts
export interface MiddlewareContext {
  readonly signal: AbortSignal;
  readonly env: ResolvedApplicationEnv;
  readonly auth: AuthContext;
  readonly log: PublicLogger;
  readonly time: PublicClock;
  readonly trace: PublicTrace;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.types.ts#L9)

### MiddlewareDescriptor (interface)

Frozen descriptor for one middleware handler.

**Example**

```ts
const descriptor: MiddlewareDescriptor = defineMiddleware("/orders", handler);
```

**Signature**

```ts
export interface MiddlewareDescriptor<Id extends string = string> extends DescriptorBase<
  "middleware",
  Id
> {
  readonly path: string;
  readonly handler: MiddlewareHandler;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.types.ts#L30)

### MiddlewareHandler (type alias)

A path-scoped HTTP middleware callback.

**Example**

```ts
const handler: MiddlewareHandler = async (_context, next) => next();
```

**Signature**

```ts
type MiddlewareHandler = (
  context: Context,
  next: Next,
  relkit: MiddlewareContext,
) => MaybePromise<Response | void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-middleware.types.ts#L21)

## `define-route.ts`

### defineRoute

Defines one HTTP method exported by a nested `route.ts` module.

The compiler derives the method from the named export and the path from the
file. Omit `id` for a source-derived route identity, and omit `request` and
`responses` when schema-based inference represents the transport; explicit
mappings replace inference completely. Matching path names map into reusable
function input.

**Throws**

TypeError for invalid authoring input.

**Example**

````ts
A GET route with inferred path and query input
```ts
import { defineFunction } from "@relkit/app/functions"
import { defineRoute } from "@relkit/app/routes"
import { z } from "@relkit/app/schema"

const listOrders = defineFunction({
  id: "orders.list",
  input: z.object({ status: z.string().optional() }),
  output: z.object({ count: z.number().int() }),
  handler: async () => ({ count: 0 })
})

export const GET = defineRoute({ target: listOrders })
````

````

**Signature**

```ts
declare const defineRoute: { <const Id extends string, const Handler extends RawRouteOptions<Id>["handler"]>(options: RawRouteOptions<Id, Handler>): RawRouteDescriptor<Id, Handler>; <const Id extends string, const Target extends FunctionRefAny, const Request extends HttpRequestMapping | undefined = undefined>(options: FunctionRouteOptions<Id, Target, Request>): FunctionRouteDescriptor<Id, Target, Request>; }
````

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-route.ts#L103)

Since v0.1.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="templates/default/v1/api/src/routes/echo/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineRoute } from "@relkit/app/routes";
import echo from "@app/services/echo/service.js";

export const POST = defineRoute({
  target: echo.echo,
});
```

**Frontend**

After [frontend installation, contract pull, and provider setup](/guides/frontend/connect-react),
call this `POST /echo` operation with its domain input. The route produces both the React selector
`POST /echo` and the TypeScript operation `route.post.echo`.

**React**

Render this component under `RelkitClientProvider`. Clicking the button sends `{ message }` and
displays the inferred `{ message: string }` result:

```tsx title="src/EchoButton.tsx"
"use client";

/** Calls the documented POST /echo function route after an explicit user action. */
import { useRelkitClient, useRouteMutation } from "@relkit/client/react";

/** Sends domain input and renders the validated output; the hook owns mutation state.
 * @returns An Echo button with pending, failure, and success feedback. */
export function EchoButton() {
  const { status } = useRelkitClient();
  const echo = useRouteMutation("POST /echo");

  return (
    <section>
      <button
        disabled={status !== "ready" || echo.isPending}
        onClick={() => echo.mutate({ message: "Hello from the frontend" })}
      >
        Send message
      </button>
      {echo.isPending && <p role="status">Sending…</p>}
      {echo.isError && <p role="alert">{String(echo.error)}</p>}
      {echo.isSuccess && <p>{echo.data.message}</p>}
    </section>
  );
}
```

**TypeScript**

Without React, load the browser identity before the mutation and call the generated operation:

```ts title="src/echo-client.ts"
/** Calls the Echo contract from a TypeScript browser frontend without React or backend source imports. */
import { createClient } from "@relkit/client";

/** Sends one message over RPC using types from the caller's pulled contract.
 * @param baseUrl - Public backend origin, or the frontend origin when proxying RPC.
 * @param message - Nonempty message accepted by the Echo function.
 * @returns The validated message output; transport and application failures reject. */
export async function echoMessage(baseUrl: string, message: string) {
  const response = await fetch(new URL("/_relkit/v1/client/identity", baseUrl), {
    credentials: "include",
    cache: "no-store",
  });
  if (!response.ok) throw new Error(`Identity request failed (${response.status})`);
  const identity = await response.json();
  if (
    !identity ||
    typeof identity.identityScope !== "string" ||
    typeof identity.sessionEpoch !== "string"
  ) {
    throw new Error("The backend returned an invalid client identity");
  }
  const client = createClient({
    baseUrl,
    headers: {
      "x-relkit-identity-scope": identity.identityScope,
      "x-relkit-session-epoch": identity.sessionEpoch,
    },
  });
  return client["route.post.echo"]({ message });
}
```

The React provider performs this identity step for hooks.

These calls use RPC over `/rpc`, with the same authorization and policy. Pass domain input rather
than assembling the route's REST mapping. Raw handlers and routes with `client: false` do not
generate these operations. Never import the backend descriptor into the browser.

Reference: [`useRouteMutation`](/docs/api/client#useroutemutation),
[`createClient`](/docs/api/client#createclient). Continue with [mutations](/docs/modules/client/mutations).

### "./route.types.js" (namespace export)

Re-exports all named exports from the "./route.types.js" module.

**Signature**

```ts
export * from "./route.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-route.ts#L20)

### defineRouteEffect

Defines a raw or function route through Effect.

**Example**

```ts
Effect.runSync(defineRouteEffect({ target: listOrders }));
```

**Signature**

```ts
declare const defineRouteEffect: {
  <const Id extends string, const Handler extends RawRouteOptions<Id>["handler"]>(
    options: RawRouteOptions<Id, Handler>,
  ): Effect.Effect<RawRouteDescriptor<Id, Handler>, RouteOperationError>;
  <
    const Id extends string,
    const Target extends FunctionRefAny,
    const Request extends HttpRequestMapping | undefined = undefined,
  >(
    options: FunctionRouteOptions<Id, Target, Request>,
  ): Effect.Effect<FunctionRouteDescriptor<Id, Target, Request>, RouteOperationError>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-route.ts#L55)

## `define-service-routes.ts`

### SERVICE_ROUTE_METHODS

**Signature**

```ts
declare const SERVICE_ROUTE_METHODS: readonly [
  "GET",
  "POST",
  "PUT",
  "PATCH",
  "DELETE",
  "HEAD",
  "OPTIONS",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L25)

### ServiceRouteEntry

**Signature**

```ts
declare const ServiceRouteEntry: ServiceRouteEntry<Service>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L20)

### ServiceRouteMethod

**Signature**

```ts
declare const ServiceRouteMethod: ServiceRouteMethod;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L18)

### ServiceRouteOptions

**Signature**

```ts
declare const ServiceRouteOptions: ServiceRouteOptions<Name, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L19)

### ServiceRoutesOptions

**Signature**

```ts
declare const ServiceRoutesOptions: Partial<
  Readonly<Record<ServiceRouteMethod, ServiceRouteEntry<Service>>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L21)

### ServiceRoutesResult

**Signature**

```ts
declare const ServiceRoutesResult: Readonly<{
  [Method in keyof Options]: FunctionRouteDescriptor<
    string,
    Extract<
      ServiceFunctions<Service>[Extract<
        EntryName<Options[Method]>,
        Extract<keyof ServiceFunctions<Service>, string>
      >],
      FunctionRefAny
    >,
    EntryRequest<Options[Method]>
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L22)

### defineServiceRoutes

Creates explicit HTTP routes for a service synchronously.

**Throws**

TypeError for invalid method or member references.

**Example**

```ts
defineServiceRoutes(service, { GET: "list" });
```

**Signature**

```ts
declare const defineServiceRoutes: <
  const Service extends ServiceDescriptor<string, any, any>,
  const Options extends ServiceRoutesOptions<Service>,
>(
  service: Service,
  options: Options & Record<Exclude<keyof Options, ServiceRouteMethod>, never>,
) => ServiceRoutesResult<Service, Options>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L82)

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

**Frontend**

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";

/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
 * @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
  const { status } = useRelkitClient();
  const orders = useRoute("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      {orders.isPending && <p role="status">Loading orders…</p>}
      {orders.data && <p>{orders.data.count} orders</p>}
      {orders.isError && <p role="alert">{orders.error.message}</p>}
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

### defineServiceRoutesEffect

Creates explicit service routes through an Effect.

**Example**

```ts
Effect.runSync(defineServiceRoutesEffect(service, { GET: "list" }));
```

**Signature**

```ts
declare const defineServiceRoutesEffect: <
  const Service extends ServiceDescriptor<string, any, any>,
  const Options extends Partial<Readonly<Record<ServiceRouteMethod, ServiceRouteEntry<Service>>>>,
>(
  service: Service,
  options: Options & Record<Exclude<keyof Options, ServiceRouteMethod>, never>,
) => Effect.Effect<
  Readonly<{
    [Method in keyof Options]: FunctionRouteDescriptor<
      string,
      Extract<
        ServiceFunctions<Service>[Extract<
          EntryName<Options[Method]>,
          Extract<keyof ServiceFunctions<Service>, string>
        >],
        FunctionRefAny
      >,
      EntryRequest<Options[Method]>
    >;
  }>,
  RouteOperationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.ts#L41)

## `define-service-routes.types.ts`

### ServiceRouteEntry (type alias)

Member name or options for a service route.

**Example**

```ts
type Entry = ServiceRouteEntry<typeof service>;
```

**Signature**

```ts
type ServiceRouteEntry<Service> = {
  [Name in ServiceFunctionName<Service>]:
    Name | ServiceRouteOptions<Name, ServiceFunction<Service, Name>>;
}[ServiceFunctionName<Service>];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.types.ts#L27)

### ServiceRouteMethod (type alias)

Explicit HTTP methods supported by a service route table.

**Example**

```ts
const method: ServiceRouteMethod = "GET";
```

**Signature**

```ts
type ServiceRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.types.ts#L9)

### ServiceRouteOptions (type alias)

Expanded options selecting one service function.

**Example**

```ts
type Options = ServiceRouteOptions<"list", typeof list>;
```

**Signature**

```ts
type ServiceRouteOptions<Name extends string, Target extends FunctionRefAny> = Omit<
  FunctionRouteOptions<string, Target, HttpRequestMapping | undefined>,
  "target"
> & { readonly member: Name };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.types.ts#L19)

### ServiceRoutesOptions (type alias)

Partial HTTP method table for a service.

**Example**

```ts
type Options = ServiceRoutesOptions<typeof service>;
```

**Signature**

```ts
type ServiceRoutesOptions<Service> = Partial<
  Readonly<Record<ServiceRouteMethod, ServiceRouteEntry<Service>>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.types.ts#L35)

### ServiceRoutesResult (type alias)

Route descriptors inferred from a service route table.

**Example**

```ts
type Routes = ServiceRoutesResult<typeof service, { GET: "list" }>;
```

**Signature**

```ts
type ServiceRoutesResult<Service, Options> = Readonly<{
  [Method in keyof Options]: FunctionRouteDescriptor<
    string,
    ServiceFunction<Service, Extract<EntryName<Options[Method]>, ServiceFunctionName<Service>>>,
    EntryRequest<Options[Method]>
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/define-service-routes.types.ts#L54)

## `http-dsl-mapping-validation.ts`

### assertMapping

Asserts a serializable mapping synchronously.

**Throws**

TypeError for invalid mapping values.

**Example**

```ts
assertMapping(http.path("id"));
```

**Signature**

```ts
declare const assertMapping: (value: unknown) => asserts value is HttpMappingNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L79)

### assertMappingEffect

Asserts a serializable mapping through Effect.

**Example**

```ts
Effect.runSync(assertMappingEffect(http.path("id")));
```

**Signature**

```ts
declare const assertMappingEffect: (
  value: unknown,
) => Effect.Effect<void, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L69)

### assertMappingValue

Validates a mapping inside an already observed operation.

**Throws**

RouteInputError for an invalid mapping.

**Example**

```ts
assertMappingValue({ kind: "path", name: "id" });
```

**Signature**

```ts
declare const assertMappingValue: (value: unknown) => asserts value is HttpMappingNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L89)

### assertRequestMapping

Asserts a request input mapping synchronously.

**Throws**

TypeError for invalid request mappings.

**Example**

```ts
assertRequestMapping(http.input({}));
```

**Signature**

```ts
declare const assertRequestMapping: (value: unknown) => asserts value is HttpRequestMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L130)

### assertRequestMappingEffect

Asserts a request input mapping through Effect.

**Example**

```ts
Effect.runSync(assertRequestMappingEffect(http.input({})));
```

**Signature**

```ts
declare const assertRequestMappingEffect: (
  value: unknown,
) => Effect.Effect<void, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L120)

### assertRequestMappingValue

Validates a request mapping inside an already observed operation.

**Throws**

RouteInputError for an invalid request mapping.

**Example**

```ts
assertRequestMappingValue({ kind: "input", fields: {} });
```

**Signature**

```ts
declare const assertRequestMappingValue: (value: unknown) => asserts value is HttpRequestMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L140)

### isHttpMapping

Checks a serializable mapping synchronously.

**Example**

```ts
isHttpMapping(http.path("id"));
```

**Signature**

```ts
declare const isHttpMapping: (value: unknown) => value is HttpMappingNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L21)

### isHttpMappingEffect

Checks a serializable mapping through Effect.

**Example**

```ts
Effect.runSync(isHttpMappingEffect(http.path("id")));
```

**Signature**

```ts
declare const isHttpMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L12)

### isHttpRequestMapping

Checks a request input mapping synchronously.

**Example**

```ts
isHttpRequestMapping(http.input({}));
```

**Signature**

```ts
declare const isHttpRequestMapping: (value: unknown) => value is HttpRequestMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L108)

### isHttpRequestMappingEffect

Checks a request input mapping through Effect.

**Example**

```ts
Effect.runSync(isHttpRequestMappingEffect(http.input({})));
```

**Signature**

```ts
declare const isHttpRequestMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L99)

### isMappingValue

Checks a non-root mapping during recursive validation.

**Example**

```ts
isMappingValue(http.path("id"));
```

**Signature**

```ts
declare const isMappingValue: (value: unknown) => value is HttpMappingNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-mapping-validation.ts#L149)

## `http-dsl-methods.types.ts`

### HttpDslMethods (interface)

Constructor methods for serializable HTTP mappings.

**Example**

```ts
const request = http.input({ id: http.path("id") });
```

**Signature**

```ts
export interface HttpDslMethods extends HttpDslSources {
  /** Named request fields.
   * @param fields - Serializable field mappings.
   * @returns An input mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.input({ id: http.path("id") });
   */
  input<const S extends HttpMappingShape>(fields: S): HttpInputMapping<S>;
  /** Named nested fields.
   * @param fields - Serializable field mappings.
   * @returns A nested object mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.nested({ id: http.path("id") });
   */
  nested<const S extends HttpMappingShape>(fields: S): HttpNestedMapping<S>;
  /** A serializable constant.
   * @param value - JSON-compatible value.
   * @returns A constant mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.constant("all");
   */
  constant<const V extends JsonValue>(value: V): HttpConstantMapping<V>;
  /** An optional source value.
   * @param value - Existing mapping node.
   * @returns An optional mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.optional(http.query("page"));
   */
  optional<const M extends HttpMappingNode>(value: M): HttpOptionalMapping<M>;
  /** A source value with a fallback.
   * @param value - Existing mapping node
   * @param fallback - JSON-compatible default.
   * @returns A default mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.default(http.query("page"), "1");
   */
  default<const M extends HttpMappingNode, const V extends JsonValue>(
    value: M,
    fallback: V,
  ): HttpDefaultMapping<M, V>;
  /** A registered transformation.
   * @param transform - Reference or stable ID
   * @param value - Optional input mapping.
   * @returns A transform mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.transform("text.upper", http.body("name"));
   */
  transform<const T extends HttpTransformRef | string, const M extends HttpMappingNode>(
    transform: T,
    value?: M,
  ): HttpTransformMapping<TransformOutput<T>>;
  /** A successful response.
   * @param status - HTTP status
   * @param schema - Optional body schema.
   * @returns A response mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.success(200);
   */
  success(status: number, schema?: StandardSchemaV1): HttpResponseMapping;
  /** An error response.
   * @param errorId - Stable error ID
   * @param status - HTTP status
   * @param schema - Optional body schema.
   * @returns An error response mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.error("not-found", 404);
   */
  error(errorId: string, status: number, schema?: StandardSchemaV1): HttpResponseMapping;
  /** A validation failure response.
   * @param status - HTTP status
   * @param schema - Optional body schema.
   * @returns A validation-error mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.validationError(422);
   */
  validationError(status?: number, schema?: StandardSchemaV1): HttpResponseMapping;
  /** A named response.
   * @param id - Stable response ID
   * @param status - HTTP status
   * @param schema - Optional body schema.
   * @returns A named response mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.response("accepted", 202);
   */
  response(id: string, status: number, schema?: StandardSchemaV1): HttpResponseMapping;
  /** A middleware continue decision.
   * @returns A continue decision.
   * @example http.continue();
   */
  continue(): ContinueMapping;
  /** A middleware response decision.
   * @param response - Mapping or stable response ID
   * @param body - Optional body mapping.
   * @returns A respond decision.
   * @throws TypeError when the mapping input is invalid.
   * @example http.respond("accepted");
   */
  respond(response: HttpResponseMapping | string, body?: HttpMappingNode): RespondMapping;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-methods.types.ts#L25)

## `http-dsl-operations.ts`

### httpEffects

Effect implementations for each HTTP mapping constructor.

**Example**

```ts
Effect.runSync(httpEffects.input({ id: httpEffects.path("id") }));
```

**Signature**

```ts
declare const httpEffects: {
  constant: <const V extends JsonValue>(
    value: V,
  ) => Effect.Effect<HttpConstantMapping<V>, RouteOperationError, never>;
  optional: <const M extends HttpMappingNode>(
    value: M,
  ) => Effect.Effect<HttpOptionalMapping<M>, RouteOperationError, never>;
  default: <const M extends HttpMappingNode, const V extends JsonValue>(
    value: M,
    fallback: V,
  ) => Effect.Effect<HttpDefaultMapping<M, V>, RouteOperationError, never>;
  transform: <const T extends HttpTransformRef | string, const M extends HttpMappingNode>(
    transform: T,
    value?: M | undefined,
  ) => Effect.Effect<HttpTransformMapping<TransformOutput<T>>, RouteOperationError, never>;
  success: (
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  error: (
    errorId: string,
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  validationError: (
    status?: number | undefined,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  response: (
    id: string,
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  continue: () => Effect.Effect<ContinueMapping, RouteOperationError, never>;
  respond: (
    response: string | HttpResponseMapping,
    body?: HttpMappingNode | undefined,
  ) => Effect.Effect<RespondMapping, RouteOperationError, never>;
  input: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpInputMapping<S>, RouteOperationError, never>;
  nested: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpNestedMapping<S>, RouteOperationError, never>;
  path: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  pathSegments: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  query: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  header: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  cookie: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  body: (
    name?: string | undefined,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  wholeBody: () => Effect.Effect<HttpWholeBodyMapping<unknown>, RouteOperationError, never>;
  multipart: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  multipartAll: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-operations.ts#L12)

## `http-dsl-response-validation.ts`

### assertResponse

Asserts a response mapping synchronously.

**Throws**

TypeError for invalid response mappings.

**Example**

```ts
assertResponse(http.success(200));
```

**Signature**

```ts
declare const assertResponse: (value: unknown) => HttpResponseMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L56)

### assertResponseEffect

Asserts a response mapping through Effect.

**Example**

```ts
Effect.runSync(assertResponseEffect(http.success(200)));
```

**Signature**

```ts
declare const assertResponseEffect: (
  value: unknown,
) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L46)

### assertResponseValue

Validates a response inside an already observed operation.

**Throws**

RouteInputError for an invalid response.

**Example**

```ts
assertResponseValue({ kind: "success", id: "success.200", status: 200 });
```

**Signature**

```ts
declare const assertResponseValue: (value: unknown) => HttpResponseMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L66)

### isHttpResponseMapping

Checks a response mapping synchronously.

**Example**

```ts
isHttpResponseMapping(http.success(200));
```

**Signature**

```ts
declare const isHttpResponseMapping: (value: unknown) => value is HttpResponseMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L27)

### isHttpResponseMappingEffect

Checks a response mapping through Effect.

**Example**

```ts
Effect.runSync(isHttpResponseMappingEffect(http.success(200)));
```

**Signature**

```ts
declare const isHttpResponseMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L18)

### isMiddlewareDecision

Checks a middleware response decision synchronously.

**Example**

```ts
isMiddlewareDecision(http.continue());
```

**Signature**

```ts
declare const isMiddlewareDecision: (value: unknown) => value is MiddlewareDecisionMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L85)

### isMiddlewareDecisionEffect

Checks a middleware response decision through Effect.

**Example**

```ts
Effect.runSync(isMiddlewareDecisionEffect(http.continue()));
```

**Signature**

```ts
declare const isMiddlewareDecisionEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-response-validation.ts#L76)

## `http-dsl-source-operations.ts`

### httpSourceEffects

Effect constructors for request input and source mappings.

**Example**

```ts
Effect.runSync(httpSourceEffects.path("id"));
```

**Signature**

```ts
declare const httpSourceEffects: {
  input: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpInputMapping<S>, RouteOperationError, never>;
  nested: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpNestedMapping<S>, RouteOperationError, never>;
  path: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  pathSegments: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  query: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  header: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  cookie: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  body: (
    name?: string | undefined,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  wholeBody: () => Effect.Effect<HttpWholeBodyMapping<unknown>, RouteOperationError, never>;
  multipart: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  multipartAll: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-source-operations.ts#L9)

## `http-dsl-sources.types.ts`

### HttpDslSources (interface)

Source constructors for serializable HTTP request mappings.

**Example**

```ts
const id = http.path("id");
```

**Signature**

```ts
export interface HttpDslSources {
  /** One path parameter.
   * @param name - Path parameter name
   * @returns A path source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.path("id");
   */
  path(name: string): HttpPathMapping;
  /** Maps a named path parameter with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.path("id", { optional: true });
   */
  path(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** Captured path segments.
   * @param name - Segment parameter name
   * @returns A path segments mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.pathSegments("parts");
   */
  pathSegments(name: string): HttpPathSegmentsMapping;
  /** Maps a captured path segments with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.pathSegments("parts", { optional: true });
   */
  pathSegments(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** One query parameter.
   * @param name - Query parameter name
   * @returns A query source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.query("page");
   */
  query(name: string): HttpQueryMapping;
  /** Maps a named query parameter with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.query("page", { default: "1" });
   */
  query(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** One request header.
   * @param name - Header name
   * @returns A header source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.header("authorization");
   */
  header(name: string): HttpHeaderMapping;
  /** Maps a named request header with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.header("authorization", { optional: true });
   */
  header(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** One request cookie.
   * @param name - Cookie name
   * @returns A cookie source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.cookie("session");
   */
  cookie(name: string): HttpCookieMapping;
  /** Maps a named request cookie with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.cookie("session", { optional: true });
   */
  cookie(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** The whole body or one body field.
   * @param name - Optional body field name
   * @param options - Optionality or fallback.
   * @returns A body source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.body("name");
   */
  /** The complete request body.
   * @returns A whole-body mapping.
   * @example http.body();
   */
  body(): HttpWholeBodyMapping;
  /** Maps one named body field.
   * @param name - Body field name.
   * @returns A body field mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.body("name");
   */
  body(name: string): HttpBodyMapping;
  /** Maps a named body field with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.body("name", { optional: true });
   */
  body(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** The complete request body.
   * @returns A whole-body mapping.
   * @example http.wholeBody();
   */
  wholeBody(): HttpWholeBodyMapping;
  /** One multipart form field.
   * @param name - Form field name
   * @returns A multipart source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.multipart("photo");
   */
  multipart(name: string): HttpMultipartMapping;
  /** Maps a named multipart field with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.multipart("photo", { optional: true });
   */
  multipart(name: string, options: HttpSourceOptions): HttpMappingNode;
  /** All values of one multipart field.
   * @param name - Form field name
   * @returns A multipart-array source mapping.
   * @throws TypeError when the mapping input is invalid.
   * @example http.multipartAll("files");
   */
  multipartAll(name: string): HttpMultipartAllMapping;
  /** Maps a all values of a multipart field with optionality or a default.
   * @param name - Source name.
   * @param options - Optionality or JSON fallback.
   * @returns A source mapping, optionally wrapped by a default or optional node.
   * @throws TypeError when the mapping input is invalid.
   * @example http.multipartAll("files", { optional: true });
   */
  multipartAll(name: string, options: HttpSourceOptions): HttpMappingNode;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-sources.types.ts#L18)

## `http-dsl-validation.ts`

### "./http-dsl-mapping-validation.js" (namespace export)

Re-exports all named exports from the "./http-dsl-mapping-validation.js" module.

**Signature**

```ts
export * from "./http-dsl-mapping-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-validation.ts#L2)

### "./http-dsl-response-validation.js" (namespace export)

Re-exports all named exports from the "./http-dsl-response-validation.js" module.

**Signature**

```ts
export * from "./http-dsl-response-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-validation.ts#L3)

### "./http-dsl-value-validation.js" (namespace export)

Re-exports all named exports from the "./http-dsl-value-validation.js" module.

**Signature**

```ts
export * from "./http-dsl-value-validation.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-validation.ts#L1)

## `http-dsl-value-validation.ts`

### assertSchema

Asserts a Standard Schema validator synchronously.

**Throws**

TypeError for invalid schemas.

**Example**

```ts
assertSchema(schema, "response schema");
```

**Signature**

```ts
declare const assertSchema: (value: unknown, name: string) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L55)

### assertSchemaEffect

Asserts a Standard Schema validator through Effect.

**Example**

```ts
Effect.runSync(assertSchemaEffect(schema, "response schema"));
```

**Signature**

```ts
declare const assertSchemaEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<void, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L43)

### assertSchemaValue

Validates a schema inside an already observed operation.

**Throws**

RouteInputError for an invalid schema.

**Example**

```ts
assertSchemaValue(schema, "response schema");
```

**Signature**

```ts
declare const assertSchemaValue: (
  value: unknown,
  name: string,
) => asserts value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L66)

### isJsonValue

Checks JSON compatibility without leaking a validation exception.

**Example**

```ts
isJsonValue({ ok: true });
```

**Signature**

```ts
declare const isJsonValue: (value: unknown) => value is JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L101)

### isRecord

Checks an ordinary non-array object synchronously.

**Example**

```ts
isRecord({});
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<string, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L132)

### isRecordEffect

Checks an ordinary non-array object through Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({}));
```

**Signature**

```ts
declare const isRecordEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L123)

### isRecordValue

Checks the object shape inside another observed operation.

**Example**

```ts
isRecordValue({ kind: "path" });
```

**Signature**

```ts
declare const isRecordValue: (value: unknown) => value is Record<string, any>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L140)

### isSchema

Checks a Standard Schema validator synchronously.

**Example**

```ts
isSchema(schema);
```

**Signature**

```ts
declare const isSchema: (value: unknown) => value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L21)

### isSchemaEffect

Checks a Standard Schema validator through Effect.

**Example**

```ts
Effect.runSync(isSchemaEffect(schema));
```

**Signature**

```ts
declare const isSchemaEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L12)

### isSchemaValue

Checks the Standard Schema shape inside a parent operation.

**Example**

```ts
isSchemaValue(z.string());
```

**Signature**

```ts
declare const isSchemaValue: (value: unknown) => value is StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L29)

### isStatus

Checks an HTTP response status synchronously.

**Example**

```ts
isStatus(200);
```

**Signature**

```ts
declare const isStatus: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L85)

### isStatusEffect

Checks an HTTP response status through Effect.

**Example**

```ts
Effect.runSync(isStatusEffect(200));
```

**Signature**

```ts
declare const isStatusEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L76)

### isStatusValue

Checks an HTTP status inside response validation.

**Example**

```ts
isStatusValue(200);
```

**Signature**

```ts
declare const isStatusValue: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L93)

### ownKeys

Checks that a mapping has only its allowed own property names.

**Example**

```ts
ownKeys({ kind: "continue" }, "kind");
```

**Signature**

```ts
declare const ownKeys: (value: object, ...keys: string[]) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-value-validation.ts#L115)

## `http-dsl-values.ts`

### httpValue

Internal pure constructors evaluated only inside the public Effect operations.

**Signature**

```ts
declare const httpValue: HttpDsl;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-values.ts#L26)

### isTransformRefValue

Checks a transform reference without running another Effect adapter.

**Example**

```ts
isTransformRefValue({ ref: { kind: "transform", id: "x" }, schema });
```

**Signature**

```ts
declare const isTransformRefValue: (value: unknown) => value is HttpTransformRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl-values.ts#L137)

## `http-dsl.ts`

### "./http-dsl.types.js" (namespace export)

Re-exports all named exports from the "./http-dsl.types.js" module.

**Signature**

```ts
export * from "./http-dsl.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L23)

### assertRequestMapping

**Signature**

```ts
declare const assertRequestMapping: (value: unknown) => asserts value is HttpRequestMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L25)

### assertRequestMappingEffect

**Signature**

```ts
declare const assertRequestMappingEffect: (
  value: unknown,
) => Effect.Effect<void, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L26)

### assertResponse

**Signature**

```ts
declare const assertResponse: (value: unknown) => HttpResponseMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L27)

### assertResponseEffect

**Signature**

```ts
declare const assertResponseEffect: (
  value: unknown,
) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L28)

### defineRequestTransform

Alias for request transform definitions.

**Throws**

TypeError for invalid transform input.

**Example**

```ts
defineRequestTransform({ schema });
```

**Signature**

```ts
declare const defineRequestTransform: <
  const Id extends string,
  const Schema extends StandardSchemaV1,
>(
  options: DefineTransformOptions<Id, Schema>,
) => HttpTransformDescriptor<Id, Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L84)

### defineRequestTransformEffect

Effect alias for request transform definitions.

**Example**

```ts
Effect.runSync(defineRequestTransformEffect({ schema }));
```

**Signature**

```ts
declare const defineRequestTransformEffect: <
  const Id extends string,
  const Schema extends StandardSchemaV1,
>(
  options: DefineTransformOptions<Id, Schema>,
) => Effect.Effect<HttpTransformDescriptor<Id, Schema>, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L91)

### defineTransform

Defines a serializable HTTP transform.

**Throws**

TypeError for invalid input or a closure-bearing transform.

**Example**

```ts
defineTransform({ schema });
```

**Signature**

```ts
declare const defineTransform: <const Id extends string, const Schema extends StandardSchemaV1>(
  options: DefineTransformOptions<Id, Schema>,
) => HttpTransformDescriptor<Id, Schema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L72)

### defineTransformEffect

Defines a serializable transform through Effect.

**Example**

```ts
Effect.runSync(defineTransformEffect({ schema }));
```

**Signature**

```ts
declare const defineTransformEffect: <
  const Id extends string,
  const Schema extends StandardSchemaV1,
>(
  options: DefineTransformOptions<Id, Schema>,
) => Effect.Effect<HttpTransformDescriptor<Id, Schema>, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L45)

### http

Creates serializable HTTP request and response mappings.

**Example**

```ts
const request = http.input({ id: http.path("id") });
```

**Signature**

```ts
declare const http: HttpDsl;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L131)

### httpEffects

**Signature**

```ts
declare const httpEffects: {
  constant: <const V extends JsonValue>(
    value: V,
  ) => Effect.Effect<HttpConstantMapping<V>, RouteOperationError, never>;
  optional: <const M extends HttpMappingNode>(
    value: M,
  ) => Effect.Effect<HttpOptionalMapping<M>, RouteOperationError, never>;
  default: <const M extends HttpMappingNode, const V extends JsonValue>(
    value: M,
    fallback: V,
  ) => Effect.Effect<HttpDefaultMapping<M, V>, RouteOperationError, never>;
  transform: <const T extends HttpTransformRef | string, const M extends HttpMappingNode>(
    transform: T,
    value?: M | undefined,
  ) => Effect.Effect<HttpTransformMapping<TransformOutput<T>>, RouteOperationError, never>;
  success: (
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  error: (
    errorId: string,
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  validationError: (
    status?: number | undefined,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  response: (
    id: string,
    status: number,
    schema?: StandardSchemaV1<unknown, unknown> | undefined,
  ) => Effect.Effect<HttpResponseMapping, RouteOperationError, never>;
  continue: () => Effect.Effect<ContinueMapping, RouteOperationError, never>;
  respond: (
    response: string | HttpResponseMapping,
    body?: HttpMappingNode | undefined,
  ) => Effect.Effect<RespondMapping, RouteOperationError, never>;
  input: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpInputMapping<S>, RouteOperationError, never>;
  nested: <const S extends HttpMappingShape>(
    fields: S,
  ) => Effect.Effect<HttpNestedMapping<S>, RouteOperationError, never>;
  path: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  pathSegments: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  query: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  header: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  cookie: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  body: (
    name?: string | undefined,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  wholeBody: () => Effect.Effect<HttpWholeBodyMapping<unknown>, RouteOperationError, never>;
  multipart: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
  multipartAll: (
    name: string,
    options?: HttpSourceOptions | undefined,
  ) => Effect.Effect<HttpMappingNode, RouteOperationError, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L38)

### isHttpMapping

**Signature**

```ts
declare const isHttpMapping: (value: unknown) => value is HttpMappingNode;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L29)

### isHttpMappingEffect

**Signature**

```ts
declare const isHttpMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L30)

### isHttpRequestMapping

**Signature**

```ts
declare const isHttpRequestMapping: (value: unknown) => value is HttpRequestMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L31)

### isHttpRequestMappingEffect

**Signature**

```ts
declare const isHttpRequestMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L32)

### isHttpResponseMapping

**Signature**

```ts
declare const isHttpResponseMapping: (value: unknown) => value is HttpResponseMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L33)

### isHttpResponseMappingEffect

**Signature**

```ts
declare const isHttpResponseMappingEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L34)

### isMiddlewareDecision

**Signature**

```ts
declare const isMiddlewareDecision: (value: unknown) => value is MiddlewareDecisionMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L35)

### isMiddlewareDecisionEffect

**Signature**

```ts
declare const isMiddlewareDecisionEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L36)

### isTransformRef

Checks a transform reference synchronously.

**Example**

```ts
isTransformRef(transform);
```

**Signature**

```ts
declare const isTransformRef: (value: unknown) => value is HttpTransformRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L123)

### isTransformRefEffect

Checks a transform reference through Effect.

**Example**

```ts
Effect.runSync(isTransformRefEffect(transform));
```

**Signature**

```ts
declare const isTransformRefEffect: (
  value: unknown,
) => Effect.Effect<boolean, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.ts#L114)

## `http-dsl.types.ts`

### "./http-mapping.types.js" (namespace export)

Re-exports all named exports from the "./http-mapping.types.js" module.

**Signature**

```ts
export * from "./http-mapping.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L6)

### ContinueMapping (interface)

Middleware decision that delegates to the next handler.

**Example**

```ts
const decision: ContinueMapping = http.continue();
```

**Signature**

```ts
export interface ContinueMapping {
  readonly kind: "continue";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L75)

### DefineTransformOptions (interface)

Authoring options for a serializable transform.

**Example**

```ts
type Options = DefineTransformOptions<"text.upper", typeof schema>;
```

**Signature**

```ts
export interface DefineTransformOptions<
  Id extends string,
  Schema extends StandardSchemaV1,
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly schema: Schema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L54)

### HttpDsl (interface)

Synchronous HTTP mapping constructor API.

**Example**

```ts
const request = http.input({ id: http.path("id") });
```

**Signature**

```ts
export interface HttpDsl extends HttpDslMethods {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L94)

### HttpMethod (type alias)

HTTP methods recognized by the compiler.

**Example**

```ts
const method: HttpMethod = "GET";
```

**Signature**

```ts
type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "ALL";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L11)

### HttpRequestContentType (type alias)

Supported explicit request content types.

**Example**

```ts
const accept: HttpRequestContentType = "application/json";
```

**Signature**

```ts
type HttpRequestContentType = "application/json" | "multipart/form-data";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L15)

### HttpResponseMapping (interface)

Serializable response status and schema mapping.

**Example**

```ts
const response: HttpResponseMapping = http.success(200);
```

**Signature**

```ts
export interface HttpResponseMapping {
  readonly kind: "success" | "error" | "validation-error" | "response";
  readonly id: string;
  readonly status: number;
  readonly errorId?: string;
  readonly schema?: StandardSchemaV1;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L65)

### HttpTransformDescriptor (interface)

Frozen authoring descriptor for a transform.

**Example**

```ts
type Upper = HttpTransformDescriptor<"text.upper", typeof schema>;
```

**Signature**

```ts
export interface HttpTransformDescriptor<
  Id extends string,
  Schema extends StandardSchemaV1,
> extends HttpTransformRef<Id, Schema> {
  readonly kind: "transform";
  readonly id: Id;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L36)

### HttpTransformRef (interface)

Transform reference paired with its output schema.

**Example**

```ts
const ref: HttpTransformRef = { ref: transform.ref, schema: transform.schema };
```

**Signature**

```ts
export interface HttpTransformRef<
  Id extends string = string,
  Schema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly ref: TransformReference<Id>;
  readonly schema: Schema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L26)

### MiddlewareDecisionMapping (type alias)

Union of middleware response decisions.

**Example**

```ts
const decision: MiddlewareDecisionMapping = http.continue();
```

**Signature**

```ts
type MiddlewareDecisionMapping = ContinueMapping | RespondMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L89)

### RespondMapping (interface)

Middleware decision selecting a response mapping.

**Example**

```ts
const decision: RespondMapping = http.respond("success.200");
```

**Signature**

```ts
export interface RespondMapping {
  readonly kind: "respond";
  readonly responseId: string;
  readonly body?: HttpMappingNode;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L81)

### TransformOutput (type alias)

Output type inferred from a transform schema.

**Example**

```ts
type Output = TransformOutput<typeof transform>;
```

**Signature**

```ts
type TransformOutput<T> = T extends { readonly schema: infer Schema }
  ? Schema extends StandardSchemaV1
    ? InferOutput<Schema>
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L46)

### TransformReference (interface)

Stable serializable transform identity.

**Example**

```ts
const ref: TransformReference = { kind: "transform", id: "text.upper" };
```

**Signature**

```ts
export interface TransformReference<Id extends string = string> {
  readonly kind: "transform";
  readonly id: Id;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-dsl.types.ts#L19)

## `http-mapping.types.ts`

### HttpBodyMapping (interface)

One named field from a request body.

**Example**

```ts
const mapping: HttpBodyMapping = http.body("name");
```

**Signature**

```ts
export interface HttpBodyMapping<Output = unknown> extends HttpMapping<Output> {
  readonly kind: "body";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L61)

### HttpConstantMapping (interface)

A serializable constant input.

**Example**

```ts
const mapping: HttpConstantMapping<string> = http.constant("all");
```

**Signature**

```ts
export interface HttpConstantMapping<
  Output extends JsonValue = JsonValue,
> extends HttpMapping<Output> {
  readonly kind: "constant";
  readonly value: Output;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L90)

### HttpCookieMapping (interface)

One named request cookie.

**Example**

```ts
const mapping: HttpCookieMapping = http.cookie("session");
```

**Signature**

```ts
export interface HttpCookieMapping<Output = string> extends HttpMapping<Output> {
  readonly kind: "cookie";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L54)

### HttpDefaultMapping (interface)

A source mapping with a serializable fallback.

**Example**

```ts
const mapping: HttpDefaultMapping = http.default(http.query("page"), "1");
```

**Signature**

```ts
export interface HttpDefaultMapping<
  M extends HttpMappingNode = HttpMappingNode,
  Default extends JsonValue = JsonValue,
> extends HttpMapping<Exclude<HttpMappingOutput<M>, undefined> | Default> {
  readonly kind: "default";
  readonly value: M;
  readonly default: Default;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L126)

### HttpHeaderMapping (interface)

One named request header.

**Example**

```ts
const mapping: HttpHeaderMapping = http.header("authorization");
```

**Signature**

```ts
export interface HttpHeaderMapping<Output = string> extends HttpMapping<Output> {
  readonly kind: "header";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L47)

### HttpInputMapping (interface)

The root request input assembled from field mappings.

**Example**

```ts
const mapping: HttpInputMapping = http.input({ id: http.path("id") });
```

**Signature**

```ts
export interface HttpInputMapping<
  S extends HttpMappingShape = HttpMappingShape,
> extends HttpMapping<MappingShapeOutput<S>> {
  readonly kind: "input";
  readonly fields: S;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L108)

### HttpMapping (interface)

Base phantom output contract for every HTTP mapping.

**Example**

```ts
const mapping: HttpMapping<string> = http.path("id");
```

**Signature**

```ts
export interface HttpMapping<Output = unknown> {
  readonly __output?: Output;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L6)

### HttpMappingNode (type alias)

Union of supported serializable request mapping nodes.

**Example**

```ts
const mapping: HttpMappingNode = http.path("id");
```

**Signature**

```ts
type HttpMappingNode =
  | HttpPathMapping
  | HttpPathSegmentsMapping
  | HttpQueryMapping
  | HttpHeaderMapping
  | HttpCookieMapping
  | HttpBodyMapping
  | HttpWholeBodyMapping
  | HttpMultipartMapping
  | HttpMultipartAllMapping
  | HttpConstantMapping
  | HttpInputMapping
  | HttpNestedMapping
  | HttpOptionalMapping
  | HttpDefaultMapping
  | HttpTransformMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L145)

### HttpMappingOutput (type alias)

Output value inferred from one mapping node.

**Example**

```ts
type Output = HttpMappingOutput<HttpPathMapping>;
```

**Signature**

```ts
type HttpMappingOutput<M> = M extends HttpMapping<infer Output> ? Output : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L22)

### HttpMappingShape (type alias)

Named fields in a nested or request input mapping.

**Example**

```ts
const fields: HttpMappingShape = { id: http.path("id") };
```

**Signature**

```ts
type HttpMappingShape = Readonly<Record<string, HttpMappingNode>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L12)

### HttpMultipartAllMapping (interface)

All values of a multipart form field.

**Example**

```ts
const mapping: HttpMultipartAllMapping = http.multipartAll("files");
```

**Signature**

```ts
export interface HttpMultipartAllMapping<
  Output = readonly (string | File)[],
> extends HttpMapping<Output> {
  readonly kind: "multipart-all";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L81)

### HttpMultipartMapping (interface)

One multipart form field.

**Example**

```ts
const mapping: HttpMultipartMapping = http.multipart("photo");
```

**Signature**

```ts
export interface HttpMultipartMapping<Output = string | File> extends HttpMapping<Output> {
  readonly kind: "multipart";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L74)

### HttpNestedMapping (interface)

A nested object assembled from field mappings.

**Example**

```ts
const mapping: HttpNestedMapping = http.nested({ id: http.path("id") });
```

**Signature**

```ts
export interface HttpNestedMapping<
  S extends HttpMappingShape = HttpMappingShape,
> extends HttpMapping<MappingShapeOutput<S>> {
  readonly kind: "nested";
  readonly fields: S;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L99)

### HttpOptionalMapping (interface)

A source mapping whose absence is allowed.

**Example**

```ts
const mapping: HttpOptionalMapping = http.optional(http.query("page"));
```

**Signature**

```ts
export interface HttpOptionalMapping<
  M extends HttpMappingNode = HttpMappingNode,
> extends HttpMapping<HttpMappingOutput<M> | undefined> {
  readonly kind: "optional";
  readonly value: M;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L117)

### HttpPathMapping (interface)

One named route path parameter.

**Example**

```ts
const mapping: HttpPathMapping = http.path("id");
```

**Signature**

```ts
export interface HttpPathMapping<Output = string> extends HttpMapping<Output> {
  readonly kind: "path";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L26)

### HttpPathSegmentsMapping (interface)

All segments captured by a route path parameter.

**Example**

```ts
const mapping: HttpPathSegmentsMapping = http.pathSegments("parts");
```

**Signature**

```ts
export interface HttpPathSegmentsMapping<Output = readonly string[]> extends HttpMapping<Output> {
  readonly kind: "path-segments";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L33)

### HttpQueryMapping (interface)

One named query parameter.

**Example**

```ts
const mapping: HttpQueryMapping = http.query("page");
```

**Signature**

```ts
export interface HttpQueryMapping<Output = string> extends HttpMapping<Output> {
  readonly kind: "query";
  readonly name: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L40)

### HttpRequestMapping (type alias)

The required root shape for explicit request mapping.

**Example**

```ts
const mapping: HttpRequestMapping = http.input({ id: http.path("id") });
```

**Signature**

```ts
type HttpRequestMapping = HttpInputMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L164)

### HttpSourceOptions (interface)

Optionality and fallback options for one request source.

**Example**

```ts
const options: HttpSourceOptions = { optional: true };
```

**Signature**

```ts
export interface HttpSourceOptions {
  readonly optional?: boolean;
  readonly default?: JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L168)

### HttpTransformMapping (interface)

A value transformed by a registered transform ID.

**Example**

```ts
const mapping: HttpTransformMapping = http.transform("upper", http.body("name"));
```

**Signature**

```ts
export interface HttpTransformMapping<Output = unknown> extends HttpMapping<Output> {
  readonly kind: "transform";
  readonly transformId: string;
  readonly value: HttpMappingNode;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L137)

### HttpWholeBodyMapping (interface)

The complete request body.

**Example**

```ts
const mapping: HttpWholeBodyMapping = http.wholeBody();
```

**Signature**

```ts
export interface HttpWholeBodyMapping<Output = unknown> extends HttpMapping<Output> {
  readonly kind: "whole-body";
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L68)

### MappingShapeOutput (type alias)

Output shape inferred from named mapping fields.

**Example**

```ts
type Output = MappingShapeOutput<{ id: HttpPathMapping }>;
```

**Signature**

```ts
type MappingShapeOutput<S extends HttpMappingShape> = {
  readonly [K in keyof S]: HttpMappingOutput<S[K]>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/http-mapping.types.ts#L16)

## `index.ts`

### "./define-middleware.js" (namespace export)

Re-exports all named exports from the "./define-middleware.js" module.

**Signature**

```ts
export * from "./define-middleware.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L2)

### "./define-route.js" (namespace export)

Re-exports all named exports from the "./define-route.js" module.

**Signature**

```ts
export * from "./define-route.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L3)

### "./define-service-routes.js" (namespace export)

Re-exports all named exports from the "./define-service-routes.js" module.

**Signature**

```ts
export * from "./define-service-routes.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L4)

### "./http-dsl.js" (namespace export)

Re-exports all named exports from the "./http-dsl.js" module.

**Signature**

```ts
export * from "./http-dsl.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L1)

### "./route-module.types.js" (namespace export)

Re-exports all named exports from the "./route-module.types.js" module.

**Signature**

```ts
export * from "./route-module.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L13)

### "./route.types.js" (namespace export)

Re-exports all named exports from the "./route.types.js" module.

**Signature**

```ts
export * from "./route.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L12)

### HttpRateLimitKey

**Signature**

```ts
declare const HttpRateLimitKey: HttpRateLimitKey;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L14)

### RouteInputError

**Signature**

```ts
declare const RouteInputError: typeof RouteInputError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L6)

### RouteOperation

**Signature**

```ts
declare const RouteOperation: RouteOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L11)

### RouteOperationError

**Signature**

```ts
declare const RouteOperationError: typeof RouteOperationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L7)

### RouteRateLimit

**Signature**

```ts
declare const RouteRateLimit: RouteRateLimit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L14)

### RouteTelemetry

**Signature**

```ts
declare const RouteTelemetry: typeof RouteTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L8)

### RouteTelemetryLive

**Signature**

```ts
declare const RouteTelemetryLive: Layer<RouteTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L9)

### RouteTelemetryService

**Signature**

```ts
declare const RouteTelemetryService: RouteTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/index.ts#L11)

## `route-auth.ts`

### BetterAuthRegistration

**Signature**

```ts
declare const BetterAuthRegistration: BetterAuthRegistration;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L6)

### copyProtectedPaths

Validates and copies protected route patterns synchronously.

**Throws**

TypeError for invalid patterns.

**Example**

```ts
copyProtectedPaths(["/admin/*"]);
```

**Signature**

```ts
declare const copyProtectedPaths: (values: readonly string[] | undefined) => readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L67)

### copyProtectedPathsEffect

Validates and copies protected paths through Effect.

**Example**

```ts
Effect.runSync(copyProtectedPathsEffect(["/admin/*"]));
```

**Signature**

```ts
declare const copyProtectedPathsEffect: (
  values: ReadonlyArray<string> | undefined,
) => Effect.Effect<ReadonlyArray<string>, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L56)

### copyProtectedValues

Copies protected paths inside an already observed operation.

**Throws**

RouteInputError for an invalid pattern.

**Example**

```ts
copyProtectedValues(["/admin/*"]);
```

**Signature**

```ts
declare const copyProtectedValues: (values: readonly string[] | undefined) => readonly string[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L77)

### readBetterAuthRegistration

Reads a Better Auth handler registration synchronously.

**Throws**

TypeError for malformed handler input.

**Example**

```ts
readBetterAuthRegistration(handler);
```

**Signature**

```ts
declare const readBetterAuthRegistration: (
  handler: RawRouteOptions<string>["handler"],
) => BetterAuthRegistration | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L24)

### readBetterAuthRegistrationEffect

Reads a Better Auth handler registration through Effect.

**Example**

```ts
Effect.runSync(readBetterAuthRegistrationEffect(handler));
```

**Signature**

```ts
declare const readBetterAuthRegistrationEffect: (
  handler: RawHttpHandler,
) => Effect.Effect<BetterAuthRegistration | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L13)

### readRegistrationValue

Reads registration metadata inside an already observed operation.

**Example**

```ts
readRegistrationValue(handler);
```

**Signature**

```ts
declare const readRegistrationValue: (
  handler: RawRouteOptions<string>["handler"],
) => BetterAuthRegistration | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.ts#L35)

## `route-auth.types.ts`

Better Auth identity attached to a raw handler.

**Example**

```ts
const registration: BetterAuthRegistration = {
  kind: "better-auth",
  service: { ref: { kind: "service", id: "auth" } },
};
```

### BetterAuthRegistration (interface)

Better Auth identity attached to a raw handler.

**Example**

```ts
const registration: BetterAuthRegistration = {
  kind: "better-auth",
  service: { ref: { kind: "service", id: "auth" } },
};
```

**Signature**

```ts
export interface BetterAuthRegistration {
  readonly kind: "better-auth";
  readonly service: { readonly ref: { readonly kind: "service"; readonly id: string } };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-auth.types.ts#L4)

## `route-client.ts`

### copyClient

Copies a client policy for synchronous authoring.

**Throws**

TypeError when the policy is invalid.

**Example**

```ts
copyClient({ operation: "query" });
```

**Signature**

```ts
declare const copyClient: (value: unknown) => RouteClientPolicy | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L22)

### copyClientEffect

Copies a client policy through a typed Effect.

**Example**

```ts
Effect.runSync(copyClientEffect({ operation: "query" }));
```

**Signature**

```ts
declare const copyClientEffect: (
  value: unknown,
) => Effect.Effect<RouteClientPolicy | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L12)

### copyClientValue

Copies client policy inside an already observed operation.

**Throws**

RouteInputError for an invalid policy.

**Example**

```ts
copyClientValue({ operation: "query" });
```

**Signature**

```ts
declare const copyClientValue: (value: unknown) => RouteClientPolicy | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L32)

### copyStream

Copies a native stream policy for synchronous authoring.

**Throws**

TypeError when the policy or output schema is incompatible.

**Example**

```ts
copyStream(undefined, output);
```

**Signature**

```ts
declare const copyStream: (
  value: unknown,
  output: StandardSchemaV1,
) => { readonly format: NativeStreamFormat } | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L65)

### copyStreamEffect

Copies a native stream policy through a typed Effect.

**Example**

```ts
Effect.runSync(copyStreamEffect(undefined, output));
```

**Signature**

```ts
declare const copyStreamEffect: (
  value: unknown,
  output: StandardSchemaV1<unknown, unknown>,
) => Effect.Effect<{ readonly format: NativeStreamFormat } | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L53)

### copyStreamValue

Copies stream policy inside an already observed operation.

**Throws**

RouteInputError for invalid stream settings.

**Example**

```ts
copyStreamValue({ format: "sse" }, streamOutput);
```

**Signature**

```ts
declare const copyStreamValue: (
  value: unknown,
  output: StandardSchemaV1,
) => { readonly format: NativeStreamFormat } | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-client.ts#L79)

## `route-definition.ts`

### prepareRouteValue

Validates route options before acquiring an unbound identity.

**Throws**

RouteInputError for invalid route inputs.

**Example**

```ts
prepareRouteValue({ target })("orders.get");
```

**Signature**

```ts
declare const prepareRouteValue: (
  options:
    | FunctionRouteOptions<string, FunctionRefAny, HttpRequestMapping | undefined>
    | RawRouteOptions<string>,
) => (id: string) => RouteDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-definition.ts#L30)

## `route-module.types.ts`

### RouteModuleContract (type alias)

Expected types for a route module's exports, used by generated module validators.
Rejects untyped exports and requires at least one named HTTP method.

**Signature**

```ts
type RouteModuleContract<Module, Parameters extends string = never> = keyof Module extends never
  ? { readonly __relkit_route_method_required: never }
  : {
      readonly [Method in keyof Module]: Method extends RouteModuleMethod
        ? CheckedRoute<Module[Method], Method, Parameters>
        : never;
    };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-module.types.ts#L29)

### RouteModuleMethod (type alias)

Value exports accepted by a filesystem route module.

**Signature**

```ts
type RouteModuleMethod = ServiceRouteMethod | "ALL";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-module.types.ts#L6)

## `route-observability.ts`

### RouteInputError (class)

Marks invalid route authoring input while preserving TypeError compatibility.

**Example**

```ts
throw new RouteInputError("Route target is invalid");
```

**Signature**

```ts
declare class RouteInputError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L11)

### RouteOperation

**Signature**

```ts
declare const RouteOperation: RouteOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L6)

### RouteOperationError (class)

Expected failure from a route authoring Effect.

**Example**

```ts
const error = new RouteOperationError({
  operation: "route.define",
  reason: "Invalid route",
  cause: new TypeError("Invalid route"),
});
```

**Signature**

```ts
declare class RouteOperationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L16)

### RouteTelemetry (class)

Injectable observer for route authoring operations.

**Example**

```ts
Effect.provide(defineRouteEffect(options), RouteTelemetryLive);
```

**Signature**

```ts
declare class RouteTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L24)

### RouteTelemetryLive

Default route observer with an Effect span, counters, and duration histogram.

**Example**

```ts
Effect.runSync(Effect.provide(Effect.void, RouteTelemetryLive));
```

**Signature**

```ts
declare const RouteTelemetryLive: Layer.Layer<RouteTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L37)

### RouteTelemetryService

**Signature**

```ts
declare const RouteTelemetryService: RouteTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L6)

### measureRoute

Records route metrics without creating a second span inside named Effect functions.

**Example**

```ts
measureRoute("route.define", Effect.succeed(route));
```

**Signature**

```ts
declare const measureRoute: <A, E, R>(
  operation: RouteOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L58)

### observeRoute

Observes a route operation with an injectable test observer.

**Example**

```ts
observeRoute("route.define", Effect.succeed(route));
```

**Signature**

```ts
declare const observeRoute: <A, E, R>(
  operation: RouteOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L45)

### routeAttempt

Evaluates a calculation inside an already observed route operation.

**Example**

```ts
yield * routeAttempt("route.define", () => descriptor);
```

**Signature**

```ts
declare const routeAttempt: <A>(
  operation: RouteOperation,
  evaluate: () => A,
) => Effect.Effect<A, RouteOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L107)

### routeIdentity

Acquires an unbound route identity through the caller's IdentityStore Layer.

**Example**

```ts
yield * routeIdentity("middleware.define");
```

**Signature**

```ts
declare const routeIdentity: (
  operation: RouteOperation,
) => Effect.Effect<string, RouteOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L128)

### routeTry

Evaluates synchronous authoring logic inside a typed and observed Effect.

**Example**

```ts
routeTry("route.define", () => descriptor);
```

**Signature**

```ts
declare const routeTry: <A>(
  operation: RouteOperation,
  evaluate: () => A,
) => Effect.Effect<A, RouteOperationError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L94)

### runRouteSync

Runs a synchronous compatibility API and restores its original error.

**Throws**

The original validation error or an unexpected defect.

**Example**

```ts
runRouteSync(Effect.succeed(true));
```

**Signature**

```ts
declare const runRouteSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.ts#L149)

## `route-observability.types.ts`

### RouteOperation (type alias)

Bounded name for a route authoring operation.

**Example**

```ts
const operation: RouteOperation = "route.define";
```

**Signature**

```ts
type RouteOperation =
  | "middleware.define"
  | "middleware.is-descriptor"
  | "middleware.is-path"
  | "route.define"
  | "service-routes.define"
  | "auth.read-registration"
  | "auth.copy-protected"
  | "client.copy"
  | "stream.copy"
  | "options.copy-rate-limit"
  | "options.positive"
  | "options.success-status"
  | "dsl.define-transform"
  | "dsl.is-transform-ref"
  | "dsl.input"
  | "dsl.nested"
  | "dsl.source"
  | "dsl.whole-body"
  | "dsl.constant"
  | "dsl.optional"
  | "dsl.default"
  | "dsl.transform"
  | "dsl.response"
  | "dsl.continue"
  | "dsl.respond"
  | "validation.is-mapping"
  | "validation.assert-mapping"
  | "validation.is-request"
  | "validation.assert-request"
  | "validation.is-response"
  | "validation.assert-response"
  | "validation.is-decision"
  | "validation.is-schema"
  | "validation.assert-schema"
  | "validation.is-status"
  | "validation.is-record";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.types.ts#L6)

### RouteTelemetryService (interface)

Replaceable observer for route operations.

**Example**

```ts
const telemetry: RouteTelemetryService = { observe: (_operation, effect) => effect };
```

**Signature**

```ts
export interface RouteTelemetryService {
  /**
   * Measures an operation without changing its success or failure channel.
   * @param operation - Fixed route operation name.
   * @param effect - Work to observe.
   * @returns The observed Effect with unchanged channels.
   * @example telemetry.observe("route.define", Effect.succeed(route));
   */
  readonly observe: <A, E, R>(
    operation: RouteOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-observability.types.ts#L47)

## `route-options.ts`

### HttpRateLimitKey

**Signature**

```ts
declare const HttpRateLimitKey: HttpRateLimitKey;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L8)

### RouteRateLimit

**Signature**

```ts
declare const RouteRateLimit: RouteRateLimit;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L8)

### copyRateLimit

Copies a route rate-limit policy synchronously.

**Throws**

TypeError for invalid policy fields.

**Example**

```ts
copyRateLimit(undefined);
```

**Signature**

```ts
declare const copyRateLimit: (value: RouteRateLimit | undefined) => RouteRateLimit | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L26)

### copyRateLimitEffect

Copies a rate-limit policy through Effect.

**Example**

```ts
Effect.runSync(copyRateLimitEffect(undefined));
```

**Signature**

```ts
declare const copyRateLimitEffect: (
  value: RouteRateLimit | undefined,
) => Effect.Effect<RouteRateLimit | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L15)

### copyRateLimitValue

Copies a rate limit inside an already observed operation.

**Throws**

RouteInputError for invalid policy fields.

**Example**

```ts
copyRateLimitValue(undefined);
```

**Signature**

```ts
declare const copyRateLimitValue: (value: RouteRateLimit | undefined) => RouteRateLimit | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L36)

### positive

Validates an optional positive integer synchronously.

**Throws**

TypeError for nonpositive or unsafe integers.

**Example**

```ts
positive(5, "timeoutMs");
```

**Signature**

```ts
declare const positive: (value: number | undefined, name: string) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L75)

### positiveEffect

Validates an optional positive integer through Effect.

**Example**

```ts
Effect.runSync(positiveEffect(5, "timeoutMs"));
```

**Signature**

```ts
declare const positiveEffect: (
  value: number | undefined,
  name: string,
) => Effect.Effect<number | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L63)

### positiveValue

Checks an optional positive integer inside an already observed operation.

**Throws**

RouteInputError for invalid integers.

**Example**

```ts
positiveValue(5, "timeoutMs");
```

**Signature**

```ts
declare const positiveValue: (value: number | undefined, name: string) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L86)

### successStatus

Validates an optional HTTP success status synchronously.

**Throws**

TypeError for values outside 200–299.

**Example**

```ts
successStatus(201);
```

**Signature**

```ts
declare const successStatus: (value: number | undefined) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L109)

### successStatusEffect

Validates a success status through Effect.

**Example**

```ts
Effect.runSync(successStatusEffect(201));
```

**Signature**

```ts
declare const successStatusEffect: (
  value: number | undefined,
) => Effect.Effect<number | undefined, RouteOperationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L98)

### successStatusValue

Checks an optional success status inside an already observed operation.

**Throws**

RouteInputError for invalid statuses.

**Example**

```ts
successStatusValue(201);
```

**Signature**

```ts
declare const successStatusValue: (value: number | undefined) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.ts#L119)

## `route-options.types.ts`

### HttpRateLimitKey (type alias)

Scalar request source used for rate-limit keys.

**Example**

```ts
const key: HttpRateLimitKey = http.header("x-api-key");
```

**Signature**

```ts
type HttpRateLimitKey =
  HttpPathMapping | HttpQueryMapping | HttpHeaderMapping | HttpCookieMapping | HttpConstantMapping;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.types.ts#L13)

### RouteRateLimit (interface)

Immutable per-route rate-limit policy.

**Example**

```ts
const policy: RouteRateLimit = { limit: 10, windowMs: 60_000, key: http.header("x-api-key") };
```

**Signature**

```ts
export interface RouteRateLimit {
  readonly limit: number;
  readonly windowMs: number;
  readonly key: HttpRateLimitKey;
  readonly store?: CacheRefAny;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route-options.types.ts#L19)

## `route.types.ts`

### FunctionRouteDescriptor (interface)

Frozen descriptor for a function-backed route.

**Example**

```ts
type Route = FunctionRouteDescriptor<"orders.get">;
```

**Signature**

```ts
export interface FunctionRouteDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
  Request extends HttpRequestMapping | undefined = HttpRequestMapping | undefined,
> extends DescriptorBase<"route", Id> {
  readonly method?: HttpMethod;
  readonly path?: string;
  readonly runtimePaths?: readonly string[];
  readonly target: Target;
  readonly accept?: HttpRequestContentType;
  readonly request?: Request;
  readonly responses?: readonly HttpResponseMapping[];
  readonly successStatus?: number;
  readonly maxBodyBytes?: number;
  readonly rateLimit?: RouteRateLimit;
  readonly timeoutMs?: number;
  readonly client?: RouteClientPolicy;
  readonly stream?: { readonly format: NativeStreamFormat };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L66)

### FunctionRouteOptions (interface)

Authoring options for a function-backed route.

**Example**

```ts
type Options = FunctionRouteOptions<"orders.get", typeof getOrder>;
```

**Signature**

```ts
export interface FunctionRouteOptions<
  Id extends string,
  Target extends FunctionRefAny,
  Request extends HttpRequestMapping | undefined = undefined,
> extends RouteSharedOptions<Id> {
  readonly target: Target;
  readonly handler?: never;
  readonly accept?: HttpRequestContentType;
  readonly request?: Request;
  readonly responses?: readonly HttpResponseMapping[];
  readonly successStatus?: number;
  readonly maxBodyBytes?: number;
  readonly rateLimit?: RouteRateLimit;
  readonly timeoutMs?: number;
  readonly client?: RouteClientPolicy;
  readonly stream?: { readonly format: NativeStreamFormat };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L31)

### NativeStreamFormat (type alias)

Native streaming transport formats.

**Example**

```ts
const format: NativeStreamFormat = "sse";
```

**Signature**

```ts
type NativeStreamFormat = "sse" | "text" | "bytes";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L22)

### RawHttpHandler (type alias)

A raw HTTP handler receiving the incoming Request.

**Example**

```ts
const handler: RawHttpHandler = () => new Response("ok");
```

**Signature**

```ts
type RawHttpHandler = (request: Request) => MaybePromise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L14)

### RawRouteDescriptor (interface)

Frozen descriptor for a raw HTTP route.

**Example**

```ts
type Route = RawRouteDescriptor<"health">;
```

**Signature**

```ts
export interface RawRouteDescriptor<
  Id extends string,
  Handler extends RawHttpHandler = RawHttpHandler,
> extends DescriptorBase<"route", Id> {
  readonly method?: HttpMethod;
  readonly path?: string;
  readonly runtimePaths?: readonly string[];
  readonly raw: true;
  readonly handler: Handler;
  readonly auth?: {
    readonly kind: "better-auth";
    readonly protected: readonly string[];
    readonly service: { readonly ref: { readonly kind: "service"; readonly id: string } };
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L89)

### RawRouteOptions (interface)

Authoring options for a raw HTTP route.

**Example**

```ts
const options: RawRouteOptions<"health"> = { handler: () => new Response("ok") };
```

**Signature**

```ts
export interface RawRouteOptions<
  Id extends string,
  Handler extends RawHttpHandler = RawHttpHandler,
> extends RouteSharedOptions<Id> {
  readonly handler: Handler;
  readonly target?: never;
  readonly auth?: {
    readonly protected?: readonly string[];
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L52)

### RouteClientPolicy (type alias)

Client exposure and operation policy for a route.

**Example**

```ts
const policy: RouteClientPolicy = { operation: "query" };
```

**Signature**

```ts
type RouteClientPolicy = false | { readonly operation?: "query" | "mutation" };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L18)

### RouteDescriptor (type alias)

Union of function-backed and raw route descriptors.

**Example**

```ts
type Route = RouteDescriptor<"orders.get">;
```

**Signature**

```ts
type RouteDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
  Request extends HttpRequestMapping | undefined = HttpRequestMapping | undefined,
> = FunctionRouteDescriptor<Id, Target, Request> | RawRouteDescriptor<Id>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/routes/src/route.types.ts#L108)

---

# Schema API
Source: https://relkit.dev/docs/api/schema

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [z](/docs/api/schema#z)
- [validate](/docs/api/schema#validate)

For configuration and examples, read [Runtime schemas](/docs/learn/concepts/schemas), [requests](/docs/modules/http/requests), [uploads](/docs/modules/http/uploads).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Public imports

- `@relkit/schema` — 56 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                             | Kind  | Import from      | Example                                                                                                                     |
| ------------------------------------------------------------------------------- | ----- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [buildSchemaEffect](/docs/api/schema#buildschemaeffect)                         | Value | `@relkit/schema` | [API example](/docs/api/schema#buildschemaeffect)                                                                           |
| [FileSchema](/docs/api/schema#fileschema-type-alias)                            | Type  | `@relkit/schema` | [API example](/docs/api/schema#fileschema-type-alias)                                                                       |
| [FileSchemaOptions](/docs/api/schema#fileschemaoptions-interface)               | Type  | `@relkit/schema` | [API example](/docs/api/schema#fileschemaoptions-interface)                                                                 |
| [getJsonSchema](/docs/api/schema#getjsonschema-1)                               | Value | `@relkit/schema` | [API example](/docs/api/schema#getjsonschema-1)                                                                             |
| [getJsonSchemaEffect](/docs/api/schema#getjsonschemaeffect-1)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#getjsonschemaeffect-1)                                                                       |
| [getSchemaMetadata](/docs/api/schema#getschemametadata-1)                       | Value | `@relkit/schema` | [API example](/docs/api/schema#getschemametadata-1)                                                                         |
| [getSchemaMetadataEffect](/docs/api/schema#getschemametadataeffect-1)           | Value | `@relkit/schema` | [API example](/docs/api/schema#getschemametadataeffect-1)                                                                   |
| [InferInput](/docs/api/schema#inferinput-type-alias-1)                          | Type  | `@relkit/schema` | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/types/authoring-boundaries.ts#L43)                       |
| [InferOutput](/docs/api/schema#inferoutput-type-alias-1)                        | Type  | `@relkit/schema` | [Source example](https://github.com/rel-kit/relkit/blob/main/integrations/packages/langchain/tests/test-native-tool.ts#L11) |
| [isJsonSchemaAvailable](/docs/api/schema#isjsonschemaavailable-1)               | Value | `@relkit/schema` | [API example](/docs/api/schema#isjsonschemaavailable-1)                                                                     |
| [isSchemaTransformed](/docs/api/schema#isschematransformed-1)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#isschematransformed-1)                                                                       |
| [isSchemaTransformedEffect](/docs/api/schema#isschematransformedeffect-1)       | Value | `@relkit/schema` | [API example](/docs/api/schema#isschematransformedeffect-1)                                                                 |
| [JSON_SCHEMA_UNAVAILABLE](/docs/api/schema#json_schema_unavailable-1)           | Value | `@relkit/schema` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/schema/tests/schema.test.ts#L50)                      |
| [JsonSchema](/docs/api/schema#jsonschema-type-alias)                            | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschema-type-alias)                                                                       |
| [JsonSchemaAvailable](/docs/api/schema#jsonschemaavailable-interface)           | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemaavailable-interface)                                                               |
| [JsonSchemaDirection](/docs/api/schema#jsonschemadirection-type-alias)          | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemadirection-type-alias)                                                              |
| [JsonSchemaFactory](/docs/api/schema#jsonschemafactory-type-alias)              | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemafactory-type-alias)                                                                |
| [JsonSchemaOptions](/docs/api/schema#jsonschemaoptions-interface)               | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemaoptions-interface)                                                                 |
| [JsonSchemaResult](/docs/api/schema#jsonschemaresult-type-alias)                | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemaresult-type-alias)                                                                 |
| [JsonSchemaUnavailable](/docs/api/schema#jsonschemaunavailable-interface)       | Type  | `@relkit/schema` | [API example](/docs/api/schema#jsonschemaunavailable-interface)                                                             |
| [JsonSchemaUnavailableError](/docs/api/schema#jsonschemaunavailableerror-class) | Value | `@relkit/schema` | [API example](/docs/api/schema#jsonschemaunavailableerror-class)                                                            |
| [NumberSchema](/docs/api/schema#numberschema-interface)                         | Type  | `@relkit/schema` | [API example](/docs/api/schema#numberschema-interface)                                                                      |
| [RelkitSchema](/docs/api/schema#relkitschema-interface)                         | Type  | `@relkit/schema` | [API example](/docs/api/schema#relkitschema-interface)                                                                      |
| [Schema](/docs/api/schema#schema-interface)                                     | Type  | `@relkit/schema` | [API example](/docs/api/schema#schema-interface)                                                                            |
| [SchemaAsyncError](/docs/api/schema#schemaasyncerror-class)                     | Value | `@relkit/schema` | [API example](/docs/api/schema#schemaasyncerror-class)                                                                      |
| [SchemaBuilderError](/docs/api/schema#schemabuildererror-class)                 | Value | `@relkit/schema` | [API example](/docs/api/schema#schemabuildererror-class)                                                                    |
| [SchemaExecutionError](/docs/api/schema#schemaexecutionerror-class)             | Value | `@relkit/schema` | [API example](/docs/api/schema#schemaexecutionerror-class)                                                                  |
| [SchemaInvalidError](/docs/api/schema#schemainvaliderror-class)                 | Value | `@relkit/schema` | [API example](/docs/api/schema#schemainvaliderror-class)                                                                    |
| [SchemaIssuesError](/docs/api/schema#schemaissueserror-class)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#schemaissueserror-class)                                                                     |
| [SchemaProjector](/docs/api/schema#schemaprojector-class)                       | Value | `@relkit/schema` | [API example](/docs/api/schema#schemaprojector-class)                                                                       |
| [SchemaProjectorLive](/docs/api/schema#schemaprojectorlive-1)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#schemaprojectorlive-1)                                                                       |
| [SchemaProjectorService](/docs/api/schema#schemaprojectorservice-interface)     | Type  | `@relkit/schema` | [API example](/docs/api/schema#schemaprojectorservice-interface)                                                            |
| [SchemaTelemetry](/docs/api/schema#schematelemetry-class)                       | Value | `@relkit/schema` | [API example](/docs/api/schema#schematelemetry-class)                                                                       |
| [SchemaTelemetryLive](/docs/api/schema#schematelemetrylive-1)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#schematelemetrylive-1)                                                                       |
| [SchemaTelemetryService](/docs/api/schema#schematelemetryservice-interface)     | Type  | `@relkit/schema` | [API example](/docs/api/schema#schematelemetryservice-interface)                                                            |
| [SchemaValidationError](/docs/api/schema#schemavalidationerror-class)           | Value | `@relkit/schema` | [API example](/docs/api/schema#schemavalidationerror-class)                                                                 |
| [SchemaValidator](/docs/api/schema#schemavalidator-class)                       | Value | `@relkit/schema` | [API example](/docs/api/schema#schemavalidator-class)                                                                       |
| [SchemaValidatorLive](/docs/api/schema#schemavalidatorlive-1)                   | Value | `@relkit/schema` | [API example](/docs/api/schema#schemavalidatorlive-1)                                                                       |
| [SchemaValidatorService](/docs/api/schema#schemavalidatorservice-interface)     | Type  | `@relkit/schema` | [API example](/docs/api/schema#schemavalidatorservice-interface)                                                            |
| [StandardFailure](/docs/api/schema#standardfailure-interface)                   | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardfailure-interface)                                                                   |
| [StandardIssue](/docs/api/schema#standardissue-interface)                       | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardissue-interface)                                                                     |
| [StandardJSONSchemaV1](/docs/api/schema#standardjsonschemav1-interface)         | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardjsonschemav1-interface)                                                              |
| [StandardPathSegment](/docs/api/schema#standardpathsegment-type-alias)          | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardpathsegment-type-alias)                                                              |
| [StandardResult](/docs/api/schema#standardresult-type-alias)                    | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardresult-type-alias)                                                                   |
| [StandardSchemaOptions](/docs/api/schema#standardschemaoptions-interface)       | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardschemaoptions-interface)                                                             |
| [StandardSchemaTypes](/docs/api/schema#standardschematypes-interface)           | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardschematypes-interface)                                                               |
| [StandardSchemaV1](/docs/api/schema#standardschemav1-interface)                 | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardschemav1-interface)                                                                  |
| [StandardSuccess](/docs/api/schema#standardsuccess-interface)                   | Type  | `@relkit/schema` | [API example](/docs/api/schema#standardsuccess-interface)                                                                   |
| [StringSchema](/docs/api/schema#stringschema-interface)                         | Type  | `@relkit/schema` | [API example](/docs/api/schema#stringschema-interface)                                                                      |
| [toJsonSchema](/docs/api/schema#tojsonschema-1)                                 | Value | `@relkit/schema` | [API example](/docs/api/schema#tojsonschema-1)                                                                              |
| [validate](/docs/api/schema#validate-1)                                         | Value | `@relkit/schema` | [API example](/docs/api/schema#validate-1)                                                                                  |
| [validateEffect](/docs/api/schema#validateeffect-1)                             | Value | `@relkit/schema` | [API example](/docs/api/schema#validateeffect-1)                                                                            |
| [validateSync](/docs/api/schema#validatesync-1)                                 | Value | `@relkit/schema` | [API example](/docs/api/schema#validatesync-1)                                                                              |
| [validateSyncEffect](/docs/api/schema#validatesynceffect-1)                     | Value | `@relkit/schema` | [API example](/docs/api/schema#validatesynceffect-1)                                                                        |
| [z](/docs/api/schema#z)                                                         | Value | `@relkit/schema` | [API example](/docs/api/schema#z)                                                                                           |
| [ZBuilder](/docs/api/schema#zbuilder-interface)                                 | Type  | `@relkit/schema` | [API example](/docs/api/schema#zbuilder-interface)                                                                          |

## `builder-composites.ts`

### arraySchema

Builds an array validator from one item schema.

**Example**

```ts
arraySchema(z.number());
```

**Signature**

```ts
declare const arraySchema: <S extends AnySchema>(schema: S) => Schema<InputOf<S>[], OutputOf<S>[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.ts#L65)

### objectSchema

Builds an object validator from named child schemas.

**Example**

```ts
objectSchema({ id: z.string() });
```

**Signature**

```ts
declare const objectSchema: <S extends Shape>(shape: S) => Schema<ObjectInput<S>, ObjectOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.ts#L25)

### unionSchema

Builds a nonempty union with first-success precedence.

**Example**

```ts
unionSchema([z.string(), z.number()]);
```

**Signature**

```ts
declare const unionSchema: <S extends SchemaTuple>(
  schemas: S,
) => Schema<InputOf<S[number]>, OutputOf<S[number]>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.ts#L100)

## `builder-composites.types.ts`

### AnySchema (type alias)

Any compatible validator accepted by a composite builder.

**Example**

```ts
const child: AnySchema = z.string();
```

**Signature**

```ts
type AnySchema = StandardSchemaV1;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L7)

### InputOf (type alias)

Accepted input of a child validator.

**Example**

```ts
type Input = InputOf<typeof schema>;
```

**Signature**

```ts
type InputOf<S extends AnySchema> = InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L17)

### ObjectInput (type alias)

Object input with optional keys inferred from child schemas.

**Example**

```ts
type Input = ObjectInput<{ id: typeof idSchema }>;
```

**Signature**

```ts
type ObjectInput<S extends Shape> = {
  [K in RequiredInputKeys<S>]: InputOf<S[K]>;
} & {
  [K in OptionalInputKeys<S>]?: Exclude<InputOf<S[K]>, undefined>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L35)

### ObjectOutput (type alias)

Object output with optional keys inferred from child schemas.

**Example**

```ts
type Output = ObjectOutput<{ id: typeof idSchema }>;
```

**Signature**

```ts
type ObjectOutput<S extends Shape> = {
  [K in RequiredOutputKeys<S>]: OutputOf<S[K]>;
} & {
  [K in OptionalOutputKeys<S>]?: Exclude<OutputOf<S[K]>, undefined>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L44)

### OutputOf (type alias)

Validated output of a child validator.

**Example**

```ts
type Output = OutputOf<typeof schema>;
```

**Signature**

```ts
type OutputOf<S extends AnySchema> = InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L22)

### SchemaTuple (type alias)

Nonempty tuple of union members, preserving declaration order.

**Example**

```ts
const members: SchemaTuple = [z.string(), z.number()];
```

**Signature**

```ts
type SchemaTuple = readonly [AnySchema, ...AnySchema[]];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L53)

### Shape (type alias)

Named child validators for an object schema.

**Example**

```ts
const shape: Shape = { id: z.string() };
```

**Signature**

```ts
type Shape = Record<string, AnySchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-composites.types.ts#L12)

## `builder-effect.ts`

### SchemaBuilderError (class)

Tagged failure when a schema builder rejects options or its dependencies throw.
The original exception remains available in `cause`.

**Example**

```ts
Effect.catchTag("SchemaBuilderError", (error) => Effect.succeed(error.cause));
```

**Signature**

```ts
declare class SchemaBuilderError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-effect.ts#L10)

### buildSchema

Runs a synchronous schema builder and preserves its original error.

**Throws**

The original construction error.

**Example**

```ts
buildSchema("builder.string", () => z.string());
```

**Signature**

```ts
declare const buildSchema: <A>(operation: SchemaOperation, build: () => A) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-effect.ts#L46)

### buildSchemaEffect

Constructs a schema inside an observed Effect.

**Example**

```ts
Effect.runSync(buildSchemaEffect("builder.string", () => z.string()));
```

**Signature**

```ts
declare const buildSchemaEffect: <A>(
  operation: SchemaOperation,
  build: () => A,
) => Effect.Effect<A, SchemaBuilderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-effect.ts#L25)

## `builder-refinements.ts`

### numberSchema

Builds a finite-number schema with numeric refinements.

**Example**

```ts
numberSchema().int().parse(2);
```

**Signature**

```ts
declare const numberSchema: () => NumberSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-refinements.ts#L29)

### stringSchema

Builds a string schema with format and length refinements.

**Example**

```ts
stringSchema().min(2).parse("ok");
```

**Signature**

```ts
declare const stringSchema: () => StringSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-refinements.ts#L13)

## `builder-refinements.types.ts`

### NumberSchema (interface)

Finite-number schema with range and integer refinement methods.

**Example**

```ts
const schema: NumberSchema = z.number().int();
```

**Signature**

```ts
export interface NumberSchema extends Schema<number, number> {
  /**
   * Requires an inclusive minimum.
   * @param value - Minimum value.
   * @param message - Optional issue text.
   * @returns A refined number schema.
   * @example z.number().min(1);
   */
  min(value: number, message?: string): NumberSchema;
  /**
   * Requires an inclusive maximum.
   * @param value - Maximum value.
   * @param message - Optional issue text.
   * @returns A refined number schema.
   * @example z.number().max(10);
   */
  max(value: number, message?: string): NumberSchema;
  /**
   * Requires an integer.
   * @param message - Optional issue text.
   * @returns An integer schema.
   * @example z.number().int();
   */
  int(message?: string): NumberSchema;
  /**
   * Requires a value above zero.
   * @param message - Optional issue text.
   * @returns A positive number schema.
   * @example z.number().positive();
   */
  positive(message?: string): NumberSchema;
  /**
   * Requires a value of zero or greater.
   * @param message - Optional issue text.
   * @returns A nonnegative number schema.
   * @example z.number().nonnegative();
   */
  nonnegative(message?: string): NumberSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-refinements.types.ts#L51)

### StringSchema (interface)

String schema with length and format refinement methods.

**Example**

```ts
const schema: StringSchema = z.string().min(1);
```

**Signature**

```ts
export interface StringSchema extends Schema<string, string> {
  /**
   * Requires a minimum string length.
   * @param length - Minimum length.
   * @param message - Optional issue text.
   * @returns A refined string schema.
   * @example z.string().min(2);
   */
  min(length: number, message?: string): StringSchema;
  /**
   * Requires a maximum string length.
   * @param length - Maximum length.
   * @param message - Optional issue text.
   * @returns A refined string schema.
   * @example z.string().max(8);
   */
  max(length: number, message?: string): StringSchema;
  /**
   * Requires a UUID string.
   * @param message - Optional issue text.
   * @returns A UUID string schema.
   * @example z.string().uuid();
   */
  uuid(message?: string): StringSchema;
  /**
   * Requires a parseable datetime string.
   * @param message - Optional issue text.
   * @returns A datetime string schema.
   * @example z.string().datetime();
   */
  datetime(message?: string): StringSchema;
  /**
   * Requires an email address string.
   * @param message - Optional issue text.
   * @returns An email string schema.
   * @example z.string().email();
   */
  email(message?: string): StringSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder-refinements.types.ts#L7)

## `builder.ts`

### z

Builds RELKIT Standard Schema validators with familiar composition helpers.

**Example**

```ts
import { z } from "@relkit/app/schema";

const order = z.object({ id: z.string(), quantity: z.number().int().positive() });
order.parse({ id: "order-1", quantity: 2 });
```

**Signature**

```ts
declare const z: ZBuilder;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L36)

Since v0.1.0

### AnySchema

**Signature**

```ts
declare const AnySchema: AnySchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L11)

### InputOf

**Signature**

```ts
declare const InputOf: InputOf<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L12)

### NumberSchema

**Signature**

```ts
declare const NumberSchema: NumberSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L13)

### ObjectInput

**Signature**

```ts
declare const ObjectInput: ObjectInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L14)

### ObjectOutput

**Signature**

```ts
declare const ObjectOutput: ObjectOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L15)

### OutputOf

**Signature**

```ts
declare const OutputOf: OutputOf<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L16)

### SchemaTuple

**Signature**

```ts
declare const SchemaTuple: SchemaTuple;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L17)

### Shape

**Signature**

```ts
declare const Shape: Shape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L18)

### StringSchema

**Signature**

```ts
declare const StringSchema: StringSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L19)

### ZBuilder

**Signature**

```ts
declare const ZBuilder: ZBuilder;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.ts#L20)

## `builder.types.ts`

### AnySchema

**Signature**

```ts
declare const AnySchema: AnySchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L15)

### InputOf

**Signature**

```ts
declare const InputOf: InputOf<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L16)

### NumberSchema

**Signature**

```ts
declare const NumberSchema: NumberSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L23)

### ObjectInput

**Signature**

```ts
declare const ObjectInput: ObjectInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L17)

### ObjectOutput

**Signature**

```ts
declare const ObjectOutput: ObjectOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L18)

### OutputOf

**Signature**

```ts
declare const OutputOf: OutputOf<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L19)

### SchemaTuple

**Signature**

```ts
declare const SchemaTuple: SchemaTuple;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L20)

### Shape

**Signature**

```ts
declare const Shape: Shape;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L21)

### StringSchema

**Signature**

```ts
declare const StringSchema: StringSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L23)

### ZBuilder (interface)

Builder methods used to compose Standard Schema validators.

**Example**

```ts
const builder: ZBuilder = z;
```

**Signature**

```ts
export interface ZBuilder {
  /**
   * Builds a string validator.
   * @returns A string schema with refinement methods.
   * @example z.string().min(1);
   */
  string(): StringSchema;
  /**
   * Builds a finite-number validator.
   * @returns A number schema with refinement methods.
   * @example z.number().int();
   */
  number(): NumberSchema;
  /**
   * Builds a boolean validator.
   * @returns A boolean schema.
   * @example z.boolean().parse(true);
   */
  boolean(): Schema<boolean, boolean>;
  /**
   * Builds a validator accepting any input without changing it.
   * @returns An unknown-value schema.
   * @example z.unknown().parse({ name: "Ada" });
   */
  unknown(): Schema<unknown, unknown>;
  /**
   * Builds an unrestricted value validator.
   * @returns An unknown-value schema.
   * @example z.any().parse(null);
   */
  any(): Schema<unknown, unknown>;
  /**
   * Builds a null validator.
   * @returns A null schema.
   * @example z.null().parse(null);
   */
  null(): Schema<null, null>;
  /**
   * Builds a buffered Web File validator.
   * @param options - Byte and media-type constraints.
   * @returns A File schema.
   * @example z.file({ maxBytes: 1024 });
   */
  file(options?: FileSchemaOptions): FileSchema;
  /**
   * Builds an undefined validator.
   * @returns An undefined schema.
   * @example z.undefined().parse(undefined);
   */
  undefined(): Schema<undefined, undefined>;
  /**
   * Builds a void-result validator.
   * @returns An undefined schema.
   * @example z.void().parse(undefined);
   */
  void(): Schema<undefined, undefined>;
  /**
   * Builds an exact-value validator.
   * @param value - Literal value to require.
   * @returns A literal schema.
   * @example z.literal("ready").parse("ready");
   */
  literal<T extends string | number | boolean | null | undefined>(value: T): Schema<T, T>;
  /**
   * Builds a named object validator.
   * @param shape - Child schemas by property name.
   * @returns An object schema with inferred input and output.
   * @example z.object({ id: z.string() });
   */
  object<S extends Shape>(shape: S): Schema<ObjectInput<S>, ObjectOutput<S>>;
  /**
   * Builds an array validator.
   * @param schema - Child item schema.
   * @returns An array schema with inferred item types.
   * @example z.array(z.number());
   */
  array<S extends AnySchema>(schema: S): Schema<InputOf<S>[], OutputOf<S>[]>;
  /**
   * Builds a nonempty union validator.
   * @param schemas - Member schemas in precedence order.
   * @returns A union schema with inferred member types.
   * @example z.union([z.string(), z.number()]);
   */
  union<S extends SchemaTuple>(schemas: S): Schema<InputOf<S[number]>, OutputOf<S[number]>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/builder.types.ts#L29)

## `file.ts`

### FileSchema

**Signature**

```ts
declare const FileSchema: FileSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/file.ts#L5)

### FileSchemaOptions

**Signature**

```ts
declare const FileSchemaOptions: FileSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/file.ts#L5)

### fileSchema

Builds a buffered Web File validator with binary projection metadata.

**Throws**

TypeError for invalid options in this synchronous adapter.

**Example**

```ts
fileSchema({ maxBytes: 1024, mediaTypes: ["image/*"] });
```

**Signature**

```ts
declare const fileSchema: (options?: FileSchemaOptions) => FileSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/file.ts#L14)

## `file.types.ts`

### FileSchema (type alias)

A schema that accepts and returns a Web File.

**Example**

```ts
const schema: FileSchema = z.file();
```

**Signature**

```ts
type FileSchema = Schema<File, File>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/file.types.ts#L16)

### FileSchemaOptions (interface)

Constraints for a buffered Web File validator.

**Example**

```ts
const options: FileSchemaOptions = { maxBytes: 1024, mediaTypes: ["image/*"] };
```

**Signature**

```ts
export interface FileSchemaOptions {
  readonly maxBytes?: number;
  readonly mediaTypes?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/file.types.ts#L7)

## `index.ts`

### FileSchema

**Signature**

```ts
declare const FileSchema: FileSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L4)

### FileSchemaOptions

**Signature**

```ts
declare const FileSchemaOptions: FileSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L4)

### InferInput

**Signature**

```ts
declare const InferInput: InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L48)

### InferOutput

**Signature**

```ts
declare const InferOutput: InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L49)

### JSON_SCHEMA_UNAVAILABLE

**Signature**

```ts
declare const JSON_SCHEMA_UNAVAILABLE: "RELKIT_SCHEMA_UNAVAILABLE";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L36)

### JsonSchema

**Signature**

```ts
declare const JsonSchema: JsonSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L39)

### JsonSchemaAvailable

**Signature**

```ts
declare const JsonSchemaAvailable: JsonSchemaAvailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L40)

### JsonSchemaDirection

**Signature**

```ts
declare const JsonSchemaDirection: SchemaProjectionDirection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L41)

### JsonSchemaFactory

**Signature**

```ts
declare const JsonSchemaFactory: JsonSchemaFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L42)

### JsonSchemaOptions

**Signature**

```ts
declare const JsonSchemaOptions: JsonSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L43)

### JsonSchemaResult

**Signature**

```ts
declare const JsonSchemaResult: JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L44)

### JsonSchemaUnavailable

**Signature**

```ts
declare const JsonSchemaUnavailable: JsonSchemaUnavailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L45)

### JsonSchemaUnavailableError

**Signature**

```ts
declare const JsonSchemaUnavailableError: typeof JsonSchemaUnavailableError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L18)

### NumberSchema

**Signature**

```ts
declare const NumberSchema: NumberSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L3)

### RelkitSchema

**Signature**

```ts
declare const RelkitSchema: RelkitSchema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L60)

### Schema

**Signature**

```ts
declare const Schema: Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L50)

### SchemaAsyncError

**Signature**

```ts
declare const SchemaAsyncError: typeof SchemaAsyncError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L7)

### SchemaBuilderError

**Signature**

```ts
declare const SchemaBuilderError: typeof SchemaBuilderError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L2)

### SchemaExecutionError

**Signature**

```ts
declare const SchemaExecutionError: typeof SchemaExecutionError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L8)

### SchemaInvalidError

**Signature**

```ts
declare const SchemaInvalidError: typeof SchemaInvalidError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L9)

### SchemaIssuesError

**Signature**

```ts
declare const SchemaIssuesError: typeof SchemaIssuesError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L10)

### SchemaProjector

**Signature**

```ts
declare const SchemaProjector: typeof SchemaProjector;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L19)

### SchemaProjectorLive

**Signature**

```ts
declare const SchemaProjectorLive: Layer<SchemaProjector, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L20)

### SchemaProjectorService

**Signature**

```ts
declare const SchemaProjectorService: SchemaProjectorService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L23)

### SchemaTelemetry

**Signature**

```ts
declare const SchemaTelemetry: typeof SchemaTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L24)

### SchemaTelemetryLive

**Signature**

```ts
declare const SchemaTelemetryLive: Layer<SchemaTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L24)

### SchemaTelemetryService

**Signature**

```ts
declare const SchemaTelemetryService: SchemaTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L25)

### SchemaValidationError

**Signature**

```ts
declare const SchemaValidationError: typeof SchemaValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L5)

### SchemaValidator

**Signature**

```ts
declare const SchemaValidator: typeof SchemaValidator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L11)

### SchemaValidatorLive

**Signature**

```ts
declare const SchemaValidatorLive: Layer<SchemaValidator, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L12)

### SchemaValidatorService

**Signature**

```ts
declare const SchemaValidatorService: SchemaValidatorService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L16)

### StandardFailure

**Signature**

```ts
declare const StandardFailure: StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L51)

### StandardIssue

**Signature**

```ts
declare const StandardIssue: StandardIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L52)

### StandardJSONSchemaV1

**Signature**

```ts
declare const StandardJSONSchemaV1: StandardJSONSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L58)

### StandardPathSegment

**Signature**

```ts
declare const StandardPathSegment: StandardPathSegment;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L53)

### StandardResult

**Signature**

```ts
declare const StandardResult: StandardResult<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L54)

### StandardSchemaOptions

**Signature**

```ts
declare const StandardSchemaOptions: StandardSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L55)

### StandardSchemaTypes

**Signature**

```ts
declare const StandardSchemaTypes: StandardSchemaTypes<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L56)

### StandardSchemaV1

**Signature**

```ts
declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L57)

### StandardSuccess

**Signature**

```ts
declare const StandardSuccess: StandardSuccess<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L59)

### StringSchema

**Signature**

```ts
declare const StringSchema: StringSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L3)

### ZBuilder

**Signature**

```ts
declare const ZBuilder: ZBuilder;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L3)

### buildSchemaEffect

**Signature**

```ts
declare const buildSchemaEffect: <A>(
  operation: SchemaOperation,
  build: () => A,
) => Effect<A, SchemaBuilderError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L2)

### getJsonSchema

**Signature**

```ts
declare const getJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L33)

### getJsonSchemaEffect

**Signature**

```ts
declare const getJsonSchemaEffect: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => Effect<JsonSchema, JsonSchemaUnavailableError, SchemaProjector>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L21)

### getSchemaMetadata

**Signature**

```ts
declare const getSchemaMetadata: (schema: StandardSchemaV1) => SchemaMetadata | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L27)

### getSchemaMetadataEffect

**Signature**

```ts
declare const getSchemaMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect<SchemaMetadata | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L28)

### isJsonSchemaAvailable

**Signature**

```ts
declare const isJsonSchemaAvailable: (result: JsonSchemaResult) => result is JsonSchemaAvailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L34)

### isSchemaTransformed

**Signature**

```ts
declare const isSchemaTransformed: (schema: StandardSchemaV1) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L29)

### isSchemaTransformedEffect

**Signature**

```ts
declare const isSchemaTransformedEffect: (schema: StandardSchemaV1) => Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L30)

### toJsonSchema

**Signature**

```ts
declare const toJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L35)

### validate

**Signature**

```ts
declare const validate: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>> | Promise<StandardResult<InferOutput<S>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L5)

### validateEffect

**Signature**

```ts
declare const validateEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L13)

### validateSync

**Signature**

```ts
declare const validateSync: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L5)

### validateSyncEffect

**Signature**

```ts
declare const validateSyncEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError | SchemaAsyncError,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L14)

### z

**Signature**

```ts
declare const z: ZBuilder;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/index.ts#L1)

## `json-schema-effect.ts`

### JsonSchemaUnavailableError (class)

Tagged failure for an unavailable or invalid JSON Schema projection.

**Example**

```ts
Effect.catchTag("JsonSchemaUnavailableError", (error) => Effect.succeed(error.reason));
```

**Signature**

```ts
declare class JsonSchemaUnavailableError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-effect.ts#L13)

### SchemaProjector (class)

Injectable JSON Schema projection boundary.

**Example**

```ts
Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive);
```

**Signature**

```ts
declare class SchemaProjector
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-effect.ts#L26)

### SchemaProjectorLive

Live JSON Schema projector using registered schema metadata and hooks.

**Example**

```ts
Effect.runSync(Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive));
```

**Signature**

```ts
declare const SchemaProjectorLive: Layer.Layer<SchemaProjector, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-effect.ts#L34)

### getJsonSchemaEffect

Projects a validator into canonical JSON Schema with typed failures.

**Example**

```ts
Effect.runSync(Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive));
```

**Signature**

```ts
declare const getJsonSchemaEffect: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => Effect.Effect<JsonSchema, JsonSchemaUnavailableError, SchemaProjector>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-effect.ts#L45)

## `json-schema-effect.types.ts`

### SchemaProjectorService (interface)

Injectable boundary for a schema's JSON projection hook.
Test Layers can substitute projection without a third-party schema package.

**Example**

```ts
Layer.succeed(SchemaProjector, { projection: () => () => ({ type: "string" }) });
```

**Signature**

```ts
export interface SchemaProjectorService {
  /**
   * Selects a directional or legacy projection hook.
   * @param schema - Compatible schema to inspect.
   * @param direction - Input, output, or legacy projection.
   * @returns A projection factory when the schema exposes one.
   * @example projector.projection(z.string(), "input");
   */
  readonly projection: (
    schema: StandardSchemaV1,
    direction: JsonSchemaDirection | "legacy",
  ) => JsonSchemaFactory | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-effect.types.ts#L9)

## `json-schema-inspection.ts`

### getSchemaProjection

Finds a deterministic projection hook without executing it.

**Example**

```ts
getSchemaProjection(z.string(), "input");
```

**Signature**

```ts
declare const getSchemaProjection: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => JsonSchemaFactory | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.ts#L45)

### getSchemaProjectionEffect

Finds a deterministic projection hook inside Effect.

**Example**

```ts
Effect.runSync(getSchemaProjectionEffect(z.string(), "input"));
```

**Signature**

```ts
declare const getSchemaProjectionEffect: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => Effect.Effect<JsonSchemaFactory | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.ts#L15)

### isSchemaOptional

Checks whether a schema accepts an omitted property.

**Example**

```ts
isSchemaOptional(z.string().optional());
```

**Signature**

```ts
declare const isSchemaOptional: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.ts#L73)

### isSchemaOptionalEffect

Checks schema optionality inside Effect.

**Example**

```ts
Effect.runSync(isSchemaOptionalEffect(z.string().optional()));
```

**Signature**

```ts
declare const isSchemaOptionalEffect: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.ts#L59)

## `json-schema-inspection.types.ts`

### RelkitProjectable (type alias)

RELKIT extension hook shapes for directional JSON projections.

**Example**

```ts
const projection = (schema as RelkitProjectable).relkit?.inputJsonSchema;
```

**Signature**

```ts
type RelkitProjectable = StandardSchemaV1 & {
  readonly relkit?: {
    readonly jsonSchema?: JsonSchemaFactory;
    readonly inputJsonSchema?: JsonSchemaFactory;
    readonly outputJsonSchema?: JsonSchemaFactory;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.types.ts#L8)

### StandardProjectable (type alias)

Standard JSON Schema extension hook shapes for compatible schemas.

**Example**

```ts
const hook = (schema["~standard"] as StandardProjectable).jsonSchema?.input;
```

**Signature**

```ts
type StandardProjectable = StandardSchemaV1["~standard"] & {
  readonly jsonSchema?: {
    readonly input?: (options: { readonly target: "draft-2020-12" }) => Record<string, unknown>;
    readonly output?: (options: { readonly target: "draft-2020-12" }) => Record<string, unknown>;
  };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema-inspection.types.ts#L20)

## `json-schema.ts`

### JSON_SCHEMA_UNAVAILABLE

Stable code for unavailable deterministic JSON Schema projections.

**Signature**

```ts
declare const JSON_SCHEMA_UNAVAILABLE: "RELKIT_SCHEMA_UNAVAILABLE";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L13)

### JsonSchema

**Signature**

```ts
declare const JsonSchema: JsonSchema;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L17)

### JsonSchemaAvailable

**Signature**

```ts
declare const JsonSchemaAvailable: JsonSchemaAvailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L18)

### JsonSchemaDirection

**Signature**

```ts
declare const JsonSchemaDirection: SchemaProjectionDirection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L19)

### JsonSchemaFactory

**Signature**

```ts
declare const JsonSchemaFactory: JsonSchemaFactory;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L20)

### JsonSchemaOptions

**Signature**

```ts
declare const JsonSchemaOptions: JsonSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L21)

### JsonSchemaResult

**Signature**

```ts
declare const JsonSchemaResult: JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L22)

### JsonSchemaUnavailable

**Signature**

```ts
declare const JsonSchemaUnavailable: JsonSchemaUnavailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L23)

### JsonSchemaValueError (class)

Tagged failure for non-JSON projection data.
The original validation exception remains in `cause`.

**Example**

```ts
Effect.catchTag("JsonSchemaValueError", (error) => Effect.succeed(error.cause));
```

**Signature**

```ts
declare class JsonSchemaValueError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L85)

### getJsonSchema

Produces a canonical JSON Schema or an unavailable result.

**Example**

```ts
getJsonSchema(z.string());
```

**Signature**

```ts
declare const getJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L33)

### getSchemaProjection

**Signature**

```ts
declare const getSchemaProjection: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => JsonSchemaFactory | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L14)

### isJsonSchemaAvailable

Narrows a successful projection result.

**Example**

```ts
isJsonSchemaAvailable(getJsonSchema(z.string()));
```

**Signature**

```ts
declare const isJsonSchemaAvailable: (result: JsonSchemaResult) => result is JsonSchemaAvailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L62)

### isJsonSchemaAvailableEffect

Checks projection availability inside Effect.

**Example**

```ts
Effect.runSync(isJsonSchemaAvailableEffect(getJsonSchema(z.string())));
```

**Signature**

```ts
declare const isJsonSchemaAvailableEffect: (result: JsonSchemaResult) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L72)

### isSchemaOptional

**Signature**

```ts
declare const isSchemaOptional: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L14)

### sortJsonValue

Canonicalizes JSON-safe projection data and preserves TypeError behavior.

**Throws**

TypeError for unsupported data.

**Example**

```ts
sortJsonValue({ b: 2, a: 1 }, "$", undefined);
```

**Signature**

```ts
declare const sortJsonValue: (value: unknown, path: string, key: string | undefined) => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L117)

### sortJsonValueEffect

Canonicalizes JSON-safe projection data inside Effect.

**Example**

```ts
Effect.runSync(sortJsonValueEffect({ b: 2, a: 1 }, "$", undefined));
```

**Signature**

```ts
declare const sortJsonValueEffect: (
  value: unknown,
  path: string,
  key: string | undefined,
) => Effect.Effect<JsonValue, JsonSchemaValueError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L97)

### toJsonSchema

Alias for callers that describe projection as a conversion.

**Example**

```ts
toJsonSchema(z.string());
```

**Signature**

```ts
declare const toJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.ts#L54)

## `json-schema.types.ts`

### JsonSchema (type alias)

A deterministic JSON Schema document.

**Example**

```ts
const document: JsonSchema = { type: "string" };
```

**Signature**

```ts
type JsonSchema = { readonly [key: string]: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L9)

### JsonSchemaAvailable (interface)

A successful JSON Schema projection.

**Example**

```ts
const available: JsonSchemaAvailable = { ok: true, schema: { type: "string" } };
```

**Signature**

```ts
export interface JsonSchemaAvailable {
  readonly ok: true;
  readonly schema: JsonSchema;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L14)

### JsonSchemaDirection (type alias)

Projection direction accepted by getJsonSchema.

**Example**

```ts
const direction: JsonSchemaDirection = "input";
```

**Signature**

```ts
type JsonSchemaDirection = SchemaProjectionDirection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L41)

### JsonSchemaFactory (type alias)

Factory for a JSON-safe schema value.

**Example**

```ts
const projection: JsonSchemaFactory = () => ({ type: "string" });
```

**Signature**

```ts
type JsonSchemaFactory = () => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L36)

### JsonSchemaOptions (interface)

Options for a JSON Schema projection.

**Example**

```ts
const options: JsonSchemaOptions = { direction: "output" };
```

**Signature**

```ts
export interface JsonSchemaOptions {
  readonly direction?: JsonSchemaDirection;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L46)

### JsonSchemaResult (type alias)

The result of a JSON Schema projection.

**Example**

```ts
const result: JsonSchemaResult = getJsonSchema(z.string());
```

**Signature**

```ts
type JsonSchemaResult = JsonSchemaAvailable | JsonSchemaUnavailable;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L31)

### JsonSchemaUnavailable (interface)

An unavailable projection with a stable code and reason.

**Example**

```ts
const unavailable: JsonSchemaUnavailable = {
  ok: false,
  code: JSON_SCHEMA_UNAVAILABLE,
  reason: "missing",
};
```

**Signature**

```ts
export interface JsonSchemaUnavailable {
  readonly ok: false;
  readonly code: typeof JSON_SCHEMA_UNAVAILABLE;
  readonly reason: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/json-schema.types.ts#L22)

## `schema-collection.ts`

### collectResults

Collects object or array validation results and preserves issue order.

**Throws**

The first rejected child validator in input order.

**Example**

```ts
collectResults([() => ({ value: 1 })], ([value]) => value);
```

**Signature**

```ts
declare const collectResults: <T, U>(
  tasks: readonly SchemaTask<T>[],
  map: (values: T[]) => U,
) => StandardResult<U> | Promise<StandardResult<U>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-collection.ts#L54)

### collectUnion

Selects the first successful union member in declaration order.

**Throws**

The first rejected validator in input order.

**Example**

```ts
collectUnion([() => ({ value: "ok" })], []);
```

**Signature**

```ts
declare const collectUnion: <T>(
  tasks: readonly SchemaTask<T>[],
  path: readonly StandardPathSegment[],
  mismatch?: () => string,
) => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-collection.ts#L73)

### resolveTasksEffect

Resolves child validators in input order with bounded async concurrency.

**Example**

```ts
Effect.runPromise(resolveTasksEffect([() => Promise.resolve({ value: 1 })]));
```

**Signature**

```ts
declare const resolveTasksEffect: <T>(
  tasks: readonly SchemaTask<T>[],
) => Effect.Effect<readonly StandardResult<T>[], SchemaExecutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-collection.ts#L16)

## `schema-collection.types.ts`

### SchemaTask (type alias)

Deferred child validation used by object, array, and union schemas.

**Example**

```ts
const task: SchemaTask<number> = () => ({ value: 1 });
```

**Signature**

```ts
type SchemaTask<T> = () => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-collection.types.ts#L7)

## `schema-execution.ts`

### throwCause

Rethrows the original cause of an Effect execution failure.

**Throws**

The original cause.

**Example**

```ts
throwCause(new SchemaExecutionError({ cause: new TypeError("bad") }));
```

**Signature**

```ts
declare const throwCause: (error: unknown) => never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-execution.ts#L10)

## `schema-impl-helpers.ts`

### SchemaProjectionError (class)

Tagged failure for an unsupported target or missing projection.
The original exception remains available in `cause`.

**Example**

```ts
Effect.catchTag("SchemaProjectionError", (error) => Effect.succeed(error.cause));
```

**Signature**

```ts
declare class SchemaProjectionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl-helpers.ts#L17)

### addPath

Prefixes nested issues without changing sync/async shape.

**Example**

```ts
addPath({ issues: [{ message: "bad" }] }, ["item"]);
```

**Signature**

```ts
declare const addPath: <T>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  path: readonly StandardPathSegment[],
) => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl-helpers.ts#L107)

### addPathEffect

Prefixes issues from a nested third-party validator in Effect.

**Example**

```ts
Effect.runSync(addPathEffect({ issues: [{ message: "bad" }] }, ["item"]));
```

**Signature**

```ts
declare const addPathEffect: <T>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  path: readonly StandardPathSegment[],
) => Effect.Effect<StandardResult<T> | Promise<StandardResult<T>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl-helpers.ts#L83)

### projectJsonSchema

Projects metadata through a Standard JSON Schema hook.

**Throws**

TypeError for an unsupported target or absent projection.

**Example**

```ts
projectJsonSchema({ jsonSchema: () => ({}) }, "input", "draft-07");
```

**Signature**

```ts
declare const projectJsonSchema: (
  metadata: SchemaMetadata,
  direction: "input" | "output",
  target: StandardJSONSchemaV1.Options["target"],
) => Record<string, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl-helpers.ts#L63)

### projectJsonSchemaEffect

Projects metadata through a Standard JSON Schema hook inside Effect.

**Example**

```ts
Effect.runSync(projectJsonSchemaEffect({ jsonSchema: () => ({}) }, "input", "draft-07"));
```

**Signature**

```ts
declare const projectJsonSchemaEffect: (
  metadata: SchemaMetadata,
  direction: "input" | "output",
  target: StandardJSONSchemaV1.Options["target"],
) => Effect.Effect<Record<string, unknown>, SchemaProjectionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl-helpers.ts#L29)

## `schema-impl.ts`

### SchemaValidationError

**Signature**

```ts
declare const SchemaValidationError: typeof SchemaValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.ts#L16)

### createSchema

Synchronous compatibility adapter for schema construction.

**Throws**

The original construction error if creation fails.

**Example**

```ts
createSchema((value) => ({ value }));
```

**Signature**

```ts
declare const createSchema: <TInput, TOutput>(
  check: SchemaCheck<TOutput>,
  metadata?: SchemaMetadata,
) => Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.ts#L50)

### createSchemaEffect

Constructs a schema within an observed Effect.

**Example**

```ts
Effect.runSync(createSchemaEffect((value) => ({ value })));
```

**Signature**

```ts
declare const createSchemaEffect: <TInput, TOutput>(
  check: SchemaCheck<TOutput>,
  metadata?: SchemaMetadata,
) => Effect.Effect<Schema<TInput, TOutput>, SchemaExecutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.ts#L25)

### runSchema

Compatibility adapter for path-aware schema validation.

**Throws**

The original validator error if evaluation fails.

**Example**

```ts
runSchema(z.string(), "ok", ["name"]);
```

**Signature**

```ts
declare const runSchema: <TOutput>(
  schema: StandardSchemaV1<unknown, TOutput>,
  value: unknown,
  path?: readonly StandardPathSegment[],
) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.ts#L96)

### runSchemaEffect

Evaluates a schema while preserving its synchronous or asynchronous result.

**Example**

```ts
Effect.runSync(runSchemaEffect(z.string(), "ok"));
```

**Signature**

```ts
declare const runSchemaEffect: <TOutput>(
  schema: StandardSchemaV1<unknown, TOutput>,
  value: unknown,
  path?: readonly StandardPathSegment[],
) => Effect.Effect<
  StandardResult<TOutput> | Promise<StandardResult<TOutput>>,
  SchemaExecutionError
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.ts#L69)

## `schema-impl.types.ts`

### InternalSchema (interface)

RELKIT schema with its internal path-aware validation hook.
The hook is only used while composing nested schemas.

**Example**

```ts
const internal = schema as InternalSchema<string, string>;
```

**Signature**

```ts
export interface InternalSchema<TInput, TOutput> extends Schema<TInput, TOutput> {
  readonly _run: SchemaCheck<TOutput>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.types.ts#L17)

### SchemaCheck (type alias)

Path-aware validation callback used by a constructed RELKIT schema.

**Example**

```ts
const check: SchemaCheck<string> = (value) => ({ value: String(value) });
```

**Signature**

```ts
type SchemaCheck<T> = (
  value: unknown,
  path: readonly StandardPathSegment[],
) => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-impl.types.ts#L7)

## `schema-implementation.ts`

### SchemaImplementation (class)

Internal path-aware schema with Standard Schema and JSON Schema hooks.

**Example**

```ts
new SchemaImplementation((value) => ({ value }), {});
```

**Signature**

```ts
declare class SchemaImplementation<TInput, TOutput> {
  constructor(check: SchemaCheck<TOutput>, metadata: SchemaMetadata);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L33)

### optional (method)

Accepts an omitted or undefined value.

**Example**

```ts
z.string().optional();
```

**Signature**

```ts
declare const optional: () => Schema<TInput | undefined, TOutput | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L90)

### nullable (method)

Accepts null without changing other validation.

**Example**

```ts
z.string().nullable();
```

**Signature**

```ts
declare const nullable: () => Schema<TInput | null, TOutput | null>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L103)

### default (method)

Substitutes a value when input is undefined.

**Example**

```ts
z.string().default("pending");
```

**Signature**

```ts
declare const default: (value: TInput | (() => TInput)) => Schema<TInput | undefined, TOutput>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L117)

### transform (method)

Maps a validated value to a new output.

**Example**

```ts
z.string().transform(Number);
```

**Signature**

```ts
declare const transform: <TNext>(
  transform: (value: TOutput) => TNext | Promise<TNext>,
) => Schema<TInput, TNext>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L134)

### refine (method)

Adds a check after base validation succeeds.

**Example**

```ts
z.number().refine((value) => value > 0);
```

**Signature**

```ts
declare const refine: (
  check: (value: TOutput) => boolean | Promise<boolean>,
  message?: string,
) => Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L153)

### parse (method)

Parses one input synchronously.

**Throws**

SchemaValidationError or TypeError for invalid or asynchronous input.

**Example**

```ts
z.string().parse("ready");
```

**Signature**

```ts
declare const parse: (value: unknown) => TOutput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L175)

### parseAsync (method)

Parses one input and awaits asynchronous checks.

**Throws**

SchemaValidationError when validation fails.

**Example**

```ts
await z.string().parseAsync("ready");
```

**Signature**

```ts
declare const parseAsync: (value: unknown) => Promise<TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L186)

### safeParse (method)

Returns issues instead of throwing for invalid input.

**Example**

```ts
z.string().safeParse("ready");
```

**Signature**

```ts
declare const safeParse: (
  value: unknown,
) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L196)

### \_run (property)

**Signature**

```ts
readonly _run: SchemaCheck<TOutput>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L34)

### "~standard" (property)

**Signature**

```ts
readonly "~standard": { readonly version: 1; readonly vendor: string; readonly validate: (value: unknown, options?: StandardSchemaOptions) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>; readonly types?: StandardSchemaTypes<TInput, TOutput>; } & StandardJSONSchemaV1.Props<TInput, TOutput>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L35)

### relkit (property)

**Signature**

```ts
readonly relkit: SchemaProjectionHooks
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.ts#L37)

## `schema-implementation.types.ts`

### Schema (interface)

RELKIT schema with parsing and composition methods.
Input and output types may differ after transformation.

**Example**

```ts
const schema: Schema<string, number> = z.string().transform(Number);
```

**Signature**

```ts
export interface Schema<TInput = unknown, TOutput = TInput> extends RelkitSchema<TInput, TOutput> {
  /**
   * Accepts undefined as input and output.
   * @returns A schema with optional value types.
   * @example z.string().optional();
   */
  optional(): Schema<TInput | undefined, TOutput | undefined>;
  /**
   * Accepts null as input and output.
   * @returns A nullable schema.
   * @example z.string().nullable();
   */
  nullable(): Schema<TInput | null, TOutput | null>;
  /**
   * Supplies a value for undefined input.
   * @param value - Constant or lazy default.
   * @returns A schema with optional input and required output.
   * @example z.string().default("ready");
   */
  default(value: TInput | (() => TInput)): Schema<TInput | undefined, TOutput>;
  /**
   * Maps a valid output to a new value.
   * @param transform - Synchronous or asynchronous mapper.
   * @returns A schema with the mapped output type.
   * @example z.string().transform(Number);
   */
  transform<TNext>(transform: (value: TOutput) => TNext | Promise<TNext>): Schema<TInput, TNext>;
  /**
   * Checks a valid output with a predicate.
   * @param check - Predicate for valid output.
   * @param message - Failure message.
   * @returns A refined schema.
   * @example z.number().refine((value) => value > 0);
   */
  refine(
    check: (value: TOutput) => boolean | Promise<boolean>,
    message?: string,
  ): Schema<TInput, TOutput>;
  /**
   * Parses synchronously or throws.
   * @param value - Input to parse.
   * @returns Validated output.
   * @throws SchemaValidationError or TypeError for invalid or asynchronous input.
   * @example z.string().parse("ready");
   */
  parse(value: unknown): TOutput;
  /**
   * Parses and awaits asynchronous checks.
   * @param value - Input to parse.
   * @returns A promise of validated output.
   * @throws SchemaValidationError for invalid input.
   * @example await z.string().parseAsync("ready");
   */
  parseAsync(value: unknown): Promise<TOutput>;
  /**
   * Returns a result for sync or async validation.
   * @param value - Input to validate.
   * @returns A result or promise with value or issues.
   * @example z.string().safeParse("ready");
   */
  safeParse(value: unknown): StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.types.ts#L18)

### SchemaProjectionHooks (interface)

Directional JSON Schema projection hooks carried by a RELKIT schema.

**Example**

```ts
const hooks: SchemaProjectionHooks = { jsonSchema: () => ({ type: "string" }) };
```

**Signature**

```ts
export interface SchemaProjectionHooks {
  readonly jsonSchema?: () => JsonValue;
  readonly inputJsonSchema?: () => JsonValue;
  readonly outputJsonSchema?: () => JsonValue;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-implementation.types.ts#L7)

## `schema-metadata-composition.ts`

### withDefaultMetadata

Adds a static default only to output and legacy projections.

**Example**

```ts
withDefaultMetadata(z.string(), "ready");
```

**Signature**

```ts
declare const withDefaultMetadata: <T>(
  schema: StandardSchemaV1,
  value: T | (() => T),
) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L165)

### withDefaultMetadataEffect

Builds default metadata in Effect without evaluating lazy values.

**Example**

```ts
Effect.runSync(withDefaultMetadataEffect(z.string(), "ready"));
```

**Signature**

```ts
declare const withDefaultMetadataEffect: <T>(
  schema: StandardSchemaV1,
  value: T | (() => T),
) => Effect.Effect<SchemaMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L129)

### withNullableMetadata

Wraps each available projection in a nullable union.

**Example**

```ts
withNullableMetadata(z.string());
```

**Signature**

```ts
declare const withNullableMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L118)

### withNullableMetadataEffect

Builds nullable metadata in Effect.

**Example**

```ts
Effect.runSync(withNullableMetadataEffect(z.string()));
```

**Signature**

```ts
declare const withNullableMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L93)

### withOptionalMetadata

Marks a schema optional in both projection directions.

**Example**

```ts
withOptionalMetadata(z.string());
```

**Signature**

```ts
declare const withOptionalMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L83)

### withOptionalMetadataEffect

Builds optional metadata in Effect.

**Example**

```ts
Effect.runSync(withOptionalMetadataEffect(z.string()));
```

**Signature**

```ts
declare const withOptionalMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L66)

### withRefinementMetadata

Preserves projection metadata while marking a schema refined.

**Example**

```ts
withRefinementMetadata(z.string());
```

**Signature**

```ts
declare const withRefinementMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L25)

### withRefinementMetadataEffect

Builds refinement metadata in Effect.

**Example**

```ts
Effect.runSync(withRefinementMetadataEffect(z.string()));
```

**Signature**

```ts
declare const withRefinementMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L13)

### withTransformMetadata

Keeps only input projection metadata after a transform.

**Example**

```ts
withTransformMetadata(z.string());
```

**Signature**

```ts
declare const withTransformMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L56)

### withTransformMetadataEffect

Builds transform metadata in Effect.

**Example**

```ts
Effect.runSync(withTransformMetadataEffect(z.string()));
```

**Signature**

```ts
declare const withTransformMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata-composition.ts#L35)

## `schema-metadata.ts`

### SchemaMetadata

**Signature**

```ts
declare const SchemaMetadata: SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L11)

### SchemaMetadataError (class)

Tagged failure when schema metadata cannot be attached.
The original exception remains available in `cause`.

**Example**

```ts
Effect.catchTag("SchemaMetadataError", (error) => Effect.succeed(error.cause));
```

**Signature**

```ts
declare class SchemaMetadataError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L30)

### SchemaProjection

**Signature**

```ts
declare const SchemaProjection: SchemaProjection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L12)

### SchemaProjectionDirection

**Signature**

```ts
declare const SchemaProjectionDirection: SchemaProjectionDirection;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L13)

### getMetadataProjection

Selects the projection hook for a direction.

**Example**

```ts
getMetadataProjection({}, "output");
```

**Signature**

```ts
declare const getMetadataProjection: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => SchemaProjection | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L120)

### getMetadataProjectionEffect

Selects the requested projection hook inside Effect.

**Example**

```ts
Effect.runSync(getMetadataProjectionEffect({}, "input"));
```

**Signature**

```ts
declare const getMetadataProjectionEffect: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => Effect.Effect<SchemaMetadata["jsonSchema"]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L101)

### getSchemaMetadata

Reads metadata attached to a schema.

**Example**

```ts
getSchemaMetadata(z.string());
```

**Signature**

```ts
declare const getSchemaMetadata: (schema: StandardSchemaV1) => SchemaMetadata | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L54)

### getSchemaMetadataEffect

Reads attached metadata inside Effect.

**Example**

```ts
Effect.runSync(getSchemaMetadataEffect(z.string()));
```

**Signature**

```ts
declare const getSchemaMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L40)

### isMetadataOptional

Checks whether a schema accepts an omitted property.

**Example**

```ts
isMetadataOptional({ optional: true });
```

**Signature**

```ts
declare const isMetadataOptional: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L153)

### isMetadataOptionalEffect

Checks optionality inside Effect.

**Example**

```ts
Effect.runSync(isMetadataOptionalEffect({ optional: true }));
```

**Signature**

```ts
declare const isMetadataOptionalEffect: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L134)

### isSchemaTransformed

Checks whether a schema has a value transform.

**Example**

```ts
isSchemaTransformed(z.string().transform(Number));
```

**Signature**

```ts
declare const isSchemaTransformed: (schema: StandardSchemaV1) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L176)

### isSchemaTransformedEffect

Checks whether a schema has been transformed inside Effect.

**Example**

```ts
Effect.runSync(isSchemaTransformedEffect(z.string()));
```

**Signature**

```ts
declare const isSchemaTransformedEffect: (schema: StandardSchemaV1) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L166)

### setSchemaMetadata

Attaches metadata for cross-copy projection lookup.

**Throws**

The original property-definition error.

**Example**

```ts
setSchemaMetadata(z.string(), { optional: true });
```

**Signature**

```ts
declare const setSchemaMetadata: (schema: StandardSchemaV1, metadata: SchemaMetadata) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L85)

### setSchemaMetadataEffect

Attaches metadata inside Effect.

**Example**

```ts
Effect.runSync(setSchemaMetadataEffect(z.string(), {}));
```

**Signature**

```ts
declare const setSchemaMetadataEffect: (
  schema: StandardSchemaV1,
  metadata: SchemaMetadata,
) => Effect.Effect<void, SchemaMetadataError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L65)

### withDefaultMetadata

**Signature**

```ts
declare const withDefaultMetadata: <T>(
  schema: StandardSchemaV1,
  value: T | (() => T),
) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L16)

### withNullableMetadata

**Signature**

```ts
declare const withNullableMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L17)

### withOptionalMetadata

**Signature**

```ts
declare const withOptionalMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L18)

### withRefinementMetadata

**Signature**

```ts
declare const withRefinementMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L19)

### withTransformMetadata

**Signature**

```ts
declare const withTransformMetadata: (schema: StandardSchemaV1) => SchemaMetadata;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.ts#L20)

## `schema-metadata.types.ts`

### SchemaMetadata (interface)

Metadata attached to a RELKIT schema for deterministic projection.
Directional hooks may differ after a transform or default is applied.

**Example**

```ts
const metadata: SchemaMetadata = { jsonSchema: () => ({ type: "string" }) };
```

**Signature**

```ts
export interface SchemaMetadata {
  /** Historical projection used by getJsonSchema(schema) without options. */
  readonly jsonSchema?: SchemaProjection;
  readonly inputJsonSchema?: SchemaProjection;
  readonly outputJsonSchema?: SchemaProjection;
  readonly optional?: boolean;
  readonly inputOptional?: boolean;
  readonly outputOptional?: boolean;
  readonly transformed?: boolean;
  readonly refined?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.types.ts#L19)

### SchemaProjection (type alias)

Factory for a JSON-safe schema projection.

**Example**

```ts
const projection: SchemaProjection = () => ({ type: "string" });
```

**Signature**

```ts
type SchemaProjection = () => JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.types.ts#L7)

### SchemaProjectionDirection (type alias)

Projection direction for input or validated output.

**Example**

```ts
const direction: SchemaProjectionDirection = "input";
```

**Signature**

```ts
type SchemaProjectionDirection = "input" | "output";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-metadata.types.ts#L12)

## `schema-observability.ts`

### SchemaOperation

**Signature**

```ts
declare const SchemaOperation: SchemaOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L4)

### SchemaTelemetry (class)

Injectable observer for schema operation spans and metrics.

**Example**

```ts
Effect.provide(validateEffect(z.string(), "ok"), SchemaTelemetryLive);
```

**Signature**

```ts
declare class SchemaTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L10)

### SchemaTelemetryLive

Live schema telemetry based on Effect spans, Clock, and Metric.

**Example**

```ts
Effect.runSync(Effect.provide(validateSyncEffect(z.string(), "ok"), SchemaTelemetryLive));
```

**Signature**

```ts
declare const SchemaTelemetryLive: Layer.Layer<SchemaTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L18)

### SchemaTelemetryService

**Signature**

```ts
declare const SchemaTelemetryService: SchemaTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L4)

### observeSchema

Instruments a schema operation with bounded metric labels.

**Example**

```ts
observeSchema("json-schema", Effect.succeed({ ok: true }));
```

**Signature**

```ts
declare const observeSchema: <A, E, R>(
  operation: SchemaOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L33)

### runSchemaSync

Runs a fully provided synchronous Effect and preserves its failure.

**Throws**

The original cause on failure.

**Example**

```ts
runSchemaSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runSchemaSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.ts#L73)

## `schema-observability.types.ts`

### SchemaOperation (type alias)

Fixed operation names used for schema telemetry labels.
The union prevents input data from entering metric cardinality.

**Example**

```ts
const operation: SchemaOperation = "validate";
```

**Signature**

```ts
type SchemaOperation =
  | "builder.string"
  | "builder.number"
  | "builder.boolean"
  | "builder.unknown"
  | "builder.any"
  | "builder.null"
  | "builder.undefined"
  | "builder.literal"
  | "builder.object"
  | "builder.array"
  | "builder.union"
  | "builder.file"
  | "builder.string-refine"
  | "builder.number-refine"
  | "schema.optional"
  | "schema.nullable"
  | "schema.default"
  | "schema.transform"
  | "schema.refine"
  | "validate"
  | "validate-sync"
  | "json-schema"
  | "schema.create"
  | "schema.run"
  | "schema.parse"
  | "schema.parse-async"
  | "schema.safe-parse";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.types.ts#L8)

### SchemaTelemetryService (interface)

Injectable observer for schema operations.
A test Layer can replace the live span and metric behavior.

**Example**

```ts
Layer.succeed(SchemaTelemetry, { observe: (_name, effect) => effect });
```

**Signature**

```ts
export interface SchemaTelemetryService {
  /**
   * Wraps one operation without changing its Effect channels.
   * @param operation - Fixed operation name.
   * @param effect - Operation being observed.
   * @returns The observed Effect with its original success and error channels.
   * @example telemetry.observe("validate", Effect.succeed(1));
   */
  readonly observe: <A, E, R>(
    operation: SchemaOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-observability.types.ts#L42)

## `schema-parse.ts`

### parseSchemaAsync

Parses asynchronously while preserving compatibility exceptions.

**Throws**

SchemaValidationError or the original callback error.

**Example**

```ts
await parseSchemaAsync(() => Promise.resolve({ value: "ok" }));
```

**Signature**

```ts
declare const parseSchemaAsync: <T>(check: SchemaParseCheck<T>) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.ts#L75)

### parseSchemaAsyncEffect

Parses one schema input asynchronously in Effect.

**Example**

```ts
Effect.runPromise(parseSchemaAsyncEffect(() => Promise.resolve({ value: "ok" })));
```

**Signature**

```ts
declare const parseSchemaAsyncEffect: <T>(
  check: SchemaParseCheck<T>,
) => Effect.Effect<T, SchemaIssuesError | SchemaExecutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.ts#L53)

### parseSchemaSync

Parses synchronously while preserving compatibility exceptions.

**Throws**

SchemaValidationError, TypeError, or the original callback error.

**Example**

```ts
parseSchemaSync(() => ({ value: "ok" }));
```

**Signature**

```ts
declare const parseSchemaSync: <T>(check: SchemaParseCheck<T>) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.ts#L39)

### parseSchemaSyncEffect

Parses one schema input synchronously in Effect.

**Example**

```ts
Effect.runSync(parseSchemaSyncEffect(() => ({ value: "ok" })));
```

**Signature**

```ts
declare const parseSchemaSyncEffect: <T>(
  check: SchemaParseCheck<T>,
) => Effect.Effect<T, SchemaIssuesError | SchemaAsyncError | SchemaExecutionError>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.ts#L19)

### safeParseSchema

Validates while preserving a synchronous or asynchronous result.

**Throws**

The original callback error.

**Example**

```ts
safeParseSchema(() => ({ value: "ok" }));
```

**Signature**

```ts
declare const safeParseSchema: <T>(
  check: SchemaParseCheck<T>,
) => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.ts#L90)

## `schema-parse.types.ts`

### SchemaParseCheck (type alias)

Deferred schema check used by parsing compatibility adapters.

**Example**

```ts
const check: SchemaParseCheck<string> = () => ({ value: "ok" });
```

**Signature**

```ts
type SchemaParseCheck<T> = () => StandardResult<T> | Promise<StandardResult<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-parse.types.ts#L7)

## `schema-result.ts`

### failure

Creates a failure result.

**Example**

```ts
failure("bad", ["name"]);
```

**Signature**

```ts
declare const failure: (message: string, path: readonly StandardPathSegment[]) => StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L176)

### failureEffect

Creates a failure result in Effect.

**Example**

```ts
Effect.runSync(failureEffect("bad", ["name"]));
```

**Signature**

```ts
declare const failureEffect: (
  message: string,
  path: readonly StandardPathSegment[],
) => Effect.Effect<StandardFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L162)

### flatMapResult

Chains successful validation and preserves sync/async shape.

**Example**

```ts
flatMapResult({ value: 1 }, (value) => ({ value: value + 1 }));
```

**Signature**

```ts
declare const flatMapResult: <T, U>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  map: (value: T) => StandardResult<U> | Promise<StandardResult<U>>,
) => StandardResult<U> | Promise<StandardResult<U>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L63)

### flatMapResultEffect

Chains successful validation while retaining failures in Effect.

**Example**

```ts
Effect.runSync(flatMapResultEffect({ value: 1 }, (value) => ({ value })));
```

**Signature**

```ts
declare const flatMapResultEffect: <T, U>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  map: (value: T) => StandardResult<U> | Promise<StandardResult<U>>,
) => Effect.Effect<StandardResult<U> | Promise<StandardResult<U>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L45)

### isFailure

Narrows a result to a validation failure.

**Example**

```ts
isFailure({ issues: [{ message: "bad" }] });
```

**Signature**

```ts
declare const isFailure: <T>(result: StandardResult<T>) => result is StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L131)

### isFailureEffect

Detects a failure result in Effect.

**Example**

```ts
Effect.runSync(isFailureEffect({ issues: [] }));
```

**Signature**

```ts
declare const isFailureEffect: <T>(result: StandardResult<T>) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L121)

### isPromiseLike

Narrows a value to a promise-like object.

**Example**

```ts
isPromiseLike(Promise.resolve(1));
```

**Signature**

```ts
declare const isPromiseLike: <T>(value: unknown) => value is PromiseLike<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L111)

### isPromiseLikeEffect

Detects thenable objects in Effect.

**Example**

```ts
Effect.runSync(isPromiseLikeEffect(Promise.resolve(1)));
```

**Signature**

```ts
declare const isPromiseLikeEffect: (value: unknown) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L101)

### mapResult

Maps a result without changing whether it is synchronous.

**Example**

```ts
mapResult({ value: 1 }, (result) => result);
```

**Signature**

```ts
declare const mapResult: <T, U>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  map: (value: StandardResult<T>) => U,
) => U | Promise<U>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L31)

### mapResultEffect

Maps a synchronous or asynchronous validation result in Effect.

**Example**

```ts
Effect.runSync(mapResultEffect({ value: 1 }, (result) => result));
```

**Signature**

```ts
declare const mapResultEffect: <T, U>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  map: (value: StandardResult<T>) => U,
) => Effect.Effect<U | Promise<U>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L17)

### mapValue

Maps a value without changing whether it is synchronous.

**Example**

```ts
mapValue(1, (value) => value + 1);
```

**Signature**

```ts
declare const mapValue: <T, U>(value: T | Promise<T>, map: (value: T) => U) => U | Promise<U>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L91)

### mapValueEffect

Maps a value or promise inside Effect.

**Example**

```ts
Effect.runSync(mapValueEffect(1, (value) => value + 1));
```

**Signature**

```ts
declare const mapValueEffect: <T, U>(
  value: T | Promise<T>,
  map: (value: T) => U,
) => Effect.Effect<U | Promise<U>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L77)

### success

Creates a success result.

**Example**

```ts
success("ready");
```

**Signature**

```ts
declare const success: <T>(value: T) => StandardSuccess<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L151)

### successEffect

Creates a success result in Effect.

**Example**

```ts
Effect.runSync(successEffect("ready"));
```

**Signature**

```ts
declare const successEffect: <T>(value: T) => Effect.Effect<StandardSuccess<T>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-result.ts#L141)

## `schema-validation-error.ts`

### SchemaValidationError (class)

Compatibility error thrown when parsing returns validation issues.

**Example**

```ts
try {
  z.string().parse(1);
} catch (error) {
  console.error(error);
}
```

**Signature**

```ts
declare class SchemaValidationError {
  constructor(issues: StandardFailure["issues"]);
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-validation-error.ts#L7)

### issues (property)

**Signature**

```ts
readonly issues: ReadonlyArray<StandardIssue>
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/schema-validation-error.ts#L8)

## `standard-schema-effect.ts`

### SchemaAsyncError (class)

Tagged failure when a synchronous call reaches an asynchronous validator.

**Example**

```ts
Effect.catchTag("SchemaAsyncError", () => Effect.succeed(undefined));
```

**Signature**

```ts
declare class SchemaAsyncError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L54)

### SchemaExecutionError (class)

Tagged failure when a validator throws or rejects.
The original exception remains available in `cause`.

**Example**

```ts
Effect.catchTag("SchemaExecutionError", (error) => Effect.succeed(error.cause));
```

**Signature**

```ts
declare class SchemaExecutionError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L30)

### SchemaInvalidError (class)

Tagged failure when a value is not a Standard Schema v1 validator.

**Example**

```ts
Effect.catchTag("SchemaInvalidError", (error) => Effect.succeed(error.reason));
```

**Signature**

```ts
declare class SchemaInvalidError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L17)

### SchemaIssuesError (class)

Tagged failure representing ordinary validation issues.

**Example**

```ts
Effect.catchTag("SchemaIssuesError", (error) => Effect.succeed(error.issues));
```

**Signature**

```ts
declare class SchemaIssuesError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L42)

### SchemaValidator (class)

Injectable boundary for external Standard Schema validators.

**Example**

```ts
Effect.provide(validateEffect(z.string(), "ok"), SchemaValidatorLive);
```

**Signature**

```ts
declare class SchemaValidator
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L64)

### SchemaValidatorLive

Live validator Layer that delegates to the Standard Schema hook.

**Example**

```ts
Effect.runPromise(Effect.provide(validateEffect(z.string(), "ok"), SchemaValidatorLive));
```

**Signature**

```ts
declare const SchemaValidatorLive: Layer.Layer<SchemaValidator, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L72)

### validateEffect

Validates an input and fails with tagged errors for issues and hook failures.

**Example**

```ts
Effect.runPromise(Effect.provide(validateEffect(z.string(), "ok"), SchemaValidatorLive));
```

**Signature**

```ts
declare const validateEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect.Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L115)

### validateMaybeEffect

Calls a validator while retaining its synchronous or asynchronous shape.

**Example**

```ts
Effect.runSync(Effect.provide(validateMaybeEffect(z.string(), "ok"), SchemaValidatorLive));
```

**Signature**

```ts
declare const validateMaybeEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect.Effect<
  StandardResult<InferOutput<S>> | Promise<StandardResult<InferOutput<S>>>,
  SchemaInvalidError | SchemaExecutionError,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L83)

### validateSyncEffect

Validates without waiting and rejects asynchronous validators by tag.

**Example**

```ts
Effect.runSync(Effect.provide(validateSyncEffect(z.number(), 2), SchemaValidatorLive));
```

**Signature**

```ts
declare const validateSyncEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect.Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError | SchemaAsyncError,
  SchemaValidator
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.ts#L146)

## `standard-schema-effect.types.ts`

### SchemaValidatorService (interface)

Substitutable boundary for third-party Standard Schema validation.
Test Layers can provide a deterministic validator.

**Example**

```ts
Layer.succeed(SchemaValidator, { validate: () => ({ value: "ok" }) });
```

**Signature**

```ts
export interface SchemaValidatorService {
  /**
   * Runs one Standard Schema validation hook.
   * @param schema - Compatible validator.
   * @param value - Candidate input.
   * @returns A result or promise of a result.
   * @example validator.validate(z.string(), "ok");
   */
  readonly validate: <T>(
    schema: StandardSchemaV1<unknown, T>,
    value: unknown,
  ) => StandardResult<T> | Promise<StandardResult<T>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema-effect.types.ts#L8)

## `standard-schema.ts`

### validate

Validates with a Standard Schema v1 compatible validator.

**Throws**

TypeError when the validator does not implement Standard Schema v1.

**Example**

```ts
import { validate, z } from "@relkit/app/schema";

const result = await validate(z.string(), "ready");
if (!("value" in result)) throw new Error("validation failed");
```

**Signature**

```ts
declare const validate: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>> | Promise<StandardResult<InferOutput<S>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L56)

Since v0.1.0

### InferInput

**Signature**

```ts
declare const InferInput: InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L23)

### InferOutput

**Signature**

```ts
declare const InferOutput: InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L24)

### JsonValue

**Signature**

```ts
declare const JsonValue: JsonValue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L25)

### RelkitSchema

**Signature**

```ts
declare const RelkitSchema: RelkitSchema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L26)

### Schema

**Signature**

```ts
declare const Schema: Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L27)

### SchemaValidationError

**Signature**

```ts
declare const SchemaValidationError: typeof SchemaValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L110)

### StandardFailure

**Signature**

```ts
declare const StandardFailure: StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L28)

### StandardIssue

**Signature**

```ts
declare const StandardIssue: StandardIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L29)

### StandardJSONSchemaV1

**Signature**

```ts
declare const StandardJSONSchemaV1: StandardJSONSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L30)

### StandardPathSegment

**Signature**

```ts
declare const StandardPathSegment: StandardPathSegment;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L31)

### StandardResult

**Signature**

```ts
declare const StandardResult: StandardResult<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L32)

### StandardSchemaOptions

**Signature**

```ts
declare const StandardSchemaOptions: StandardSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L33)

### StandardSchemaTypes

**Signature**

```ts
declare const StandardSchemaTypes: StandardSchemaTypes<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L34)

### StandardSchemaV1

**Signature**

```ts
declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L35)

### StandardSuccess

**Signature**

```ts
declare const StandardSuccess: StandardSuccess<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L36)

### createSchema

**Signature**

```ts
declare const createSchema: <TInput, TOutput>(
  check: SchemaCheck<TOutput>,
  metadata?: SchemaMetadata,
) => Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L110)

### isPromiseLike

**Signature**

```ts
declare const isPromiseLike: <T>(value: unknown) => value is PromiseLike<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L38)

### issue

Constructs a portable validation failure at a schema path.

**Example**

```ts
issue("Expected a string", ["name"]);
```

**Signature**

```ts
declare const issue: (message: string, path: readonly StandardPathSegment[]) => StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L119)

### runSchema

**Signature**

```ts
declare const runSchema: <TOutput>(
  schema: StandardSchemaV1<unknown, TOutput>,
  value: unknown,
  path?: readonly StandardPathSegment[],
) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L110)

### validateSync

Validates synchronously with a Standard Schema v1 compatible validator.

**Throws**

TypeError when the validator is invalid or asynchronous.

**Example**

```ts
const result = validateSync(z.number(), 3);
```

**Signature**

```ts
declare const validateSync: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.ts#L96)

## `standard-schema.types.ts`

A Standard Schema issue path accepts keys and structured segments.

**Example**

```ts
const path: StandardPathSegment[] = ["items", 0, { key: "name" }];
```

### InferInput (type alias)

Infers the accepted input type of a compatible schema.

**Example**

```ts
type Input = InferInput<typeof schema>;
```

**Signature**

```ts
type InferInput<S extends StandardSchemaV1> = S["~standard"] extends {
  readonly types?: infer Types;
}
  ? Types extends StandardSchemaTypes<infer Input, unknown>
    ? Input
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L159)

### InferOutput (type alias)

Infers the validated output type of a compatible schema.

**Example**

```ts
type Output = InferOutput<typeof schema>;
```

**Signature**

```ts
type InferOutput<S extends StandardSchemaV1> = S["~standard"] extends {
  readonly types?: infer Types;
}
  ? Types extends StandardSchemaTypes<unknown, infer Output>
    ? Output
    : unknown
  : unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L171)

### JsonValue (type alias)

JSON-safe value produced by a schema projection hook.

**Example**

```ts
const projection: JsonValue = { type: "string" };
```

**Signature**

```ts
type JsonValue =
  string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L152)

### RelkitSchema (interface)

RELKIT schema boundary with optional legacy and directional projections.

**Example**

```ts
const schema: RelkitSchema = z.string();
```

**Signature**

```ts
export interface RelkitSchema<TInput = unknown, TOutput = TInput> extends StandardSchemaV1<
  TInput,
  TOutput
> {
  readonly "~standard": StandardSchemaV1<TInput, TOutput>["~standard"] &
    StandardJSONSchemaV1<TInput, TOutput>["~standard"];
  readonly relkit?: {
    readonly jsonSchema?: () => JsonValue;
    readonly inputJsonSchema?: () => JsonValue;
    readonly outputJsonSchema?: () => JsonValue;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L135)

### Schema

**Signature**

```ts
declare const Schema: Schema<TInput, TOutput>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L179)

### StandardFailure (interface)

Standard Schema validation failure with structured issues.

**Example**

```ts
const failure: StandardFailure = { issues: [{ message: "Required" }] };
```

**Signature**

```ts
export interface StandardFailure {
  readonly issues: readonly StandardIssue[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L29)

### StandardIssue (interface)

A portable issue that may identify a nested path.

**Example**

```ts
const issue: StandardIssue = { message: "Required", path: ["name"] };
```

**Signature**

```ts
export interface StandardIssue {
  readonly message: string;
  readonly path?: readonly StandardPathSegment[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L11)

### StandardJSONSchemaV1 (interface)

Standard JSON Schema v1 projection contract.

**Example**

```ts
schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
```

**Signature**

```ts
export interface StandardJSONSchemaV1<TInput = unknown, TOutput = TInput> {
  readonly "~standard": StandardJSONSchemaV1.Props<TInput, TOutput>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L84)

### StandardJSONSchemaV1 (namespace)

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L88)

### Props (interface)

Type and projection hooks advertised by a schema.

**Example**

```ts
const props: StandardJSONSchemaV1.Props = schema["~standard"];
```

**Signature**

```ts
export interface Props<Input = unknown, Output = Input> {
  readonly version: 1;
  readonly vendor: string;
  readonly types?: StandardSchemaTypes<Input, Output>;
  readonly jsonSchema: {
    readonly input: (options: Options) => Record<string, unknown>;
    readonly output: (options: Options) => Record<string, unknown>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L93)

### Options (interface)

Dialect and vendor options for Standard JSON Schema hooks.

**Example**

```ts
const options: StandardJSONSchemaV1.Options = { target: "draft-2020-12" };
```

**Signature**

```ts
export interface Options {
  readonly target: "draft-2020-12" | "draft-07" | "openapi-3.0" | ({} & string);
  readonly libraryOptions?: Record<string, unknown> | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L106)

### StandardPathSegment (type alias)

A Standard Schema issue path accepts keys and structured segments.

**Example**

```ts
const path: StandardPathSegment[] = ["items", 0, { key: "name" }];
```

**Signature**

```ts
type StandardPathSegment = PropertyKey | { readonly key: PropertyKey };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L5)

### StandardResult (type alias)

Result union that preserves issues instead of throwing.

**Example**

```ts
const result: StandardResult<number> = { value: 2 };
```

**Signature**

```ts
type StandardResult<T> = StandardSuccess<T> | StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L37)

### StandardSchemaOptions (interface)

Vendor-specific options accepted by a compatible validator.

**Example**

```ts
const options: StandardSchemaOptions = { libraryOptions: {} };
```

**Signature**

```ts
export interface StandardSchemaOptions {
  readonly libraryOptions?: Record<string, unknown> | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L43)

### StandardSchemaTypes (interface)

Phantom input and output types advertised by Standard Schema.

**Example**

```ts
type Types = StandardSchemaTypes<string, number>;
```

**Signature**

```ts
export interface StandardSchemaTypes<TInput = unknown, TOutput = TInput> {
  readonly input: TInput;
  readonly output: TOutput;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L51)

### StandardSchemaV1 (interface)

Standard Schema v1 contract accepted by RELKIT.
The validate hook may return synchronously or asynchronously.

**Example**

```ts
const result = await schema["~standard"].validate(value);
```

**Signature**

```ts
export interface StandardSchemaV1<TInput = unknown, TOutput = TInput> {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: string;
    /**
     * Validates unknown input.
     * @param value - Candidate input.
     * @param options - Optional vendor settings.
     * @returns A validation result or promise of one.
     * @example schema["~standard"].validate("ready");
     */
    readonly validate: (
      value: unknown,
      options?: StandardSchemaOptions,
    ) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
    readonly types?: StandardSchemaTypes<TInput, TOutput>;
  };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L61)

### StandardSchemaV1 (namespace)

Namespace aliases matching the official Standard Schema v1 vocabulary.

**Example**

```ts
type Result = StandardSchemaV1.Result<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L116)

### Props (type alias)

**Signature**

```ts
type Props<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>["~standard"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L117)

### Result (type alias)

**Signature**

```ts
type Result<Output> = StandardResult<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L118)

### SuccessResult (type alias)

**Signature**

```ts
type SuccessResult<Output> = StandardSuccess<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L119)

### FailureResult (type alias)

**Signature**

```ts
type FailureResult = StandardFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L120)

### Issue (type alias)

**Signature**

```ts
type Issue = StandardIssue;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L121)

### PathSegment (type alias)

**Signature**

```ts
type PathSegment = { readonly key: PropertyKey };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L122)

### Types (type alias)

**Signature**

```ts
type Types<Input = unknown, Output = Input> = StandardSchemaTypes<Input, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L123)

### Options (type alias)

**Signature**

```ts
type Options = StandardSchemaOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L124)

### InferInput (type alias)

**Signature**

```ts
type InferInput<S extends StandardSchemaV1> = import("./standard-schema.types.js").InferInput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L125)

### InferOutput (type alias)

**Signature**

```ts
type InferOutput<S extends StandardSchemaV1> = import("./standard-schema.types.js").InferOutput<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L127)

### StandardSuccess (interface)

Successful Standard Schema validation with a typed output.

**Example**

```ts
const success: StandardSuccess<string> = { value: "ready" };
```

**Signature**

```ts
export interface StandardSuccess<T> {
  readonly value: T;
  readonly issues?: undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/schema/src/standard-schema.types.ts#L20)

---

# Services API
Source: https://relkit.dev/docs/api/services

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineService](/docs/api/services#defineservice)

For configuration and examples, read [define](/docs/modules/service/define), [migration](/docs/modules/service/migration), [service](/docs/modules/service).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Frontend usage

[Call a public service operation](/docs/modules/service/routes#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/services` — 45 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                       | Kind  | Import from        | Example                                                             |
| ----------------------------------------------------------------------------------------- | ----- | ------------------ | ------------------------------------------------------------------- |
| [assertServiceDescriptor](/docs/api/services#assertservicedescriptor)                     | Value | `@relkit/services` | [API example](/docs/api/services#assertservicedescriptor)           |
| [assertServiceDescriptorEffect](/docs/api/services#assertservicedescriptoreffect)         | Value | `@relkit/services` | [API example](/docs/api/services#assertservicedescriptoreffect)     |
| [assertServiceMemberName](/docs/api/services#assertservicemembername)                     | Value | `@relkit/services` | [API example](/docs/api/services#assertservicemembername)           |
| [assertServiceMemberNameEffect](/docs/api/services#assertservicemembernameeffect)         | Value | `@relkit/services` | [API example](/docs/api/services#assertservicemembernameeffect)     |
| [assertServiceRef](/docs/api/services#assertserviceref)                                   | Value | `@relkit/services` | [API example](/docs/api/services#assertserviceref)                  |
| [assertServiceRefEffect](/docs/api/services#assertservicerefeffect)                       | Value | `@relkit/services` | [API example](/docs/api/services#assertservicerefeffect)            |
| [defineService](/docs/api/services#defineservice)                                         | Value | `@relkit/services` | [API example](/docs/api/services#defineservice)                     |
| [DefineService](/docs/api/services#defineservice-interface)                               | Type  | `@relkit/services` | [API example](/docs/api/services#defineservice-interface)           |
| [defineServiceEffect](/docs/api/services#defineserviceeffect)                             | Value | `@relkit/services` | [API example](/docs/api/services#defineserviceeffect)               |
| [DefineServiceOptions](/docs/api/services#defineserviceoptions-interface)                 | Type  | `@relkit/services` | [API example](/docs/api/services#defineserviceoptions-interface)    |
| [freezeServiceContextValue](/docs/api/services#freezeservicecontextvalue)                 | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicecontextvalue)         |
| [freezeServiceContextValueEffect](/docs/api/services#freezeservicecontextvalueeffect)     | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicecontextvalueeffect)   |
| [freezeServiceDescriptor](/docs/api/services#freezeservicedescriptor)                     | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicedescriptor)           |
| [freezeServiceDescriptorEffect](/docs/api/services#freezeservicedescriptoreffect)         | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicedescriptoreffect)     |
| [isFunctionDescriptor](/docs/api/services#isfunctiondescriptor)                           | Value | `@relkit/services` | [API example](/docs/api/services#isfunctiondescriptor)              |
| [isFunctionDescriptorEffect](/docs/api/services#isfunctiondescriptoreffect)               | Value | `@relkit/services` | [API example](/docs/api/services#isfunctiondescriptoreffect)        |
| [isReservedServiceMemberName](/docs/api/services#isreservedservicemembername)             | Value | `@relkit/services` | [API example](/docs/api/services#isreservedservicemembername)       |
| [isReservedServiceMemberNameEffect](/docs/api/services#isreservedservicemembernameeffect) | Value | `@relkit/services` | [API example](/docs/api/services#isreservedservicemembernameeffect) |
| [isServiceDescriptor](/docs/api/services#isservicedescriptor)                             | Value | `@relkit/services` | [API example](/docs/api/services#isservicedescriptor)               |
| [isServiceDescriptorEffect](/docs/api/services#isservicedescriptoreffect)                 | Value | `@relkit/services` | [API example](/docs/api/services#isservicedescriptoreffect)         |
| [isServiceRef](/docs/api/services#isserviceref)                                           | Value | `@relkit/services` | [API example](/docs/api/services#isserviceref)                      |
| [isServiceRefEffect](/docs/api/services#isservicerefeffect)                               | Value | `@relkit/services` | [API example](/docs/api/services#isservicerefeffect)                |
| [normalizeServiceMemberName](/docs/api/services#normalizeservicemembername)               | Value | `@relkit/services` | [API example](/docs/api/services#normalizeservicemembername)        |
| [normalizeServiceMemberNameEffect](/docs/api/services#normalizeservicemembernameeffect)   | Value | `@relkit/services` | [API example](/docs/api/services#normalizeservicemembernameeffect)  |
| [observeService](/docs/api/services#observeservice)                                       | Value | `@relkit/services` | [API example](/docs/api/services#observeservice)                    |
| [RESERVED_SERVICE_MEMBER_NAMES](/docs/api/services#reserved_service_member_names)         | Value | `@relkit/services` | [Module example](/docs/modules/service/define)                      |
| [runServiceSync](/docs/api/services#runservicesync)                                       | Value | `@relkit/services` | [API example](/docs/api/services#runservicesync)                    |
| [SERVICE_RESERVED_MEMBER_NAMES](/docs/api/services#service_reserved_member_names)         | Value | `@relkit/services` | [Module example](/docs/modules/service/define)                      |
| [ServiceDescriptor](/docs/api/services#servicedescriptor-type-alias)                      | Type  | `@relkit/services` | [API example](/docs/api/services#servicedescriptor-type-alias)      |
| [ServiceDescriptorAny](/docs/api/services#servicedescriptorany-type-alias)                | Type  | `@relkit/services` | [API example](/docs/api/services#servicedescriptorany-type-alias)   |
| [ServiceEventMap](/docs/api/services#serviceeventmap-type-alias)                          | Type  | `@relkit/services` | [API example](/docs/api/services#serviceeventmap-type-alias)        |
| [ServiceEvents](/docs/api/services#serviceevents-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#serviceevents-type-alias)          |
| [ServiceFunctionMap](/docs/api/services#servicefunctionmap-type-alias)                    | Type  | `@relkit/services` | [API example](/docs/api/services#servicefunctionmap-type-alias)     |
| [ServiceFunctions](/docs/api/services#servicefunctions-type-alias)                        | Type  | `@relkit/services` | [API example](/docs/api/services#servicefunctions-type-alias)       |
| [ServiceJobMap](/docs/api/services#servicejobmap-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#servicejobmap-type-alias)          |
| [ServiceJobs](/docs/api/services#servicejobs-type-alias)                                  | Type  | `@relkit/services` | [API example](/docs/api/services#servicejobs-type-alias)            |
| [serviceMemberEntries](/docs/api/services#servicememberentries)                           | Value | `@relkit/services` | [API example](/docs/api/services#servicememberentries)              |
| [serviceMemberEntriesEffect](/docs/api/services#servicememberentrieseffect)               | Value | `@relkit/services` | [API example](/docs/api/services#servicememberentrieseffect)        |
| [ServiceRef](/docs/api/services#serviceref-interface)                                     | Type  | `@relkit/services` | [API example](/docs/api/services#serviceref-interface)              |
| [ServiceRefAny](/docs/api/services#servicerefany-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#servicerefany-type-alias)          |
| [ServiceTaskMap](/docs/api/services#servicetaskmap-type-alias)                            | Type  | `@relkit/services` | [API example](/docs/api/services#servicetaskmap-type-alias)         |
| [ServiceTasks](/docs/api/services#servicetasks-type-alias)                                | Type  | `@relkit/services` | [API example](/docs/api/services#servicetasks-type-alias)           |
| [ServiceTelemetry](/docs/api/services#servicetelemetry-class)                             | Value | `@relkit/services` | [API example](/docs/api/services#servicetelemetry-class)            |
| [ServiceTelemetryLive](/docs/api/services#servicetelemetrylive)                           | Value | `@relkit/services` | [API example](/docs/api/services#servicetelemetrylive)              |
| [ServiceValidationError](/docs/api/services#servicevalidationerror-class)                 | Value | `@relkit/services` | [API example](/docs/api/services#servicevalidationerror-class)      |

## `define-service.ts`

### defineService

Define a service synchronously for authoring and preserve member identity.

**Throws**

TypeError for malformed local input, or the original identity/ID error.

**Example**

```ts
import { defineFunction } from "@relkit/functions";
import { z } from "@relkit/schema";
import { defineService } from "@relkit/services";
const lookup = defineFunction({
  input: z.string(),
  output: z.string(),
  handler: (id) => id,
});
const orders = defineService({ id: "orders", functions: { lookup } });
```

**Signature**

```ts
declare const defineService: DefineService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.ts#L114)

Since v0.1.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/orders/service.ts"
/** Declares the orders service boundary without acquiring native clients. */
import { defineService } from "@relkit/app/services";
import createOrder from "./functions/create-order.function.js";
import deleteOrder from "./functions/delete-order.function.js";
import getOrder from "./functions/get-order.function.js";
import searchOrders from "./functions/search-orders.function.js";
import updateOrder from "./functions/update-order.function.js";
import authorizeOrder from "./functions/authorize-order.function.js";
import streamOrderReport from "./functions/stream-order-report.function.js";
import cleanupOrders from "./jobs/cleanup-orders.job.js";
import exportOrders from "./jobs/export-orders.job.js";
import cleanupOrdersTask from "./tasks/cleanup-orders.task.js";
import exportOrdersTask from "./tasks/export-orders.task.js";

export default defineService({
  functions: {
    createOrder,
    deleteOrder,
    getOrder,
    searchOrders,
    updateOrder,
    authorizeOrder,
    streamOrderReport,
  },
  tasks: { cleanupOrdersTask, exportOrdersTask },
  jobs: { cleanupOrders, exportOrders },
});
```

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

**Frontend**

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";

/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
 * @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
  const { status } = useRelkitClient();
  const orders = useRoute("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      {orders.isPending && <p role="status">Loading orders…</p>}
      {orders.data && <p>{orders.data.count} orders</p>}
      {orders.isError && <p role="alert">{orders.error.message}</p>}
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

### defineServiceEffect

Define a service without cloning its member descriptors.

**Example**

```ts
Effect.runSync(defineServiceEffect({ id: "orders", functions: { lookup } }));
```

**Signature**

```ts
declare const defineServiceEffect: <
  const Id extends string,
  const Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  const Events extends ServiceEventMap = Readonly<Record<never, never>>,
  const Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  const Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
>(
  options: DefineServiceOptions<Id, Functions, Events, Tasks, Jobs>,
) => Effect.Effect<
  ServiceDescriptor<Id, Functions, Events, Tasks, Jobs>,
  ServiceValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.ts#L29)

## `define-service.types.ts`

### DefineService (interface)

Generic synchronous service factory preserving member inference.

**Throws**

TypeError for malformed local input, or the original identity/ID error.

**Example**

```ts
const orders = defineService({ id: "orders", functions: { lookup } });
```

**Signature**

```ts
export interface DefineService {
  <
    const Id extends string,
    const Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
    const Events extends ServiceEventMap = Readonly<Record<never, never>>,
    const Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
    const Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
  >(
    options: DefineServiceOptions<Id, Functions, Events, Tasks, Jobs>,
  ): ServiceDescriptor<Id, Functions, Events, Tasks, Jobs>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L122)

### DefineServiceOptions (interface)

Metadata and optional descriptor members accepted by defineService.

**Example**

```ts
const options: DefineServiceOptions<"orders"> = { id: "orders" };
```

**Signature**

```ts
export interface DefineServiceOptions<
  Id extends string,
  Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  Events extends ServiceEventMap = Readonly<Record<never, never>>,
  Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly functions?: Functions;
  readonly events?: Events;
  readonly tasks?: Tasks;
  readonly jobs?: Jobs;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L102)

### ServiceDescriptor (type alias)

Frozen service descriptor with identity-preserving public members.

**Example**

```ts
type Orders = ServiceDescriptor<"orders", { lookup: typeof lookup }>;
```

**Signature**

```ts
type ServiceDescriptor<
  Id extends string,
  Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  Events extends ServiceEventMap = Readonly<Record<never, never>>,
  Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
> = DescriptorBase<"service", Id> &
  PublicMembers<Functions, Events, Tasks, Jobs> & {
    readonly [serviceTypes]: ServiceTypeMembers<Functions, Events, Tasks, Jobs>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L47)

### ServiceDescriptorAny (type alias)

Service descriptor with an unspecified ID and member set.

**Example**

```ts
function inspect(service: ServiceDescriptorAny) {
  return service.id;
}
```

**Signature**

```ts
type ServiceDescriptorAny = DescriptorBase<"service", string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L61)

### ServiceEventMap (type alias)

Named event members on a service.

**Example**

```ts
type Events = ServiceEventMap;
```

**Signature**

```ts
type ServiceEventMap = Readonly<Record<string, EventDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L13)

### ServiceEvents (type alias)

Extracts the event members recorded in a service type.

**Example**

```ts
type Events = ServiceEvents<typeof orders>;
```

**Signature**

```ts
type ServiceEvents<Service> = Service extends {
  readonly [serviceTypes]: { readonly events: infer Events };
}
  ? Events
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L75)

### ServiceFunctionMap (type alias)

Named function members on a service.

**Example**

```ts
type Functions = ServiceFunctionMap;
```

**Signature**

```ts
type ServiceFunctionMap = Readonly<Record<string, FunctionRefAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L9)

### ServiceFunctions (type alias)

Extracts the function members recorded in a service type.

**Example**

```ts
type Functions = ServiceFunctions<typeof orders>;
```

**Signature**

```ts
type ServiceFunctions<Service> = Service extends {
  readonly [serviceTypes]: { readonly functions: infer Functions };
}
  ? Functions
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L66)

### ServiceJobMap (type alias)

Named job members on a service.

**Example**

```ts
type Jobs = ServiceJobMap;
```

**Signature**

```ts
type ServiceJobMap = Readonly<Record<string, JobDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L21)

### ServiceJobs (type alias)

Extracts the job members recorded in a service type.

**Example**

```ts
type Jobs = ServiceJobs<typeof orders>;
```

**Signature**

```ts
type ServiceJobs<Service> = Service extends {
  readonly [serviceTypes]: { readonly jobs: infer Jobs };
}
  ? Jobs
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L93)

### ServiceTaskMap (type alias)

Named task members on a service.

**Example**

```ts
type Tasks = ServiceTaskMap;
```

**Signature**

```ts
type ServiceTaskMap = Readonly<Record<string, TaskDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L17)

### ServiceTasks (type alias)

Extracts the task members recorded in a service type.

**Example**

```ts
type Tasks = ServiceTasks<typeof orders>;
```

**Signature**

```ts
type ServiceTasks<Service> = Service extends {
  readonly [serviceTypes]: { readonly tasks: infer Tasks };
}
  ? Tasks
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L84)

## `descriptor-guards.ts`

### assertServiceDescriptor

Require a valid service descriptor synchronously.

**Throws**

TypeError when invalid.

**Example**

```ts
assertServiceDescriptor(candidate);
```

**Signature**

```ts
declare const assertServiceDescriptor: (value: unknown) => asserts value is ServiceDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L67)

### assertServiceDescriptorEffect

Require a valid service descriptor in Effect.

**Example**

```ts
Effect.runSync(assertServiceDescriptorEffect(candidate));
```

**Signature**

```ts
declare const assertServiceDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ServiceDescriptorAny, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L49)

### freezeServiceDescriptor

Validate and freeze a descriptor synchronously.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
freezeServiceDescriptor(service);
```

**Signature**

```ts
declare const freezeServiceDescriptor: <T extends ServiceDescriptorAny>(value: T) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L93)

### freezeServiceDescriptorEffect

Validate and recursively freeze a descriptor in Effect.

**Example**

```ts
Effect.runSync(freezeServiceDescriptorEffect(service));
```

**Signature**

```ts
declare const freezeServiceDescriptorEffect: <T extends ServiceDescriptorAny>(
  value: T,
) => Effect.Effect<T, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L76)

### isServiceDescriptor

Check a service descriptor synchronously.

**Example**

```ts
isServiceDescriptor(candidate);
```

**Signature**

```ts
declare const isServiceDescriptor: (value: unknown) => value is ServiceDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L40)

### isServiceDescriptorEffect

Check a service descriptor and every public member in Effect.

**Example**

```ts
Effect.runSync(isServiceDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isServiceDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L15)

### serviceMemberEntries

Enumerate public descriptor members synchronously.

**Example**

```ts
serviceMemberEntries(service);
```

**Signature**

```ts
declare const serviceMemberEntries: (service: ServiceDescriptorAny) => [string, unknown][];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L120)

### serviceMemberEntriesEffect

Enumerate public descriptor members in Effect.

**Example**

```ts
Effect.runSync(serviceMemberEntriesEffect(service));
```

**Signature**

```ts
declare const serviceMemberEntriesEffect: (
  service: ServiceDescriptorAny,
) => Effect.Effect<Array<[string, unknown]>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L102)

## `function-guards.ts`

### isFunctionDescriptor

Check a function member synchronously.

**Example**

```ts
isFunctionDescriptor(candidate);
```

**Signature**

```ts
declare const isFunctionDescriptor: (value: unknown) => value is FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/function-guards.ts#L34)

### isFunctionDescriptorEffect

Check a function member's descriptor contract in Effect.

**Example**

```ts
Effect.runSync(isFunctionDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isFunctionDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/function-guards.ts#L11)

## `guards.ts`

Public guard relay.

### "./descriptor-guards.js" (namespace export)

Re-exports all named exports from the "./descriptor-guards.js" module.

**Signature**

```ts
export * from "./descriptor-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L2)

### "./function-guards.js" (namespace export)

Re-exports all named exports from the "./function-guards.js" module.

**Signature**

```ts
export * from "./function-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L3)

### "./member-name.js" (namespace export)

Re-exports all named exports from the "./member-name.js" module.

**Signature**

```ts
export * from "./member-name.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L4)

### "./reference-guards.js" (namespace export)

Re-exports all named exports from the "./reference-guards.js" module.

**Signature**

```ts
export * from "./reference-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L5)

## `index.ts`

### "./define-service.js" (namespace export)

Re-exports all named exports from the "./define-service.js" module.

**Signature**

```ts
export * from "./define-service.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L1)

### "./guards.js" (namespace export)

Re-exports all named exports from the "./guards.js" module.

**Signature**

```ts
export * from "./guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L2)

### "./service-context.js" (namespace export)

Re-exports all named exports from the "./service-context.js" module.

**Signature**

```ts
export * from "./service-context.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L3)

### "./service-error.js" (namespace export)

Re-exports all named exports from the "./service-error.js" module.

**Signature**

```ts
export * from "./service-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L4)

### "./service-observability.js" (namespace export)

Re-exports all named exports from the "./service-observability.js" module.

**Signature**

```ts
export * from "./service-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L5)

### "./types.js" (namespace export)

Re-exports all named exports from the "./types.js" module.

**Signature**

```ts
export * from "./types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L6)

## `member-name.ts`

### RESERVED_SERVICE_MEMBER_NAMES

Compatibility alias for the reserved member list.

**Signature**

```ts
declare const RESERVED_SERVICE_MEMBER_NAMES: readonly [
  "kind",
  "id",
  "ref",
  "functions",
  "events",
  "tasks",
  "jobs",
  "capability",
  "title",
  "description",
  "tags",
  "handler",
  "constructor",
  "prototype",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L25)

### SERVICE_RESERVED_MEMBER_NAMES

Names disallowed as service members because they collide with descriptor metadata.

**Signature**

```ts
declare const SERVICE_RESERVED_MEMBER_NAMES: readonly [
  "kind",
  "id",
  "ref",
  "functions",
  "events",
  "tasks",
  "jobs",
  "capability",
  "title",
  "description",
  "tags",
  "handler",
  "constructor",
  "prototype",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L6)

### assertServiceMemberName

Assert a canonical, nonreserved member name synchronously.

**Throws**

TypeError for invalid names.

**Example**

```ts
assertServiceMemberName("lookup");
```

**Signature**

```ts
declare const assertServiceMemberName: (value: unknown) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L119)

### assertServiceMemberNameEffect

Validate one member name with a tagged Effect failure.

**Example**

```ts
Effect.runSync(assertServiceMemberNameEffect("lookup"));
```

**Signature**

```ts
declare const assertServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<string, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L94)

### isReservedServiceMemberName

Check a candidate against the reserved member list.

**Example**

```ts
isReservedServiceMemberName(" id ");
```

**Signature**

```ts
declare const isReservedServiceMemberName: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L85)

### isReservedServiceMemberNameEffect

Check whether a candidate is a reserved member name in Effect.

**Example**

```ts
Effect.runSync(isReservedServiceMemberNameEffect("id"));
```

**Signature**

```ts
declare const isReservedServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L66)

### normalizeServiceMemberName

Normalize a service member name synchronously.

**Throws**

TypeError for non-string or empty input.

**Example**

```ts
normalizeServiceMemberName(" lookup ");
```

**Signature**

```ts
declare const normalizeServiceMemberName: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L57)

### normalizeServiceMemberNameEffect

Normalize a service member name inside Effect.

**Example**

```ts
Effect.runSync(normalizeServiceMemberNameEffect("lookup"));
```

**Signature**

```ts
declare const normalizeServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<string, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L32)

## `reference-guards.ts`

### assertServiceRef

Require a service reference synchronously.

**Throws**

TypeError when invalid.

**Example**

```ts
assertServiceRef(candidate);
```

**Signature**

```ts
declare const assertServiceRef: (value: unknown) => asserts value is ServiceRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L53)

### assertServiceRefEffect

Require a service reference in Effect.

**Example**

```ts
Effect.runSync(assertServiceRefEffect(candidate));
```

**Signature**

```ts
declare const assertServiceRefEffect: (
  value: unknown,
) => Effect.Effect<ServiceRefAny, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L36)

### isServiceRef

Check a service reference synchronously.

**Example**

```ts
isServiceRef({ ref: createRef("service", "orders") });
```

**Signature**

```ts
declare const isServiceRef: (value: unknown) => value is ServiceRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L27)

### isServiceRefEffect

Check a service reference in Effect.

**Example**

```ts
Effect.runSync(isServiceRefEffect({ ref: createRef("service", "orders") }));
```

**Signature**

```ts
declare const isServiceRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L12)

## `reference-guards.types.ts`

### ServiceRef (interface)

A stable reference to one service descriptor.

**Example**

```ts
const ref: ServiceRef<"orders"> = { ref: createRef("service", "orders") };
```

**Signature**

```ts
export interface ServiceRef<Id extends string = string> {
  readonly ref: Ref<"service", Id>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.types.ts#L6)

### ServiceRefAny (type alias)

Any service reference regardless of its stable ID.

**Example**

```ts
function inspect(value: ServiceRefAny) {
  return value.ref.id;
}
```

**Signature**

```ts
type ServiceRefAny = ServiceRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.types.ts#L13)

## `service-context.ts`

### freezeServiceContextValue

Copy and freeze a plain service context graph synchronously.

**Throws**

When a proxy or getter prevents graph inspection.

**Example**

```ts
freezeServiceContextValue({ enabled: true }, new WeakMap());
```

**Signature**

```ts
declare const freezeServiceContextValue: (value: unknown, seen: WeakMap<object, object>) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-context.ts#L22)

### freezeServiceContextValueEffect

Copy and freeze a plain service context graph, preserving cycles and identity.

**Example**

```ts
Effect.runSync(freezeServiceContextValueEffect({ enabled: true }, new WeakMap()));
```

**Signature**

```ts
declare const freezeServiceContextValueEffect: (
  value: unknown,
  seen: WeakMap<object, object>,
) => Effect.Effect<unknown, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-context.ts#L10)

## `service-error.ts`

### ServiceValidationError (class)

Expected malformed service input or dependency rejection in an Effect operation.

**Example**

```ts
Effect.catchTag(defineServiceEffect(input), "ServiceValidationError", () => Effect.void);
```

**Signature**

```ts
declare class ServiceValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-error.ts#L7)

## `service-members.ts`

### assertUniqueServiceMembersEffect

Reject member names appearing in more than one category.

**Example**

```ts
Effect.runSync(assertUniqueServiceMembersEffect({ lookup }, {}));
```

**Signature**

```ts
declare const assertUniqueServiceMembersEffect: (
  ...args: Array<any>
) => Effect.Effect<undefined, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.ts#L47)

### copyServiceMembersEffect

Copy and validate one category of service members in insertion order.

**Example**

```ts
Effect.runSync(copyServiceMembersEffect({ lookup }, isFunctionDescriptorEffect, "function"));
```

**Signature**

```ts
declare const copyServiceMembersEffect: <T>(
  value: Readonly<Record<string, T>> | undefined,
  validate: ServiceMemberValidator<T>,
  kind: ServiceMemberKind,
) => Effect.Effect<Record<string, T>, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.ts#L14)

## `service-members.types.ts`

### ServiceMemberKind (type alias)

Kinds accepted by service authoring.

**Example**

```ts
const kind: ServiceMemberKind = "function";
```

**Signature**

```ts
type ServiceMemberKind = "function" | "event" | "task" | "job";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.types.ts#L6)

### ServiceMemberValidator (type alias)

Predicate for one member category during Effect validation.

**Example**

```ts
const valid: ServiceMemberValidator<number> = (value) => Effect.succeed(typeof value === "number");
```

**Signature**

```ts
type ServiceMemberValidator<T> = (value: unknown) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.types.ts#L13)

## `service-observability.ts`

### ServiceTelemetry (class)

Substitutable telemetry for all service operations.

**Example**

```ts
Effect.provide(isServiceRefEffect(value), ServiceTelemetryLive);
```

**Signature**

```ts
declare class ServiceTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L8)

### ServiceTelemetryLive

Live span, call, duration, and failure instrumentation.

**Example**

```ts
Effect.provide(isServiceRefEffect(value), ServiceTelemetryLive);
```

**Signature**

```ts
declare const ServiceTelemetryLive: Layer.Layer<ServiceTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L15)

### observeService

Observe one service operation using an injected or live observer.

**Example**

```ts
observeService("ref.is", Effect.succeed(true));
```

**Signature**

```ts
declare const observeService: <A, E, R>(
  operation: ServiceOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L29)

### runServiceSync

Run a dependency-free Effect for a synchronous compatibility caller.

**Throws**

TypeError for local validation, an original dependency error, or a defect.

**Example**

```ts
runServiceSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runServiceSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L68)

## `service-observability.types.ts`

### ServiceOperation (type alias)

Fixed service operation labels keep telemetry dimensions bounded.

**Example**

```ts
const operation: ServiceOperation = "descriptor.is";
```

**Signature**

```ts
type ServiceOperation =
  | "define"
  | "members.copy"
  | "members.unique"
  | "member.normalize"
  | "member.is-reserved"
  | "member.assert"
  | "ref.is"
  | "ref.assert"
  | "descriptor.is"
  | "descriptor.assert"
  | "descriptor.freeze"
  | "descriptor.entries"
  | "function.is"
  | "context.freeze";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.types.ts#L6)

### ServiceTelemetryService (interface)

Injectable observation boundary for service operations.

**Example**

```ts
const telemetry: ServiceTelemetryService = { observe: (_, effect) => effect };
```

**Signature**

```ts
export interface ServiceTelemetryService {
  /** Observe one operation while preserving its channels.
   * @param operation - Fixed operation label.
   * @param effect - Operation to measure.
   * @returns The observed Effect with unchanged success and error channels.
   * @example telemetry.observe("ref.is", Effect.succeed(true));
   */
  readonly observe: <A, E, R>(
    operation: ServiceOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.types.ts#L25)

## `types.ts`

Public declaration relay retained for package source compatibility.

### "./define-service.types.js" (namespace export)

Re-exports all named exports from the "./define-service.types.js" module.

**Signature**

```ts
export * from "./define-service.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/types.ts#L2)

### "./reference-guards.types.js" (namespace export)

Re-exports all named exports from the "./reference-guards.types.js" module.

**Signature**

```ts
export * from "./reference-guards.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/types.ts#L3)

---

# Testing API
Source: https://relkit.dev/docs/api/testing

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [invokeFunction](/docs/api/testing#invokefunction)
- [createTestApplication](/docs/api/testing#createtestapplication)

For configuration and examples, read [testing](/docs/modules/operations/testing), [first service](/docs/modules/service/first-service), [first route](/docs/modules/http/first-route).

For a complete workflow, follow [cache product prices](/guides/caching/cache-product-prices), [build an offline agent](/guides/ai/build-an-offline-agent).

## Public imports

- `@relkit/testing` — 72 exports
- `@relkit/testing/drizzle` — 3 exports
- `@relkit/testing/better-auth` — 3 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                  | Kind  | Import from                                                                 | Example                                                                                                                                                  |
| ------------------------------------------------------------------------------------ | ----- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [assertObservabilityHookTypes](/docs/api/testing#assertobservabilityhooktypes)       | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [assertResponseStatus](/docs/api/testing#assertresponsestatus)                       | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createBunHttpListener](/docs/api/testing#createbunhttplistener)                     | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createDeterministicJobsAdapter](/docs/api/testing#createdeterministicjobsadapter-1) | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/owned-compatibility.ts#L79)                                 |
| [createHttpTestClient](/docs/api/testing#createhttptestclient)                       | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createJobsConformanceHarness](/docs/api/testing#createjobsconformanceharness-1)     | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createObservabilityAssertions](/docs/api/testing#createobservabilityassertions)     | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestAgentStateProvider](/docs/api/testing#createtestagentstateprovider-1)     | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestApplication](/docs/api/testing#createtestapplication)                     | Value | `@relkit/testing`                                                           | [API example](/docs/api/testing#createtestapplication)                                                                                                   |
| [createTestApplication](/docs/api/testing#createtestapplication-2)                   | Value | `@relkit/testing/drizzle`                                                   | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/orders-tutorial/steps/database/tests/integration/hello.route.test.ts#L6) |
| [createTestApplication](/docs/api/testing#createtestapplication-1)                   | Value | `@relkit/testing/better-auth`                                               | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/orders-tutorial/steps/tests/tests/integration/hello.route.test.ts#L6)    |
| [createTestBucket](/docs/api/testing#createtestbucket)                               | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestBucketFake](/docs/api/testing#createtestbucketfake)                       | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/checked-examples.ts#L23)                                    |
| [createTestCache](/docs/api/testing#createtestcache)                                 | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestCacheFake](/docs/api/testing#createtestcachefake)                         | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/checked-examples.ts#L25)                                    |
| [createTestEvent](/docs/api/testing#createtestevent)                                 | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/events.test.ts#L23)                                    |
| [createTestEventFake](/docs/api/testing#createtesteventfake)                         | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestFakes](/docs/api/testing#createtestfakes)                                 | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/owned-compatibility.ts#L75)                                 |
| [createTestHttpClient](/docs/api/testing#createtesthttpclient)                       | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/checked-examples.ts#L31)                                    |
| [createTestHttpListener](/docs/api/testing#createtesthttplistener)                   | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestJob](/docs/api/testing#createtestjob-1)                                   | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/jobs.test.ts#L14)                                      |
| [createTestJobFake](/docs/api/testing#createtestjobfake-1)                           | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestJobsAdapter](/docs/api/testing#createtestjobsadapter-1)                   | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/commerce-layout-tasks.native.ts#L33)                             |
| [createTestObservability](/docs/api/testing#createtestobservability)                 | Value | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/http/http.test.ts#L125)                                                   |
| [createTestRealtimeProvider](/docs/api/testing#createtestrealtimeprovider-1)         | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [createTestRuntime](/docs/api/testing#createtestruntime-1)                           | Value | `@relkit/testing`                                                           | [API example](/docs/api/testing#createtestruntime-1)                                                                                                     |
| [FunctionContextOf](/docs/api/testing#functioncontextof-type-alias)                  | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [FunctionInput](/docs/api/testing#functioninput-type-alias)                          | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [FunctionOutput](/docs/api/testing#functionoutput-type-alias)                        | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [invokeFunction](/docs/api/testing#invokefunction-1)                                 | Value | `@relkit/testing`                                                           | [API example](/docs/api/testing#invokefunction-1)                                                                                                        |
| [InvokeFunctionOptions](/docs/api/testing#invokefunctionoptions-interface)           | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [JOBS_CONFORMANCE_FIXTURES](/docs/api/testing#jobs_conformance_fixtures-1)           | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [JobsConformanceFixture](/docs/api/testing#jobsconformancefixture-interface)         | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [JobsConformanceHarness](/docs/api/testing#jobsconformanceharness-interface)         | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [RealListenerPurpose](/docs/api/testing#reallistenerpurpose-type-alias)              | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [responseJson](/docs/api/testing#responsejson)                                       | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [responseText](/docs/api/testing#responsetext)                                       | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [runJobsConformance](/docs/api/testing#runjobsconformance-1)                         | Value | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [StandaloneFunctionTarget](/docs/api/testing#standalonefunctiontarget-interface)     | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/http/commerce-native-invocation.ts#L16)                                   |
| [TestApplication](/docs/api/testing#testapplication-interface)                       | Type  | `@relkit/testing`, `@relkit/testing/drizzle`, `@relkit/testing/better-auth` | [Source example](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/orders-tutorial/steps/tests/tests/integration/orders.route.test.ts#L58)  |
| [TestApplicationOptions](/docs/api/testing#testapplicationoptions-type-alias)        | Type  | `@relkit/testing`, `@relkit/testing/drizzle`, `@relkit/testing/better-auth` | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/fixtures/checked-examples.ts#L90)                                    |
| [TestBucketFake](/docs/api/testing#testbucketfake-interface)                         | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/runtime-instrumentation.types.ts#L17)                            |
| [TestBucketFakeOptions](/docs/api/testing#testbucketfakeoptions-interface)           | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestBucketObject](/docs/api/testing#testbucketobject-interface)                     | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestCacheFake](/docs/api/testing#testcachefake-type-alias)                          | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestCacheFakeOptions](/docs/api/testing#testcachefakeoptions-interface)             | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestCacheSnapshot](/docs/api/testing#testcachesnapshot-interface)                   | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestClock](/docs/api/testing#testclock-interface)                                   | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestEventCloseOptions](/docs/api/testing#testeventcloseoptions-interface)           | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestEventDeliveryAttempt](/docs/api/testing#testeventdeliveryattempt-interface)     | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestEventFake](/docs/api/testing#testeventfake-interface)                           | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/events.ts#L35)                                                              |
| [TestEventOptions](/docs/api/testing#testeventoptions-interface)                     | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestEventPublishResult](/docs/api/testing#testeventpublishresult-type-alias)        | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestEventTriggerOptions](/docs/api/testing#testeventtriggeroptions-interface)       | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestFailureControls](/docs/api/testing#testfailurecontrols-interface)               | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/runtime-instrumentation.ts#L45)                                  |
| [TestFakes](/docs/api/testing#testfakes-interface)                                   | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestFakesOptions](/docs/api/testing#testfakesoptions-interface)                     | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestHttpApplication](/docs/api/testing#testhttpapplication-interface)               | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestHttpClient](/docs/api/testing#testhttpclient-interface)                         | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/http/http.test.ts#L55)                                                    |
| [TestHttpClientOptions](/docs/api/testing#testhttpclientoptions-interface)           | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestHttpInput](/docs/api/testing#testhttpinput-type-alias)                          | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestHttpListener](/docs/api/testing#testhttplistener-interface)                     | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/http/ownership.test.ts#L68)                                          |
| [TestHttpListenerOptions](/docs/api/testing#testhttplisteneroptions-interface)       | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestHttpRequest](/docs/api/testing#testhttprequest-type-alias)                      | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestJobCloseOptions](/docs/api/testing#testjobcloseoptions-interface)               | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestJobFake](/docs/api/testing#testjobfake-interface)                               | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/contracts/jobs.ts#L56)                                                                |
| [TestJobOptions](/docs/api/testing#testjoboptions-interface)                         | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestJobsAdapter](/docs/api/testing#testjobsadapter-interface)                       | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/fixtures/commerce-layout-task-run.ts#L24)                                 |
| [TestJobsAdapterOptions](/docs/api/testing#testjobsadapteroptions-interface)         | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestObservability](/docs/api/testing#testobservability-interface)                   | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/tests/integration/http/http.test.ts#L51)                                                    |
| [TestProviderReplacements](/docs/api/testing#testproviderreplacements-type-alias)    | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestRuntime](/docs/api/testing#testruntime-interface)                               | Type  | `@relkit/testing`                                                           | [Source example](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/application-http.test.ts#L31)                          |
| [TestRuntimeCloseOptions](/docs/api/testing#testruntimecloseoptions-interface)       | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |
| [TestRuntimeOptions](/docs/api/testing#testruntimeoptions-interface)                 | Type  | `@relkit/testing`                                                           | [Module example](/docs/modules/operations/testing)                                                                                                       |

## `application-acquisition.ts`

Acquires the general runtime and explicitly selected application services in one scope.

### acquireApplication

Native application work shares one scope and reverse-order cleanup policy.

**Signature**

```ts
declare const acquireApplication: (
  app: { readonly env: object },
  options: TestApplicationOptions,
) => Effect.Effect<ApplicationHarness, unknown, Scope | TestApplicationPlatform>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-acquisition.ts#L92)

## `application-cleanup.ts`

Finalizers preserve sibling release and report every application cleanup failure.

### cleanup

Collects release failures and retains them in the Cause when acquisition already failed.

**Signature**

```ts
declare const cleanup: (
  release: () => Promise<unknown> | undefined,
  failures: unknown[],
  failed?: boolean,
) => Effect.Effect<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-cleanup.ts#L5)

## `application-drizzle-services.ts`

Selected database-only test acquisition; authentication SDKs are never imported.

### activateDrizzleTestServices

Acquires the sole database and releases it exactly once with the returned owner.

**Signature**

```ts
declare const activateDrizzleTestServices: TestServiceActivator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-drizzle-services.ts#L21)

## `application-errors.ts`

Normalizes foreign acquisition rejections without replacing native Error identity.

### nativeServiceError

Normalizes foreign acquisition rejections without replacing native Error identity.

**Signature**

```ts
declare const nativeServiceError: <Failure>(cause: Failure) => Error;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-errors.ts#L2)

## `application-generic-services.ts`

General application acquisition never imports a native database or authentication SDK.

### activateGenericTestServices

Rejects an unselected native helper before returning an incomplete application.

**Signature**

```ts
declare const activateGenericTestServices: TestServiceActivator;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-generic-services.ts#L7)

## `application-http.ts`

### handleTestRequest

Dispatches a matched route through existing engine validation and error mapping.

**Signature**

```ts
declare const handleTestRequest: (
  routes: readonly TestRoute[],
  runtime: TestRuntime,
  request: Request,
) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-http.ts#L12)

## `application-native-services.types.ts`

Drizzle/Better Auth contracts reachable only through the selected testing helper.

### ApplicationServicesPlatform (interface)

Native dependencies substituted by test Layers without replacing ownership.

**Signature**

```ts
export interface ApplicationServicesPlatform {
  readonly load: (
    root: string,
  ) => Effect.Effect<readonly DescriptorAny[], Error | SourceLocationError>;
  readonly database: typeof activateDrizzleService;
  readonly auth: typeof activateBetterAuthService;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-native-services.types.ts#L13)

### AuthDeclaration (type alias)

**Signature**

```ts
type AuthDeclaration = Parameters<typeof activateBetterAuthService>[0];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-native-services.types.ts#L10)

### DatabaseDeclaration (type alias)

**Signature**

```ts
type DatabaseDeclaration = Parameters<typeof activateDrizzleService>[0];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-native-services.types.ts#L9)

### NativeAuth (type alias)

**Signature**

```ts
type NativeAuth = Awaited<ReturnType<typeof activateBetterAuthService>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-native-services.types.ts#L8)

### NativeDatabase (type alias)

**Signature**

```ts
type NativeDatabase = Awaited<ReturnType<typeof activateDrizzleService>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-native-services.types.ts#L7)

## `application-platform.ts`

Replaceable application operations and owned harness authorities.

### TestApplicationHarness (class)

Resources and release failures owned by one application Layer scope.

**Signature**

```ts
declare class TestApplicationHarness
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-platform.ts#L16)

### TestApplicationPlatform (class)

Native application dependencies substituted before acquisition.

**Signature**

```ts
declare class TestApplicationPlatform
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-platform.ts#L10)

### TestApplicationPlatformLive

General live platform; selected native helpers enter through explicit options.

**Signature**

```ts
declare const TestApplicationPlatformLive: Layer.Layer<TestApplicationPlatform, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-platform.ts#L22)

## `application-realtime.ts`

### bindTestRealtime

Binds registered realtime contracts to the acquired test provider generation.

**Signature**

```ts
declare const bindTestRealtime: (
  runtime: TestRuntime,
  artifacts: TestApplicationArtifacts | undefined,
  providers: ProviderRegistry | undefined,
  environment: string,
) => TestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-realtime.ts#L15)

## `application-registry.ts`

Loads fresh generated modules with their original native import ancestry and guarded SDK resolution.

### TestApplicationArtifacts

**Signature**

```ts
declare const TestApplicationArtifacts: TestApplicationArtifacts;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-registry.ts#L3)

### loadTestApplicationArtifacts

Loads the generated graph, handlers, and selected integration modules for one test generation.

**Signature**

```ts
declare const loadTestApplicationArtifacts: (
  root: string,
) => Promise<TestApplicationArtifacts | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-registry.ts#L18)

## `application-registry.types.ts`

### TestApplicationArtifacts (interface)

Compiled graph, registry and native integration evidence acquired by an application.

**Signature**

```ts
export interface TestApplicationArtifacts {
  readonly graph: FunctionRegistryOptions["graph"];
  readonly publicFingerprint: string;
  readonly registry: FunctionRegistry;
  readonly runtimeIntegrationModules: readonly LoadedRuntimeIntegrationModule[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-registry.types.ts#L8)

## `application-request.ts`

Routes application test HTTP through actual runtime invocation and selected service authorities.
Request-local auth and context patches are evaluated per request under the application's owned runtime.

### createApplicationRequest

Binds HTTP admission and request-local authentication to an acquired runtime.

**Signature**

```ts
declare const createApplicationRequest: (
  routes: readonly TestRoute[],
  applicationRuntime: TestRuntime,
  services: TestApplicationServices,
  context: Record<string, unknown>,
) => TestHttpApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-request.ts#L19)

## `application-routes.ts`

### TestFunctionRoute

**Signature**

```ts
declare const TestFunctionRoute: TestFunctionRoute;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.ts#L7)

### TestRawRoute

**Signature**

```ts
declare const TestRawRoute: TestRawRoute;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.ts#L7)

### TestRoute

**Signature**

```ts
declare const TestRoute: TestRoute;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.ts#L7)

### loadTestRoutes

Loads filesystem routes and derives native request/response contracts.

**Signature**

```ts
declare const loadTestRoutes: (root: string) => Promise<readonly TestRoute[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.ts#L26)

## `application-routes.types.ts`

### AuthoredRoute (type alias)

Native authored route descriptor accepted by application HTTP wiring.

**Signature**

```ts
type AuthoredRoute = Omit<TestFunctionRoute, "method" | "path" | "request" | "responses"> & {
  readonly accept?: "application/json" | "multipart/form-data";
  readonly request?: unknown;
  readonly responses?: TestFunctionRoute["responses"];
  readonly successStatus?: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.types.ts#L38)

### TestFunctionRoute (type alias)

Native function-backed HTTP route and its declared exposure/validation contract.

**Signature**

```ts
type TestFunctionRoute = {
  readonly method: string;
  readonly path: string;
  readonly request: unknown;
  readonly target: Parameters<TestRuntime["invoke"]>[0] & {
    readonly input: StandardSchemaV1;
    readonly output: StandardSchemaV1;
    readonly errors?: readonly {
      readonly id: string;
      readonly data: StandardSchemaV1;
      readonly http?: { readonly status: number };
    }[];
  };
  readonly responses: readonly {
    readonly kind?: string;
    readonly id?: string;
    readonly status?: number;
    readonly errorId?: string;
  }[];
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.types.ts#L5)

### TestRawRoute (type alias)

Raw native HTTP route preserving its original handler and method contract.

**Signature**

```ts
type TestRawRoute = {
  readonly method: "ALL";
  readonly path: string;
  readonly handler: (request: Request) => Response | Promise<Response>;
  readonly auth?: { readonly protected: readonly string[] };
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.types.ts#L27)

### TestRoute (type alias)

Supported native function or raw HTTP route declaration.

**Signature**

```ts
type TestRoute = TestFunctionRoute | TestRawRoute;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-routes.types.ts#L35)

## `application-service-auth.ts`

Composes auth over a borrowed database without taking a second disposal authority.

### acquireApplicationAuth

Acquires the optional native auth handler and its protection runtime.

**Signature**

```ts
declare const acquireApplicationAuth: (
  platform: ApplicationServicesPlatform,
  declaration: BetterAuthServiceDescriptor<BetterAuthServiceOptions> | undefined,
  database: DrizzleActivation<DrizzleServiceDescriptor<any, any, any, any>> | undefined,
  routes: ReadonlyArray<TestRoute>,
) => Effect.Effect<Pick<TestApplicationServices, "auth" | "authHandler">, Error, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-service-auth.ts#L22)

### nativeServiceError

**Signature**

```ts
declare const nativeServiceError: <Failure>(cause: Failure) => Error;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-service-auth.ts#L59)

## `application-service-discovery.ts`

Finds native service declarations through the shared, syntax-only layout model.

### loadApplicationServices

Loads only evidenced boundaries, in deterministic order, without activating clients.

**Signature**

```ts
declare const loadApplicationServices: (
  root: string,
) => Effect.Effect<Array<DescriptorAny>, Error, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-service-discovery.ts#L20)

### soleNativeService

Selects the sole native declaration by its capability discriminator.

**Throws**

Error When more than one declaration owns the capability.

**Signature**

```ts
declare const soleNativeService: <Kind extends "drizzle" | "better-auth">(
  services: readonly DescriptorAny[],
  kind: Kind,
) => DescriptorAny | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-service-discovery.ts#L78)

## `application-services.ts`

Owns scoped database/auth activation for a test application in either service layout.

### ApplicationServicesPlatform

**Signature**

```ts
declare const ApplicationServicesPlatform: ApplicationServicesPlatform;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L17)

### TestApplicationServices

**Signature**

```ts
declare const TestApplicationServices: TestApplicationServices;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L18)

### TestServices (class)

Database and authentication authorities whose lifetime follows their Layer.

**Signature**

```ts
declare class TestServices
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L39)

### TestServicesPlatform (class)

Native activation dependencies acquired once per application owner.

**Signature**

```ts
declare class TestServicesPlatform
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L21)

### TestServicesPlatformLive

Live native adapters; no database or auth client is acquired by this Layer.

**Signature**

```ts
declare const TestServicesPlatformLive: Layer.Layer<TestServicesPlatform, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L81)

### activateTestServices

Acquires services with an idempotent native shutdown hook.

**Signature**

```ts
declare const activateTestServices: (
  root: string,
  env: ServiceEnvironment,
  routes: readonly TestRoute[],
) => Promise<TestApplicationServices>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L108)

### testServicesLayer

Builds an owner-scoped Layer over replaceable native dependencies.

**Signature**

```ts
declare const testServicesLayer: (
  root: string,
  env: ServiceEnvironment,
  routes: readonly TestRoute[],
) => Layer.Layer<TestServices, Error, TestServicesPlatform>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.ts#L93)

## `application-services.types.ts`

Native application service ownership and replaceable activation dependencies.

### ServiceEnvironment (type alias)

Uses the existing generic runtime's environment contract without an SDK dependency.

**Signature**

```ts
type ServiceEnvironment = TestRuntime["env"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.types.ts#L7)

### TestApplicationServices (interface)

Acquired owner-specific authorities; auth borrows the sole database.

**Signature**

```ts
export interface TestApplicationServices {
  readonly context: NonNullable<TestRuntimeOptions["context"]>;
  readonly auth?: HttpAuthRuntime;
  readonly authHandler?: (request: Request) => Promise<Response>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.types.ts#L10)

### TestServiceActivator (type alias)

Explicit capability helper selected before application acquisition.

**Signature**

```ts
type TestServiceActivator = (
  root: string,
  env: ServiceEnvironment,
  routes: readonly TestRoute[],
) => Promise<TestApplicationServices>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application-services.types.ts#L18)

## `application.ts`

General test application ownership with explicitly selected capability helpers.

### createTestApplication

Creates an application owner with HTTP, deterministic runtime and provider services.

**Example**

```ts
import { defineEnv } from "@relkit/app/config";
import { createTestApplication } from "@relkit/testing";
async function testApplication(projectRoot: string): Promise<void> {
  const app = await createTestApplication({ env: defineEnv({}) }, { projectRoot });
  try {
    await app.http.get("/");
  } finally {
    await app.close();
  }
}
```

**Signature**

```ts
declare const createTestApplication: (
  app: { readonly env: object },
  options?: TestApplicationOptions,
) => Promise<TestApplication>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L32)

Since v0.1.0

### TestApplication

**Signature**

```ts
declare const TestApplication: TestApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L13)

### TestApplicationHarness

**Signature**

```ts
declare const TestApplicationHarness: typeof TestApplicationHarness;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L9)

### TestApplicationOptions

**Signature**

```ts
declare const TestApplicationOptions: TestApplicationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L13)

### TestApplicationPlatform

**Signature**

```ts
declare const TestApplicationPlatform: typeof TestApplicationPlatform;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L10)

### TestApplicationPlatformLive

**Signature**

```ts
declare const TestApplicationPlatformLive: Layer.Layer<TestApplicationPlatform, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L11)

### testApplicationLayer

Acquires the application scope using replaceable platform operations.

**Signature**

```ts
declare const testApplicationLayer: (
  app: { readonly env: object },
  options?: TestApplicationOptions,
) => Layer.Layer<TestApplicationHarness, unknown, TestApplicationPlatform>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.ts#L61)

## `application.types.ts`

Describes the owned test application and replaceable acquisition platform.
Generic contracts retain existing runtime environment/context semantics without a native auth or database SDK edge.

### ApplicationHarness (interface)

Effect-owned application request workflow and native application state.

**Signature**

```ts
export interface ApplicationHarness {
  readonly value: Omit<TestApplication, "close">;
  readonly cleanupFailures: unknown[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.types.ts#L40)

### ApplicationPlatform (interface)

Replaceable application acquisition operations used by the owning service Layer.

**Signature**

```ts
export interface ApplicationPlatform {
  readonly artifacts: typeof loadTestApplicationArtifacts;
  readonly routes: typeof loadTestRoutes;
  readonly providers: typeof activateTestProviders;
  readonly services: TestServiceActivator;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.types.ts#L32)

### TestApplication (interface)

Owned compiled test application, direct HTTP facade and complete release boundary.

**Signature**

```ts
export interface TestApplication {
  readonly runtime: TestRuntime;
  readonly http: TestHttpClient;
  readonly clock: TestClock;
  readonly fakes: TestFakes;
  readonly observability: TestObservability;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.types.ts#L22)

### TestApplicationOptions (type alias)

Explicit test application project, environment and native platform inputs.

**Signature**

```ts
type TestApplicationOptions = Omit<TestRuntimeOptions, "app"> & {
  readonly projectRoot?: string;
  readonly bindingValues?: Readonly<Record<string, JsonValue>>;
  readonly resourceProviders?: "configured" | "fake";
  readonly services?: TestServiceActivator;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/application.types.ts#L14)

## `better-auth.ts`

Explicit database-backed authentication test application facade.

### TestApplication

**Signature**

```ts
declare const TestApplication: TestApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/better-auth.ts#L5)

### TestApplicationOptions

**Signature**

```ts
declare const TestApplicationOptions: TestApplicationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/better-auth.ts#L5)

### createTestApplication

Acquires auth over a borrowed database while preserving general harness ownership.

**Signature**

```ts
declare const createTestApplication: (
  app: { readonly env: object },
  options?: TestApplicationOptions,
) => Promise<TestApplication>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/better-auth.ts#L8)

## `bucket-storage.schemas.ts`

### BucketStorageSnapshot

Schema authority for detached native fake bucket transfers.

**Signature**

```ts
declare const BucketStorageSnapshot: Schema.Struct<{
  readonly bucketId: Schema.String;
  readonly records: Schema.$Array<
    Schema.Struct<{
      readonly key: Schema.String;
      readonly bytes: Schema.Uint8Array;
      readonly metadata: Schema.Struct<{
        readonly etag: Schema.String;
        readonly contentHash: Schema.optionalKey<Schema.String>;
        readonly size: Schema.optionalKey<Schema.Finite>;
        readonly contentType: Schema.optionalKey<Schema.String>;
        readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
      }>;
    }>
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-storage.schemas.ts#L4)

## `bucket-storage.ts`

### TestBucketStorage (class)

Authoritative writable bucket state; every public read returns detached bytes/metadata.

**Signature**

```ts
declare class TestBucketStorage
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-storage.ts#L22)

### bucketStorageLayer

Owns one isolated bucket, validating options before allocating its temporary root.

**Signature**

```ts
declare const bucketStorageLayer: (
  options?: TestBucketFakeOptions,
) => Layer.Layer<TestBucketStorage, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-storage.ts#L31)

## `bucket-storage.types.ts`

### BucketStorageService (interface)

Effect decisions over authoritative writable bucket bytes and native metadata.

**Signature**

```ts
export interface BucketStorageService {
  readonly stateRoot: string;
  readonly put: (
    ...args: Parameters<NonNullable<BucketProvider["put"]>>
  ) => Effect.Effect<void, unknown>;
  readonly get: (
    ...args: Parameters<NonNullable<BucketProvider["get"]>>
  ) => Effect.Effect<Uint8Array | undefined, unknown>;
  readonly head: (
    ...args: Parameters<NonNullable<BucketProvider["head"]>>
  ) => Effect.Effect<BucketObjectMetadata | undefined, unknown>;
  readonly delete: (
    ...args: Parameters<NonNullable<BucketProvider["delete"]>>
  ) => Effect.Effect<void, unknown>;
  readonly exists: (
    ...args: Parameters<NonNullable<BucketProvider["exists"]>>
  ) => Effect.Effect<boolean, unknown>;
  readonly list: (
    ...args: Parameters<NonNullable<BucketProvider["list"]>>
  ) => Effect.Effect<readonly string[], unknown>;
  readonly inspect: Effect.Effect<readonly TestBucketObject[]>;
  readonly snapshot: Effect.Effect<BucketStorageSnapshot>;
  readonly restore: (snapshot: unknown) => Effect.Effect<void, unknown>;
  readonly clear: Effect.Effect<void>;
  readonly close: Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-storage.types.ts#L10)

### BucketStorageSnapshot (type alias)

Detached native bucket transfer derived from its decoding schema authority.

**Signature**

```ts
type BucketStorageSnapshot = typeof SnapshotSchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-storage.types.ts#L7)

## `bucket-validation.ts`

### assertBucketKey

Rejects unsafe or empty native bucket keys.

**Signature**

```ts
declare const assertBucketKey: (value: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-validation.ts#L10)

### assertBucketPrefix

Validates the existing optional bucket listing prefix.

**Signature**

```ts
declare const assertBucketPrefix: (value: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-validation.ts#L30)

### copyBucketMetadata

Detaches nested native bucket metadata.

**Signature**

```ts
declare const copyBucketMetadata: (
  value: BucketObjectMetadata | undefined,
) => BucketObjectMetadata | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-validation.ts#L42)

### copyBucketObject

Detaches stored bytes and nested native metadata.

**Signature**

```ts
declare const copyBucketObject: (value: TestBucketObject) => TestBucketObject;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/bucket-validation.ts#L57)

## `buckets-types.ts`

Preserved compatibility entrypoint for the canonical domain type companion.

### "./buckets.types.js" (namespace export)

Re-exports all named exports from the "./buckets.types.js" module.

**Signature**

```ts
export * from "./buckets.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets-types.ts#L2)

## `buckets.ts`

### TestBucketFake

**Signature**

```ts
declare const TestBucketFake: TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.ts#L8)

### TestBucketFakeOptions

**Signature**

```ts
declare const TestBucketFakeOptions: TestBucketFakeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.ts#L8)

### TestBucketObject

**Signature**

```ts
declare const TestBucketObject: TestBucketObject;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.ts#L8)

### createTestBucket

**Signature**

```ts
declare const createTestBucket: (options?: TestBucketFakeOptions) => TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.ts#L77)

### createTestBucketFake

Creates an authoritative in-memory provider behind the production Promise client.

**See**

- tests/fixtures/checked-examples.ts ownedHelpersExample for checked resource ownership.

**Signature**

```ts
declare const createTestBucketFake: (options?: TestBucketFakeOptions) => TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.ts#L16)

## `buckets.types.ts`

### TestBucketFake (interface)

Owned native bucket client with deterministic transfer and inspection controls.

**Signature**

```ts
export interface TestBucketFake extends BucketClient {
  readonly capabilities: { readonly signedReadUrl: false; readonly signedWriteUrl: false };
  readonly provider: BucketProvider;
  readonly client: BucketClient;
  readonly stateRoot: string;
  readonly seed: (key: string, bytes: Uint8Array, options?: BucketPutOptions) => Promise<void>;
  readonly read: (key: string) => Promise<Uint8Array | undefined>;
  readonly inspect: () => readonly TestBucketObject[];
  readonly snapshot: () => import("./bucket-storage.types.js").BucketStorageSnapshot;
  readonly restore: (snapshot: unknown) => void;
  readonly clear: () => void;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.types.ts#L29)

### TestBucketFakeOptions (interface)

Bucket write policy and explicit clock, root and failure dependencies.

**Signature**

```ts
export interface TestBucketFakeOptions {
  readonly bucketId?: string;
  readonly ownerId?: string;
  readonly stateRoot?: string;
  readonly clock?: () => number;
  readonly failures?: TestFailureControls;
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly maxObjectBytes?: number;
  readonly allowedContentTypes?: readonly string[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.types.ts#L10)

### TestBucketObject (interface)

Detached native bucket bytes and metadata selected by a stable key.

**Signature**

```ts
export interface TestBucketObject {
  readonly key: string;
  readonly bytes: Uint8Array;
  readonly metadata: BucketObjectMetadata;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/buckets.types.ts#L22)

## `cache-storage-state.ts`

### cacheStorageOperations

Binds native cache validation and committed mutations to one authoritative Ref.

**Signature**

```ts
declare const cacheStorageOperations: (
  state: Ref.Ref<CacheStorageState>,
  policy: CacheStoragePolicy,
) => {
  open: () => CacheStorageState;
  keyOf: (key: unknown) => string;
  active: (context: CacheOperationContext | undefined) => number;
  readEntry: (key: unknown, context: CacheOperationContext | undefined) => CacheEntry | undefined;
  writeEntry: (
    key: unknown,
    value: unknown,
    write: CacheOperationOptions | undefined,
    context: CacheOperationContext | undefined,
  ) => void;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage-state.ts#L17)

## `cache-storage.schemas.ts`

### CacheStorageKey

Restored keys retain the canonical identity produced by the native fake.

**Signature**

```ts
declare const CacheStorageKey: Schema.Struct<{
  readonly cacheId: Schema.String;
  readonly schemaVersion: Schema.Union<readonly [Schema.String, Schema.Number]>;
  readonly key: Schema.Unknown;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.schemas.ts#L4)

### CacheStorageSnapshot

Detached storage transfer; restoring requires matching cache identity/version.

**Signature**

```ts
declare const CacheStorageSnapshot: Schema.Struct<{
  readonly cacheId: Schema.String;
  readonly schemaVersion: Schema.Union<readonly [Schema.String, Schema.Number]>;
  readonly records: Schema.$Array<
    Schema.Struct<{
      readonly key: Schema.String;
      readonly value: Schema.Unknown;
      readonly expiresAt: Schema.optionalKey<Schema.Finite>;
    }>
  >;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.schemas.ts#L11)

## `cache-storage.ts`

### TestCacheStorage (class)

Authoritative writable cache state, never subject to memoization eviction.

**Signature**

```ts
declare class TestCacheStorage
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.ts#L12)

### cacheStorageLayer

Acquires one isolated fake root with scoped release and native cache semantics.

**Signature**

```ts
declare const cacheStorageLayer: (
  options: TestCacheFakeOptions,
) => Layer.Layer<TestCacheStorage, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.ts#L21)

## `cache-storage.types.ts`

### CacheEntry (interface)

Detached authoritative cache value with an optional deterministic expiration timestamp.

**Signature**

```ts
export interface CacheEntry {
  readonly value: unknown;
  readonly expiresAt?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.types.ts#L12)

### CacheStoragePolicy (interface)

Validated native write policy captured once before storage acquisition.

**Signature**

```ts
export interface CacheStoragePolicy {
  readonly cacheId: string;
  readonly schemaVersion: string | number;
  readonly clock: () => number;
  readonly failures: TestFailureControls;
  readonly defaultTtlMs: number | undefined;
  readonly maxTtlMs: number | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.types.ts#L25)

### CacheStorageService (interface)

Effect decisions over authoritative writable cache state and transfer boundaries.

**Signature**

```ts
export interface CacheStorageService {
  readonly stateRoot: string;
  readonly get: (
    ...args: Parameters<NonNullable<CacheProvider["get"]>>
  ) => Effect.Effect<unknown, unknown>;
  readonly set: (
    ...args: Parameters<NonNullable<CacheProvider["set"]>>
  ) => Effect.Effect<void, unknown>;
  readonly delete: (
    ...args: Parameters<NonNullable<CacheProvider["delete"]>>
  ) => Effect.Effect<void, unknown>;
  readonly has: (
    ...args: Parameters<NonNullable<CacheProvider["has"]>>
  ) => Effect.Effect<boolean, unknown>;
  readonly getOrSet: (
    ...args: Parameters<NonNullable<CacheProvider["getOrSet"]>>
  ) => Effect.Effect<unknown, unknown>;
  readonly increment: (
    ...args: Parameters<NonNullable<CacheProvider["increment"]>>
  ) => Effect.Effect<number, unknown>;
  readonly inspect: Effect.Effect<TestCacheSnapshot>;
  readonly snapshot: Effect.Effect<CacheStorageSnapshot>;
  readonly restore: (snapshot: unknown) => Effect.Effect<void, unknown>;
  readonly clear: Effect.Effect<void>;
  readonly close: Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.types.ts#L35)

### CacheStorageSnapshot (type alias)

Detached native cache transfer derived from its decoding schema authority.

**Signature**

```ts
type CacheStorageSnapshot = typeof SnapshotSchema.Type;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.types.ts#L9)

### CacheStorageState (interface)

Authoritative state survives until explicit owner release, without eviction.

**Signature**

```ts
export interface CacheStorageState {
  closed: boolean;
  readonly entries: Map<string, CacheEntry>;
  readonly flights: Map<string, Promise<unknown>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-storage.types.ts#L18)

## `cache-types.ts`

Preserved compatibility entrypoint for the canonical domain type companion.

### "./cache.types.js" (namespace export)

Re-exports all named exports from the "./cache.types.js" module.

**Signature**

```ts
export * from "./cache.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache-types.ts#L2)

## `cache.ts`

### TestCacheFake

**Signature**

```ts
declare const TestCacheFake: TestCacheFake<Key, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.ts#L14)

### TestCacheFakeOptions

**Signature**

```ts
declare const TestCacheFakeOptions: TestCacheFakeOptions<KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.ts#L14)

### TestCacheSnapshot

**Signature**

```ts
declare const TestCacheSnapshot: TestCacheSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.ts#L14)

### createTestCache

**Signature**

```ts
declare const createTestCache: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.ts#L98)

### createTestCacheFake

Creates authoritative cache storage behind the production Promise client.

**See**

- tests/fixtures/checked-examples.ts ownedHelpersExample for checked schema inference.

**Signature**

```ts
declare const createTestCacheFake: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.ts#L24)

## `cache.types.ts`

### TestCacheFake (type alias)

Authoritative writable native cache facade with detached transfer and release controls.

**Signature**

```ts
type TestCacheFake<Key, Value> = CacheClient<Key, Value> & {
  readonly provider: CacheProvider;
  readonly client: CacheClient<Key, Value>;
  readonly capabilities: { readonly increment: true };
  readonly stateRoot: string;
  readonly seed: (key: Key, value: Value, options?: CacheOperationOptions) => Promise<void>;
  readonly read: (key: Key) => Promise<Value | undefined>;
  readonly increment: (
    key: Key,
    delta?: number,
    options?: CacheOperationOptions,
  ) => Promise<number>;
  readonly inspect: () => TestCacheSnapshot;
  readonly snapshot: () => import("./cache-storage.types.js").CacheStorageSnapshot;
  readonly restore: (snapshot: unknown) => void;
  readonly clear: () => void;
  readonly close: () => Promise<void>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.types.ts#L40)

### TestCacheFakeOptions (interface)

Native key/value schemas, TTL policy and explicit fake-owner dependencies.

**Signature**

```ts
export interface TestCacheFakeOptions<
  KeySchema extends StandardSchemaV1 = StandardSchemaV1,
  ValueSchema extends StandardSchemaV1 = StandardSchemaV1,
> {
  readonly cacheId?: string;
  readonly ownerId?: string;
  readonly stateRoot?: string;
  readonly clock?: () => number;
  readonly failures?: TestFailureControls;
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly keySchema?: KeySchema;
  readonly valueSchema?: ValueSchema;
  readonly defaultTtlMs?: number;
  readonly maxTtlMs?: number;
  readonly schemaVersion?: string | number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.types.ts#L10)

### TestCacheSnapshot (interface)

Native cache occupancy and identity evidence without memoization eviction.

**Signature**

```ts
export interface TestCacheSnapshot {
  readonly cacheId: string;
  readonly schemaVersion: string | number;
  readonly entries: number;
  readonly inFlight: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/cache.types.ts#L28)

## `drizzle.ts`

Selected database application harness; database ownership remains scoped to each test.

### TestApplication

**Signature**

```ts
declare const TestApplication: TestApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/drizzle.ts#L5)

### TestApplicationOptions

**Signature**

```ts
declare const TestApplicationOptions: TestApplicationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/drizzle.ts#L5)

### createTestApplication

Acquires the general harness with the explicit native database service installer.

**Signature**

```ts
declare const createTestApplication: (
  app: { readonly env: object },
  options?: TestApplicationOptions,
) => Promise<TestApplication>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/drizzle.ts#L8)

## `event-controls.types.ts`

### EventControlsService (interface)

Effect publication, delivery, inspection and lifecycle operations over native authorities.

**Signature**

```ts
export interface EventControlsService {
  readonly publish: (
    ...args: Parameters<EventProvider["publish"]>
  ) => Effect.Effect<Awaited<ReturnType<EventProvider["publish"]>>, unknown>;
  readonly pending: (triggerId?: string) => Effect.Effect<number, unknown>;
  readonly completed: (triggerId?: string) => Effect.Effect<number, unknown>;
  readonly runNext: (triggerId?: string) => Effect.Effect<EventDeliveryResult | undefined, unknown>;
  readonly drain: Effect.Effect<readonly EventDeliveryResult[], unknown>;
  readonly restart: Effect.Effect<void, unknown>;
  readonly close: (options?: TestEventCloseOptions) => Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/event-controls.types.ts#L7)

## `events-inspection.ts`

### completedEventDeliveries

Counts acknowledged durable and ephemeral deliveries.

**Signature**

```ts
declare const completedEventDeliveries: (
  state: TestEventControlState,
  triggerId?: string,
) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-inspection.ts#L38)

### pendingEventDeliveries

Counts eligible durable deliveries and persisted publications still awaiting fanout.

**Signature**

```ts
declare const pendingEventDeliveries: (state: TestEventControlState, triggerId?: string) => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-inspection.ts#L10)

## `events-lifecycle.ts`

### eventLifecycle

Composes restart and final release under the event service's scoped ownership.

**Signature**

```ts
declare const eventLifecycle: (
  state: TestEventControlState,
  scope: Scope.Scope,
  context: Context.Context<never>,
) => {
  restart: Effect.Effect<void, unknown, never>;
  close: (failed?: boolean) => Effect.Effect<void, unknown, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-lifecycle.ts#L13)

## `events-runtime-controls.ts`

### TestEventControlState

**Signature**

```ts
declare const TestEventControlState: TestEventControlState;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.ts#L5)

### TestEventControls

**Signature**

```ts
declare const TestEventControls: TestEventControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.ts#L5)

### TestEventExecution (class)

Delivery admission, retry/fanout and release belong to one event owner.

**Signature**

```ts
declare class TestEventExecution
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.ts#L92)

### createTestEventControls

Exposes synchronous inspection and Promise work through one owned runtime.

**Signature**

```ts
declare const createTestEventControls: (state: TestEventControlState) => Promise<TestEventControls>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.ts#L122)

### eventControlsLayer

Owns the native delivery lifecycle; alternate Layers retain this service contract.

**Signature**

```ts
declare const eventControlsLayer: (
  state: TestEventControlState,
) => Layer.Layer<TestEventExecution, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.ts#L101)

## `events-runtime-controls.types.ts`

### TestEventControlState (interface)

Native authorities and Effect workflows owned by one event service Layer.

**Signature**

```ts
export interface TestEventControlState {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly router: () => EventRouter;
  readonly log: () => { readonly close: () => Promise<void> };
  readonly open: Effect.Effect<void, unknown>;
  readonly release: Effect.Effect<void, unknown>;
  readonly work: WorkOwnershipState;
  readonly openFanout: (envelope: UnknownEventEnvelope) => Effect.Effect<void, unknown>;
  readonly owner: TestStateRoot;
  readonly failures: TestFailureControls;
  readonly triggers: readonly {
    readonly id: string;
    readonly eventId: string;
    readonly eventVersion: number;
  }[];
  readonly envelopes: readonly UnknownEventEnvelope[];
  readonly unfanned: Map<string, UnknownEventEnvelope>;
  readonly remember: (result: EventDeliveryResult, envelope: UnknownEventEnvelope) => void;
  readonly publish: (
    ...args: Parameters<EventProvider["publish"]>
  ) => Effect.Effect<Awaited<ReturnType<EventProvider["publish"]>>, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.types.ts#L10)

### TestEventControls (interface)

Native Promise facade preserving publication, inspection and delivery signatures.

**Signature**

```ts
export interface TestEventControls {
  readonly publishNative: EventProvider["publish"];
  readonly pending: (triggerId?: string) => number;
  readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
  readonly drain: () => Promise<readonly EventDeliveryResult[]>;
  readonly completed: (triggerId?: string) => number;
  readonly restart: () => Promise<void>;
  readonly close: (options?: TestEventCloseOptions) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-controls.types.ts#L34)

## `events-runtime-open.ts`

### OpenTestEventRuntimeOptions

**Signature**

```ts
declare const OpenTestEventRuntimeOptions: OpenTestEventRuntimeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-open.ts#L2)

### openTestEventRuntime

Acquires log/router resources and materializes the declared event plan.

**Signature**

```ts
declare const openTestEventRuntime: (
  input: OpenTestEventRuntimeOptions,
) => Effect.Effect<
  { log: EventLog; router: EventRouter; generation: number; storedCount: number },
  unknown,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-open.ts#L17)

## `events-runtime-open.types.ts`

### OpenTestEventRuntimeOptions (interface)

Native log/router acquisition inputs and deterministic generation identity.

**Signature**

```ts
export interface OpenTestEventRuntimeOptions {
  readonly profile: string;
  readonly plan: Parameters<typeof materializeEvents>[0]["plan"];
  readonly owner: TestStateRoot;
  readonly options: TestEventOptions<unknown, unknown>;
  readonly now: () => number;
  readonly random: () => number;
  readonly failures: TestFailureControls;
  readonly runner: InvocationRunner;
  readonly idSource: Parameters<typeof createEventInvoker>[4];
  readonly targets: ReadonlyMap<string, InvocationTarget<unknown, unknown>>;
  readonly generation: number;
  readonly ownerSignal?: () => AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-open.types.ts#L10)

## `events-runtime-utils.ts`

### createEventInvoker

Binds native event invocation to deterministic dependencies and cancellation.

**Signature**

```ts
declare const createEventInvoker: (
  targets: ReadonlyMap<string, InvocationTarget<unknown, unknown>>,
  options: TestEventOptions<unknown, unknown>,
  now: () => number,
  runner: InvocationRunner,
  idSource: InvocationIdSource,
  ownerSignal?: () => AbortSignal,
) => (request: EventInvocationOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-utils.ts#L102)

### createEventTraceBridge

Binds event producer spans to deterministic native invocation identities.

**Signature**

```ts
declare const createEventTraceBridge: (
  eventId: string,
  options: Pick<TestEventOptions<unknown, unknown>, "correlationId" | "causationInvocationId">,
  clock: DeterministicClockService,
  ids: InvocationIdSource,
) => {
  run: <A>(
    operation: () => MaybePromise<A>,
    bridgeOptions?: { readonly name?: string },
  ) => Promise<A>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-utils.ts#L40)

### fanoutEvent

Routes a persisted publication before removing its acknowledgement-gap marker.

**Signature**

```ts
declare const fanoutEvent: (
  router: EventRouter,
  envelope: UnknownEventEnvelope,
  unfanned: Map<string, UnknownEventEnvelope>,
  failures: TestFailureControls,
) => Effect.Effect<void, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-utils.ts#L149)

### toEnvelope

Detaches an event envelope through the existing canonical JSON authority.

**Signature**

```ts
declare const toEnvelope: (value: Record<string, unknown>) => UnknownEventEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime-utils.ts#L28)

## `events-runtime.ts`

### TestEventRuntimeOptions

**Signature**

```ts
declare const TestEventRuntimeOptions: TestEventRuntimeOptions<Payload, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.ts#L6)

### createTestEventRuntime

Builds the native event publication and delivery owner.

**Signature**

```ts
declare const createTestEventRuntime: <Payload, Output>(
  input: TestEventRuntimeOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.ts#L34)

## `events-runtime.types.ts`

### EventRuntimeState (interface)

All publication, fanout and admission state belongs to one event owner.

**Signature**

```ts
export interface EventRuntimeState extends WorkOwnershipState {
  readonly envelopes: UnknownEventEnvelope[];
  readonly attempts: TestEventDeliveryAttempt[];
  readonly unfanned: Map<string, UnknownEventEnvelope>;
  generation: number;
  sequence: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.types.ts#L35)

### OpenedEventRuntime (type alias)

Native generation acquired by the event owner's ordered Effect workflow.

**Signature**

```ts
type OpenedEventRuntime = Effect.Success<ReturnType<typeof openTestEventRuntime>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.types.ts#L32)

### TestEventRuntimeOptions (interface)

Dependencies required to acquire one event log/router generation.

**Signature**

```ts
export interface TestEventRuntimeOptions<Payload, Output> {
  readonly eventId: string;
  readonly version: number;
  readonly profile: string;
  readonly triggers: readonly TestTrigger<Output>[];
  readonly plan: Parameters<typeof materializeEvents>[0]["plan"];
  readonly owner: TestStateRoot;
  readonly deterministic: ReturnType<typeof createDeterministicClock>;
  readonly failures: TestFailureControls;
  readonly random: () => number;
  readonly runner: InvocationRunner;
  readonly idSource: InvocationIdSource;
  readonly options: TestEventOptions<Payload, Output>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.types.ts#L48)

### TestTrigger (type alias)

Normalized event trigger identity, delivery policy and native target.

**Signature**

```ts
type TestTrigger<Output> = TestEventTriggerOptions<Output> & {
  readonly delivery: "ephemeral" | "durable";
  readonly profile: string;
  readonly eventId: string;
  readonly eventVersion: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-runtime.types.ts#L24)

## `events-types.ts`

Preserved compatibility entrypoint for the canonical domain type companion.

### "./events.types.js" (namespace export)

Re-exports all named exports from the "./events.types.js" module.

**Signature**

```ts
export * from "./events.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events-types.ts#L2)

## `events.ts`

### createTestEvent

Creates a deterministic event publication and delivery harness.

**Signature**

```ts
declare const createTestEvent: <Payload = unknown, Output = unknown>(
  options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.ts#L18)

### createTestEventFake

**Signature**

```ts
declare const createTestEventFake: <Payload = unknown, Output = unknown>(
  options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.ts#L56)

## `events.types.ts`

### NormalizedTrigger (type alias)

Validated event trigger identity and policy used by native materialization.

**Signature**

```ts
type NormalizedTrigger<Output> = TestEventTriggerOptions<Output> & {
  readonly delivery: "ephemeral" | "durable";
  readonly profile: string;
  readonly eventId: string;
  readonly eventVersion: number;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L119)

### TestEventCloseOptions (interface)

Explicit failed-test state retention policy for event shutdown.

**Signature**

```ts
export interface TestEventCloseOptions {
  readonly failed?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L70)

### TestEventDeliveryAttempt (interface)

Native delivery outcome paired with its canonical persisted event envelope.

**Signature**

```ts
export interface TestEventDeliveryAttempt extends EventDeliveryResult {
  readonly envelope: UnknownEventEnvelope;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L75)

### TestEventFake (interface)

Owned native publication/delivery facade with truthful deterministic ledgers.

**Signature**

```ts
export interface TestEventFake<Payload = unknown, Output = unknown> extends EventClient<
  Payload,
  string,
  number,
  Payload
> {
  readonly id: string;
  readonly eventId: string;
  readonly version: number;
  readonly client: EventClient<Payload, string, number, Payload>;
  readonly provider: EventProvider;
  readonly stateRoot: string;
  readonly clock: TestClock;
  readonly failures: TestFailureControls;
  readonly pending: (triggerId?: string) => number;
  readonly runNext: (triggerId?: string) => Promise<EventDeliveryResult | undefined>;
  readonly drain: () => Promise<readonly EventDeliveryResult[]>;
  readonly completed: (triggerId?: string) => number;
  readonly restart: () => Promise<void>;
  readonly envelopes: readonly UnknownEventEnvelope[];
  readonly attempts: readonly TestEventDeliveryAttempt[];
  readonly deliveries: readonly EventDeliveryLedgerRecord[];
  readonly close: (options?: TestEventCloseOptions) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L84)

### TestEventInvocation (type alias)

Native invocation request consumed by an event target fixture.

**Signature**

```ts
type TestEventInvocation = EventInvocationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L113)

### TestEventOptions (interface)

Event publication contract, native consumers and deterministic fixture dependencies.

**Signature**

```ts
export interface TestEventOptions<Payload = unknown, Output = unknown> {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly event?: EventDescriptorAny;
  readonly events?: readonly EventDescriptorAny[];
  readonly eventId?: string;
  readonly version?: number;
  readonly payloadSchema?: StandardSchemaV1;
  readonly target?: EventFunctionDescriptorAny;
  readonly triggers?: readonly TestEventTriggerOptions<Output>[];
  readonly triggerId?: string;
  readonly delivery?: "ephemeral" | "durable";
  readonly profile?: string;
  readonly ownerId?: string;
  readonly correlationId?: string;
  readonly causationInvocationId?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly stateRoot?: string;
  readonly startTimeMs?: number;
  readonly leaseDurationMs?: number;
  readonly ephemeralCapacity?: number;
  readonly random?: () => number;
  readonly randomValues?: readonly number[];
  readonly failures?: TestFailureControls;
  readonly env?: Readonly<Record<string, unknown>>;
  readonly clients?: DependencyClientSources;
  readonly hooks?: InvocationHooks;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L40)

### TestEventPublishResult (type alias)

Native accepted publication receipt retained by the public event fixture.

**Signature**

```ts
type TestEventPublishResult = EventPublishResult<string, number, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L110)

### TestEventTriggerOptions (interface)

Native target and per-trigger delivery, retry and worker concurrency policy.

**Signature**

```ts
export interface TestEventTriggerOptions<Output = unknown> {
  readonly id: string;
  readonly target: EventFunctionDescriptorAny;
  readonly delivery?: "ephemeral" | "durable";
  readonly profile?: string;
  readonly retry?: RetryPolicy;
  readonly concurrency?: number;
  readonly timeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/events.types.ts#L25)

## `fake-utils.ts`

### TestFakeRoot

**Signature**

```ts
declare const TestFakeRoot: TestFakeRoot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L2)

### assertFailurePoint

Validates the existing dependency-fake failure boundary name.

**Signature**

```ts
declare const assertFailurePoint: (point: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L76)

### assertName

Rejects empty dependency client names.

**Signature**

```ts
declare const assertName: (name: string) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L106)

### clone

Detaches native fixture data using structured cloning.

**Signature**

```ts
declare const clone: (value: unknown) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L60)

### createFakeRoot

Acquires a category-specific persistence path beneath an owned state root.

**Signature**

```ts
declare const createFakeRoot: (
  requestedPath: string | undefined,
  category: string,
  id: string,
) => TestFakeRoot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L15)

### lazyRecords

Creates owner-local dependency instances only on first named access.

**Signature**

```ts
declare const lazyRecords: <T>(
  records: Record<string, T>,
  create: (id: string) => T,
) => Record<string, T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L87)

### noFailures

**Signature**

```ts
declare const noFailures: TestFailureControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L64)

### positive

Validates the existing optional positive TTL policy.

**Signature**

```ts
declare const positive: (value: number | undefined, name: string) => number | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L48)

### text

Validates and trims a required fake storage identity.

**Signature**

```ts
declare const text: (value: string, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.ts#L37)

## `fake-utils.types.ts`

Owned native storage subdirectory and idempotent temporary-parent cleanup.

### TestFakeRoot (interface)

Owned native storage subdirectory and idempotent temporary-parent cleanup.

**Signature**

```ts
export interface TestFakeRoot {
  readonly stateRoot: string;
  readonly cleanup: (failed: boolean) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fake-utils.types.ts#L2)

## `fakes.ts`

### TestFailureControls

**Signature**

```ts
declare const TestFailureControls: TestFailureControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L6)

### TestFakeProviders (class)

Native dependency sources and their storage release share a single test owner.

**Signature**

```ts
declare class TestFakeProviders
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L192)

### TestFakes

**Signature**

```ts
declare const TestFakes: TestFakes;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L6)

### TestFakesOptions

**Signature**

```ts
declare const TestFakesOptions: TestFakesOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L6)

### createTestFakes

Creates fresh native dependency sources with an owned Effect lifetime.

**Signature**

```ts
declare const createTestFakes: (stateRoot: string, options?: TestFakesOptions) => TestFakes;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L222)

### fakeProvidersLayer

Acquires synchronous fake dependencies and scopes all storage created lazily later.

**Signature**

```ts
declare const fakeProvidersLayer: (
  stateRoot: string,
  options?: TestFakesOptions,
) => Layer.Layer<TestFakeProviders, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.ts#L202)

## `fakes.types.ts`

### TestFailureControls (interface)

Owner-local native failure injection with explicit one-shot and persistent boundaries.

**Signature**

```ts
export interface TestFailureControls {
  readonly failAt: (point: string, cause?: unknown) => void;
  readonly once?: (point: string, cause?: unknown) => void;
  readonly clear: (point?: string) => void;
  readonly check: (point: string) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.types.ts#L7)

### TestFakes (interface)

Owned native dependency sources and authoritative writable storage fixtures.

**Signature**

```ts
export interface TestFakes {
  readonly stateRoot: string;
  readonly clients: DependencyClientSources;
  readonly buckets: Readonly<Record<string, TestBucketFake>>;
  readonly cache: Readonly<Record<string, TestCacheFake<unknown, unknown>>>;
  readonly providers: TestProviderReplacements;
  readonly createBucket: (
    id: string,
    options?: Omit<TestBucketFakeOptions, "bucketId" | "stateRoot" | "failures" | "clock">,
  ) => TestBucketFake;
  readonly createCache: (
    id: string,
    options?: Omit<TestCacheFakeOptions, "cacheId" | "stateRoot" | "failures" | "clock">,
  ) => TestCacheFake<unknown, unknown>;
  readonly setClient: (category: DependencyCategory, name: string, client: unknown) => void;
  readonly removeClient: (category: DependencyCategory, name: string) => void;
  readonly failures: TestFailureControls;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.types.ts#L22)

### TestFakesOptions (interface)

Explicit clock, logger and provider replacement policy for one fake owner.

**Signature**

```ts
export interface TestFakesOptions {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly clock?: () => number;
  readonly providers?: TestProviderReplacements;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/fakes.types.ts#L15)

## `http-listener.ts`

### RealListenerPurpose

**Signature**

```ts
declare const RealListenerPurpose: RealListenerPurpose;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.ts#L7)

### TestHttpListener

**Signature**

```ts
declare const TestHttpListener: TestHttpListener;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.ts#L9)

### TestHttpListenerOptions

**Signature**

```ts
declare const TestHttpListenerOptions: TestHttpListenerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.ts#L8)

### createBunHttpListener

**Signature**

```ts
declare const createBunHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.ts#L44)

### createTestHttpListener

Starts the real-socket path reserved for disconnect, streaming, and proxy tests.

**Signature**

```ts
declare const createTestHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.ts#L19)

## `http-listener.types.ts`

### RealListenerPurpose (type alias)

Native behavior requiring a real Bun listener in compatibility acceptance.

**Signature**

```ts
type RealListenerPurpose = "disconnect" | "stream" | "proxy";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.types.ts#L4)

### TestHttpListener (interface)

Owned real Bun server handle and native request/release boundary.

**Signature**

```ts
export interface TestHttpListener {
  readonly purpose: RealListenerPurpose;
  readonly url: URL;
  readonly server: Bun.Server<undefined>;
  readonly request: TestHttpRequest;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.types.ts#L16)

### TestHttpListenerOptions (interface)

Explicit native socket identity, timeout and disconnect test policy.

**Signature**

```ts
export interface TestHttpListenerOptions {
  readonly purpose?: RealListenerPurpose;
  readonly hostname?: string;
  readonly port?: number;
  readonly idleTimeout?: number;
  readonly closeTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-listener.types.ts#L7)

## `http-owner.ts`

### TestHttpOwner (class)

Listener admission, startup races and complete shutdown belong to one client owner.

**Signature**

```ts
declare class TestHttpOwner
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.ts#L20)

### TestHttpPlatform (class)

Native listener acquisition; tests substitute failures without opening real sockets.

**Signature**

```ts
declare class TestHttpPlatform
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.ts#L10)

### TestHttpPlatformLive

**Signature**

```ts
declare const TestHttpPlatformLive: Layer.Layer<TestHttpPlatform, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.ts#L14)

### httpOwnerLayer

Owns listener admission, late startup adoption and complete release as Effect decisions.

**Signature**

```ts
declare const httpOwnerLayer: (
  app: TestHttpApplication,
  options: TestHttpClientOptions,
) => Layer.Layer<TestHttpOwner, never, TestHttpPlatform>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.ts#L31)

## `http-owner.types.ts`

### HttpOwnerService (interface)

Effect listener admission and complete shutdown over native listener handles.

**Signature**

```ts
export interface HttpOwnerService {
  readonly listen: (options?: TestHttpListenerOptions) => Effect.Effect<TestHttpListener, unknown>;
  readonly close: Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.types.ts#L14)

### HttpOwnerState (interface)

Listener handles and real startup completion retained by one scoped HTTP owner.

**Signature**

```ts
export interface HttpOwnerState {
  closed: boolean;
  readonly listeners: Set<TestHttpListener>;
  readonly pending: Set<Promise<unknown>>;
  readonly startupReleaseFailures: unknown[];
  closing: Promise<void> | undefined;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.types.ts#L20)

### HttpPlatformService (interface)

Replaceable native listener acquisition authority for one HTTP owner.

**Signature**

```ts
export interface HttpPlatformService {
  readonly listen: typeof createTestHttpListener;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http-owner.types.ts#L9)

## `http.ts`

### RealListenerPurpose

**Signature**

```ts
declare const RealListenerPurpose: RealListenerPurpose;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L94)

### TestHttpApplication

**Signature**

```ts
declare const TestHttpApplication: TestHttpApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L16)

### TestHttpClient

**Signature**

```ts
declare const TestHttpClient: TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L18)

### TestHttpClientOptions

**Signature**

```ts
declare const TestHttpClientOptions: TestHttpClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L17)

### TestHttpInput

**Signature**

```ts
declare const TestHttpInput: TestHttpInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L14)

### TestHttpListener

**Signature**

```ts
declare const TestHttpListener: TestHttpListener;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L95)

### TestHttpListenerOptions

**Signature**

```ts
declare const TestHttpListenerOptions: TestHttpListenerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L96)

### TestHttpRequest

**Signature**

```ts
declare const TestHttpRequest: TestHttpRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L15)

### TestObservability

**Signature**

```ts
declare const TestObservability: TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L19)

### assertObservabilityHookTypes

Asserts event order and the existing observability protocol/version.

**Signature**

```ts
declare const assertObservabilityHookTypes: (
  hooks: Pick<InspectableObservabilityHooks, "read">,
  expected: readonly ObservabilityHookEvent["type"][],
) => readonly ObservabilityHookEvent[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L162)

### assertResponseStatus

Asserts the existing native HTTP response status.

**Signature**

```ts
declare const assertResponseStatus: (response: Response, expected: number) => Response;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L105)

### createBunHttpListener

**Signature**

```ts
declare const createBunHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L92)

### createHttpTestClient

**Signature**

```ts
declare const createHttpTestClient: (
  app: TestHttpApplication,
  options?: TestHttpClientOptions,
) => TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L90)

### createObservabilityAssertions

**Signature**

```ts
declare const createObservabilityAssertions: () => TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L154)

### createTestHttpClient

Sends ordinary route tests through the app's in-memory request entry point.

**Signature**

```ts
declare const createTestHttpClient: (
  app: TestHttpApplication,
  options?: TestHttpClientOptions,
) => TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L41)

### createTestHttpListener

**Signature**

```ts
declare const createTestHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L91)

### createTestObservability

Creates a protocol/version-checked capture for engine-backed HTTP tests.

**Signature**

```ts
declare const createTestObservability: () => TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L141)

### responseJson

Reads JSON after the optional native status assertion.

**Signature**

```ts
declare const responseJson: <T = unknown>(
  response: Response,
  expectedStatus?: number,
) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L118)

### responseText

Reads text after the optional native status assertion.

**Signature**

```ts
declare const responseText: (response: Response, expectedStatus?: number) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.ts#L132)

## `http.types.ts`

### TestHttpApplication (interface)

The app request/fetch methods satisfy this boundary without leaking framework types.

**Signature**

```ts
export interface TestHttpApplication {
  readonly request?: (input: TestHttpInput, init?: RequestInit) => Response | Promise<Response>;
  readonly fetch?: (request: Request) => Response | Promise<Response>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L12)

### TestHttpClient (interface)

Owned HTTP test facade exposing direct requests and optional real listeners.

**Signature**

```ts
export interface TestHttpClient {
  readonly request: TestHttpRequest;
  readonly get: TestHttpRequest;
  readonly post: TestHttpRequest;
  readonly put: TestHttpRequest;
  readonly patch: TestHttpRequest;
  readonly delete: TestHttpRequest;
  readonly listen: (options?: TestHttpListenerOptions) => Promise<TestHttpListener>;
  readonly close: () => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L28)

### TestHttpClientOptions (interface)

Explicit test origin, listener close policy and ownership callbacks.

**Signature**

```ts
export interface TestHttpClientOptions {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly baseUrl?: string | URL;
  /** Registers client shutdown with the owning test runtime/application. */
  readonly registerClose?: (close: () => Promise<void>) => void;
  readonly onClose?: () => MaybePromise<void>;
  readonly closeTimeoutMs?: number;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L18)

### TestHttpInput (type alias)

Native Request, URL or relative path accepted by direct HTTP fixtures.

**Signature**

```ts
type TestHttpInput = Request | string | URL;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L6)

### TestHttpRequest (type alias)

Native in-memory request operation preserving RequestInit and Response contracts.

**Signature**

```ts
type TestHttpRequest = (input: TestHttpInput, init?: RequestInit) => Promise<Response>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L9)

### TestObservability (interface)

Native engine event capture with ordered protocol/version assertions.

**Signature**

```ts
export interface TestObservability {
  readonly hooks: InspectableObservabilityHooks;
  readonly read: () => readonly ObservabilityHookEvent[];
  readonly types: () => readonly ObservabilityHookEvent["type"][];
  readonly assertTypes: (
    expected: readonly ObservabilityHookEvent["type"][],
  ) => readonly ObservabilityHookEvent[];
  readonly clear: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/http.types.ts#L40)

## `identity.ts`

### TestIdentity (class)

Native trace/span/invocation identity sequence belongs to one deterministic owner.

**Signature**

```ts
declare class TestIdentity
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/identity.ts#L7)

### createTestIdentitySource

Exposes native synchronous identity generation over the same service contract.

**Signature**

```ts
declare const createTestIdentitySource: () => InvocationIdSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/identity.ts#L47)

### identityLayer

Builds the identity service once per provisioned owner.

**Signature**

```ts
declare const identityLayer: () => Layer.Layer<TestIdentity, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/identity.ts#L39)

## `identity.types.ts`

### TestIdentityService (interface)

Deterministic identity allocation authority shared by one test owner.

**Signature**

```ts
export interface TestIdentityService {
  readonly next: (kind: Parameters<InvocationIdSource["next"]>[0]) => Effect.Effect<ProtocolId>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/identity.types.ts#L6)

## `index.ts`

Exposes generic application test owners and fakes; native helpers have feature entrypoints.

### FunctionContextOf

**Signature**

```ts
declare const FunctionContextOf: FunctionContextOf<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L4)

### FunctionInput

**Signature**

```ts
declare const FunctionInput: FunctionInput<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L5)

### FunctionOutput

**Signature**

```ts
declare const FunctionOutput: FunctionOutput<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L6)

### InvokeFunctionOptions

**Signature**

```ts
declare const InvokeFunctionOptions: InvokeFunctionOptions<Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L7)

### JOBS_CONFORMANCE_FIXTURES

**Signature**

```ts
declare const JOBS_CONFORMANCE_FIXTURES: ReadonlyArray<JobsConformanceFixture>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L57)

### JobsConformanceFixture

**Signature**

```ts
declare const JobsConformanceFixture: JobsConformanceFixture;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L59)

### JobsConformanceHarness

**Signature**

```ts
declare const JobsConformanceHarness: JobsConformanceHarness;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L59)

### RealListenerPurpose

**Signature**

```ts
declare const RealListenerPurpose: RealListenerPurpose;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L40)

### StandaloneFunctionTarget

**Signature**

```ts
declare const StandaloneFunctionTarget: StandaloneFunctionTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L8)

### TestApplication

**Signature**

```ts
declare const TestApplication: TestApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L18)

### TestApplicationOptions

**Signature**

```ts
declare const TestApplicationOptions: TestApplicationOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L18)

### TestBucketFake

**Signature**

```ts
declare const TestBucketFake: TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L24)

### TestBucketFakeOptions

**Signature**

```ts
declare const TestBucketFakeOptions: TestBucketFakeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L24)

### TestBucketObject

**Signature**

```ts
declare const TestBucketObject: TestBucketObject;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L24)

### TestCacheFake

**Signature**

```ts
declare const TestCacheFake: TestCacheFake<Key, Value>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L26)

### TestCacheFakeOptions

**Signature**

```ts
declare const TestCacheFakeOptions: TestCacheFakeOptions<KeySchema, ValueSchema>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L26)

### TestCacheSnapshot

**Signature**

```ts
declare const TestCacheSnapshot: TestCacheSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L26)

### TestClock

**Signature**

```ts
declare const TestClock: TestClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L12)

### TestEventCloseOptions

**Signature**

```ts
declare const TestEventCloseOptions: TestEventCloseOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L62)

### TestEventDeliveryAttempt

**Signature**

```ts
declare const TestEventDeliveryAttempt: TestEventDeliveryAttempt;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L63)

### TestEventFake

**Signature**

```ts
declare const TestEventFake: TestEventFake<Payload, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L64)

### TestEventOptions

**Signature**

```ts
declare const TestEventOptions: TestEventOptions<Payload, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L65)

### TestEventPublishResult

**Signature**

```ts
declare const TestEventPublishResult: TestEventPublishResult;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L66)

### TestEventTriggerOptions

**Signature**

```ts
declare const TestEventTriggerOptions: TestEventTriggerOptions<Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L67)

### TestFailureControls

**Signature**

```ts
declare const TestFailureControls: TestFailureControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L20)

### TestFakes

**Signature**

```ts
declare const TestFakes: TestFakes;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L20)

### TestFakesOptions

**Signature**

```ts
declare const TestFakesOptions: TestFakesOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L20)

### TestHttpApplication

**Signature**

```ts
declare const TestHttpApplication: TestHttpApplication;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L41)

### TestHttpClient

**Signature**

```ts
declare const TestHttpClient: TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L42)

### TestHttpClientOptions

**Signature**

```ts
declare const TestHttpClientOptions: TestHttpClientOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L43)

### TestHttpInput

**Signature**

```ts
declare const TestHttpInput: TestHttpInput;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L44)

### TestHttpListener

**Signature**

```ts
declare const TestHttpListener: TestHttpListener;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L45)

### TestHttpListenerOptions

**Signature**

```ts
declare const TestHttpListenerOptions: TestHttpListenerOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L46)

### TestHttpRequest

**Signature**

```ts
declare const TestHttpRequest: TestHttpRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L47)

### TestJobCloseOptions

**Signature**

```ts
declare const TestJobCloseOptions: TestJobCloseOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L51)

### TestJobFake

**Signature**

```ts
declare const TestJobFake: TestJobFake<Input, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L51)

### TestJobOptions

**Signature**

```ts
declare const TestJobOptions: TestJobOptions<Input, Output>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L51)

### TestJobsAdapter

**Signature**

```ts
declare const TestJobsAdapter: TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L53)

### TestJobsAdapterOptions

**Signature**

```ts
declare const TestJobsAdapterOptions: TestJobsAdapterOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L53)

### TestObservability

**Signature**

```ts
declare const TestObservability: TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L48)

### TestProviderReplacements

**Signature**

```ts
declare const TestProviderReplacements: Readonly<
  Partial<
    Record<
      "bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
      Readonly<Record<string, unknown>>
    >
  >
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L21)

### TestRuntime

**Signature**

```ts
declare const TestRuntime: TestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L13)

### TestRuntimeCloseOptions

**Signature**

```ts
declare const TestRuntimeCloseOptions: TestRuntimeCloseOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L14)

### TestRuntimeOptions

**Signature**

```ts
declare const TestRuntimeOptions: TestRuntimeOptions<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L15)

### assertObservabilityHookTypes

**Signature**

```ts
declare const assertObservabilityHookTypes: (
  hooks: Pick<InspectableObservabilityHooks, "read">,
  expected: readonly ObservabilityHookEvent["type"][],
) => readonly ObservabilityHookEvent[];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L28)

### assertResponseStatus

**Signature**

```ts
declare const assertResponseStatus: (response: Response, expected: number) => Response;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L29)

### createBunHttpListener

**Signature**

```ts
declare const createBunHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L30)

### createDeterministicJobsAdapter

**Signature**

```ts
declare const createDeterministicJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L52)

### createHttpTestClient

**Signature**

```ts
declare const createHttpTestClient: (
  app: TestHttpApplication,
  options?: TestHttpClientOptions,
) => TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L31)

### createJobsConformanceHarness

**Signature**

```ts
declare const createJobsConformanceHarness: (
  options?: TestJobsAdapterOptions,
) => JobsConformanceHarness;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L55)

### createObservabilityAssertions

**Signature**

```ts
declare const createObservabilityAssertions: () => TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L32)

### createTestAgentStateProvider

**Signature**

```ts
declare const createTestAgentStateProvider: (root: string) => AgentStateProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L22)

### createTestApplication

**Signature**

```ts
declare const createTestApplication: (
  app: { readonly env: object },
  options?: TestApplicationOptions,
) => Promise<TestApplication>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L17)

### createTestBucket

**Signature**

```ts
declare const createTestBucket: (options?: TestBucketFakeOptions) => TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L23)

### createTestBucketFake

**Signature**

```ts
declare const createTestBucketFake: (options?: TestBucketFakeOptions) => TestBucketFake;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L23)

### createTestCache

**Signature**

```ts
declare const createTestCache: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L25)

### createTestCacheFake

**Signature**

```ts
declare const createTestCacheFake: <
  const KeySchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
  const ValueSchema extends StandardSchemaV1 = StandardSchemaV1<unknown, unknown>,
>(
  options?: TestCacheFakeOptions<KeySchema, ValueSchema>,
) => TestCacheFake<InferInput<KeySchema>, InferOutput<ValueSchema>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L25)

### createTestEvent

**Signature**

```ts
declare const createTestEvent: <Payload = unknown, Output = unknown>(
  options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L60)

### createTestEventFake

**Signature**

```ts
declare const createTestEventFake: <Payload = unknown, Output = unknown>(
  options: TestEventOptions<Payload, Output>,
) => Promise<TestEventFake<Payload, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L60)

### createTestFakes

**Signature**

```ts
declare const createTestFakes: (stateRoot: string, options?: TestFakesOptions) => TestFakes;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L19)

### createTestHttpClient

**Signature**

```ts
declare const createTestHttpClient: (
  app: TestHttpApplication,
  options?: TestHttpClientOptions,
) => TestHttpClient;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L33)

### createTestHttpListener

**Signature**

```ts
declare const createTestHttpListener: (
  app: TestHttpApplication,
  options?: TestHttpListenerOptions,
) => Promise<TestHttpListener>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L34)

### createTestJob

**Signature**

```ts
declare const createTestJob: <Input = JsonValue, Output = unknown>(
  options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L50)

### createTestJobFake

**Signature**

```ts
declare const createTestJobFake: <Input = JsonValue, Output = unknown>(
  options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L50)

### createTestJobsAdapter

**Signature**

```ts
declare const createTestJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L52)

### createTestObservability

**Signature**

```ts
declare const createTestObservability: () => TestObservability;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L35)

### createTestRealtimeProvider

**Signature**

```ts
declare const createTestRealtimeProvider: (root: string) => RealtimeProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L22)

### createTestRuntime

**Signature**

```ts
declare const createTestRuntime: <S extends EnvShape = EnvShape>(
  options?: TestRuntimeOptions<S>,
) => TestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L10)

### invokeFunction

**Signature**

```ts
declare const invokeFunction: <
  const Target extends StandaloneFunctionTarget,
  Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
  target: Target,
  input: FunctionInput<Target>,
  options?: InvokeFunctionOptions<Context>,
) => Promise<FunctionOutput<Target>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L2)

### responseJson

**Signature**

```ts
declare const responseJson: <T = unknown>(
  response: Response,
  expectedStatus?: number,
) => Promise<T>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L36)

### responseText

**Signature**

```ts
declare const responseText: (response: Response, expectedStatus?: number) => Promise<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L37)

### runJobsConformance

**Signature**

```ts
declare const runJobsConformance: (
  adapter: JobsAdapterRuntime,
  fixtureIds?: readonly string[],
) => Promise<readonly string[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/index.ts#L56)

## `invoke-function.ts`

### invokeFunction

Invokes a function descriptor through the engine's direct, transport-free path.

**Example**

```ts
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import { invokeFunction } from "@relkit/testing";

export async function greetingExample(): Promise<string> {
  const greet = defineFunction({
    id: "greet",
    input: z.string(),
    output: z.string(),
    handler: async (name) => `Hello ${name}`,
  });
  return invokeFunction(greet, "Ada");
}
```

**Signature**

```ts
declare const invokeFunction: <
  const Target extends StandaloneFunctionTarget,
  Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
  target: Target,
  input: FunctionInput<Target>,
  options?: InvokeFunctionOptions<Context>,
) => Promise<FunctionOutput<Target>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L52)

Since v0.1.0

### FunctionContextOf

**Signature**

```ts
declare const FunctionContextOf: FunctionContextOf<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L12)

### FunctionInput

**Signature**

```ts
declare const FunctionInput: FunctionInput<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L10)

### FunctionOutput

**Signature**

```ts
declare const FunctionOutput: FunctionOutput<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L11)

### InvokeFunctionOptions

**Signature**

```ts
declare const InvokeFunctionOptions: InvokeFunctionOptions<Context>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L13)

### StandaloneFunctionTarget

**Signature**

```ts
declare const StandaloneFunctionTarget: StandaloneFunctionTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L9)

### invokeFunctionWithRunner

Invokes the existing engine validation path with an explicit Effect runner.

**Signature**

```ts
declare const invokeFunctionWithRunner: <
  const Target extends StandaloneFunctionTarget,
  Context extends { readonly signal: AbortSignal } = FunctionContextOf<Target>,
>(
  target: Target,
  input: FunctionInput<Target>,
  options: InvokeFunctionOptions<Context> | undefined,
  runner?: InvocationRunner,
) => Promise<FunctionOutput<Target>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.ts#L107)

## `invoke-function.types.ts`

### FunctionContextOf (type alias)

Context inferred from the native handler, preserving required cancellation.

**Signature**

```ts
type FunctionContextOf<Target> =
  Target extends Record<"handler", (input: infer _Input, context: infer Context) => unknown>
    ? Context extends { readonly signal: AbortSignal }
      ? Context
      : InvocationContext
    : InvocationContext;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.types.ts#L45)

### FunctionInput (type alias)

Input inferred from the target's native schema authority.

**Signature**

```ts
type FunctionInput<Target extends { readonly input: StandardSchemaV1 }> = InferInput<
  Target["input"]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.types.ts#L29)

### FunctionOutput (type alias)

Output inferred from the target's native schema authority.

**Signature**

```ts
type FunctionOutput<Target extends { readonly output: StandardSchemaV1 }> = InferOutput<
  Target["output"]
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.types.ts#L37)

### InvokeFunctionOptions (interface)

Direct invocation dependencies and native hooks without process environment reads.

**Signature**

```ts
export interface InvokeFunctionOptions<Context extends { readonly signal: AbortSignal }> {
  readonly registry?: FunctionRegistry;
  readonly env?: Readonly<Record<string, unknown>>;
  readonly clients?: DependencyClientSources;
  readonly signal?: AbortSignal;
  readonly now?: () => number;
  readonly idSource?: InvocationIdSource;
  readonly context?: InvocationHooks<Context>["context"];
  readonly hooks?: InvocationHooks<Context>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.types.ts#L56)

### StandaloneFunctionTarget (interface)

Native function descriptor retaining input, output and dependency validation.

**Signature**

```ts
export interface StandaloneFunctionTarget {
  readonly id: string;
  readonly input: StandardSchemaV1;
  readonly output: StandardSchemaV1;
  readonly errors?: readonly { readonly id: string; readonly data: StandardSchemaV1 }[];
  readonly dependencies?: import("@relkit/engine").DependencyDeclarations;
  readonly publishes?: readonly string[];
  readonly publications?: Readonly<Record<string, import("@relkit/engine").DependencyRefLike>>;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly handler: (...arguments_: readonly never[]) => MaybePromise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/invoke-function.types.ts#L12)

## `job-harness.types.ts`

### JobHarnessService (interface)

Native inspection and Effect workflows over one durable job generation.

**Signature**

```ts
export interface JobHarnessService {
  readonly value: TestJobFake<never, unknown>;
  readonly runNext: (
    id?: string,
  ) => Effect.Effect<Awaited<ReturnType<TestJobFake["runNext"]>>, unknown>;
  readonly drain: Effect.Effect<Awaited<ReturnType<TestJobFake["drain"]>>, unknown>;
  readonly restart: Effect.Effect<void, unknown>;
  readonly close: (options?: TestJobCloseOptions) => Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-harness.types.ts#L5)

## `job-runtime-controls.ts`

### enqueueJob

Persists one submission before making a new durable instance available.

**Signature**

```ts
declare const enqueueJob: (
  queue: JobQueue,
  input: JobQueueEnqueue,
  signal: AbortSignal,
) => Effect.Effect<JobQueueAcceptance, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime-controls.ts#L13)

### jobWorkerControls

Composes native worker selection and retry promotion against the current generation.

**Signature**

```ts
declare const jobWorkerControls: (state: JobWorkerState) => {
  runNext: (
    instanceId?: string | undefined,
  ) => Effect.Effect<JobRunResult | undefined, unknown, never>;
  drain: Effect.Effect<ReadonlyArray<JobRunResult>, unknown, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime-controls.ts#L67)

### promoteDueJobs

Promotes due entries in native snapshot order before worker admission.

**Signature**

```ts
declare const promoteDueJobs: (
  queue: JobQueue,
  currentTimeMs: () => number,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime-controls.ts#L37)

## `job-runtime.ts`

### createTestJobRuntime

Acquires and composes the durable job owner's actual workflows.

**Signature**

```ts
declare const createTestJobRuntime: <Input = JsonValue, Output = unknown>(
  options: TestJobOptions<Input, Output>,
) => Effect.Effect<
  {
    value: JobHarnessService["value"];
    runNext: (instanceId?: string) => Effect.Effect<JobRunResult | undefined, unknown, never>;
    drain: Effect.Effect<ReadonlyArray<JobRunResult>, unknown, never>;
    restart: Effect.Effect<void, unknown, never>;
    close: (closeOptions: TestJobCloseOptions | undefined) => Effect.Effect<void, unknown, never>;
  },
  unknown,
  Scope.Scope
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime.ts#L38)

## `job-runtime.types.ts`

### JobRuntimeState (interface)

Admission, native cancellation and actual completion receipts for one durable job owner.

**Signature**

```ts
export interface JobRuntimeState extends WorkOwnershipState {}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime.types.ts#L6)

### JobWorkerState (interface)

Current-generation native authorities read lazily by ordered worker workflows.

**Signature**

```ts
export interface JobWorkerState {
  readonly queue: () => JobQueue;
  readonly worker: () => Awaited<ReturnType<typeof materializeJobs>>;
  readonly jobId: string;
  readonly now: () => number;
  readonly isClosed: () => boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/job-runtime.types.ts#L9)

## `jobs-conformance.ts`

### JOBS_CONFORMANCE_FIXTURES

**Signature**

```ts
declare const JOBS_CONFORMANCE_FIXTURES: ReadonlyArray<JobsConformanceFixture>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.ts#L10)

### JobsConformanceFixture

**Signature**

```ts
declare const JobsConformanceFixture: JobsConformanceFixture;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.ts#L2)

### JobsConformanceHarness

**Signature**

```ts
declare const JobsConformanceHarness: JobsConformanceHarness;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.ts#L2)

### createJobsConformanceHarness

Creates the deterministic adapter used by native contract fixtures.

**Signature**

```ts
declare const createJobsConformanceHarness: (
  options?: TestJobsAdapterOptions,
) => JobsConformanceHarness;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.ts#L33)

### runJobsConformance

Executes selected existing native adapter contract fixtures sequentially.

**Signature**

```ts
declare const runJobsConformance: (
  adapter: JobsAdapterRuntime,
  fixtureIds?: readonly string[],
) => Promise<readonly string[]>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.ts#L59)

## `jobs-conformance.types.ts`

### JobsConformanceFixture (interface)

Native adapter fixture inputs for reusable jobs contract assertions.

**Signature**

```ts
export interface JobsConformanceFixture {
  readonly id: string;
  readonly description: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.types.ts#L7)

### JobsConformanceHarness (interface)

Owned native jobs conformance operations and completion controls.

**Signature**

```ts
export interface JobsConformanceHarness {
  readonly adapter: TestJobsAdapter;
  readonly context: OperationContext;
  readonly fixtures: typeof JOBS_CONFORMANCE_FIXTURES;
  readonly run: (fixtureId: string) => Promise<RunHandle | undefined>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-conformance.types.ts#L13)

## `jobs-types.ts`

Preserved compatibility entrypoint for the canonical domain type companion.

### "./jobs.types.js" (namespace export)

Re-exports all named exports from the "./jobs.types.js" module.

**Signature**

```ts
export * from "./jobs.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-types.ts#L2)

## `jobs-utils.ts`

### createFailures

Creates isolated named failure injection controls.

**Signature**

```ts
declare const createFailures: () => TestFailureControls;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L170)

### createIdSource

Creates an isolated monotonically sequenced invocation identity source.

**Signature**

```ts
declare const createIdSource: () => InvocationIdSource;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L142)

### createJobInvoker

Binds job invocation to deterministic IDs, time and owner cancellation.

**Signature**

```ts
declare const createJobInvoker: <Input, Output>(
  target: InvocationTarget<Input, Output>,
  failures: TestFailureControls,
  runner: InvocationRunner,
  idSource: InvocationIdSource,
  now: () => number,
  env: Readonly<Record<string, unknown>> | undefined,
  clients: DependencyClientSources | undefined,
  hooks: InvocationHooks | undefined,
  ownerSignal?: () => AbortSignal,
) => (request: JobInvocationOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L86)

### createPlan

Builds the minimal registration plan consumed by native materialization.

**Signature**

```ts
declare const createPlan: <Input, Output>(
  jobId: string,
  target: InvocationTarget<Input, Output>,
  retry: RetryPolicy,
  profile: string,
  options: TestJobOptions<Input, Output>,
) => Parameters<typeof materializeJobs>[0]["plan"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L38)

### createRandom

Creates deterministic retry randomness with upfront fixture validation.

**Signature**

```ts
declare const createRandom: (
  source: (() => number) | undefined,
  values: readonly number[] | undefined,
) => () => number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L152)

### defaultRetry

**Signature**

```ts
declare const defaultRetry: RetryPolicy;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs-utils.ts#L19)

## `jobs.ts`

### TestJobHarness (class)

Durable native job generation owned by one test scope.

**Signature**

```ts
declare class TestJobHarness
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.ts#L10)

### createTestJob

**Signature**

```ts
declare const createTestJob: <Input = JsonValue, Output = unknown>(
  options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.ts#L92)

### createTestJobFake

Creates a durable one-job harness with an owned Effect runtime.

**Signature**

```ts
declare const createTestJobFake: <Input = JsonValue, Output = unknown>(
  options: TestJobOptions<Input, Output>,
) => Promise<TestJobFake<Input, Output>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.ts#L52)

### testJobLayer

Acquires native store/queue/worker resources with deterministic retry inputs.

**Signature**

```ts
declare const testJobLayer: <Input, Output>(
  options: TestJobOptions<Input, Output>,
) => Layer.Layer<TestJobHarness, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.ts#L21)

## `jobs.types.ts`

### TestJobCloseOptions (interface)

Explicit failed-test state retention policy for durable job shutdown.

**Signature**

```ts
export interface TestJobCloseOptions {
  readonly failed?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.types.ts#L46)

### TestJobFake (interface)

Owned durable native job facade with deterministic admission and lifecycle controls.

**Signature**

```ts
export interface TestJobFake<Input = JsonValue, Output = unknown> extends JobClient<Input> {
  readonly id: string;
  readonly client: JobClient<Input>;
  readonly provider: JobProvider;
  readonly stateRoot: string;
  readonly clock: TestClock;
  readonly random: () => number;
  readonly failures: TestFailureControls;
  readonly admin: JobAdmin;
  readonly status: () => JobQueueCounts;
  readonly get: (instanceId: string) => JobQueueEntry | undefined;
  readonly runNext: (instanceId?: string) => Promise<JobRunResult | undefined>;
  readonly drain: () => Promise<readonly JobRunResult[]>;
  readonly restart: () => Promise<void>;
  readonly close: (options?: TestJobCloseOptions) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.types.ts#L55)

### TestJobOptions (interface)

Durable native target, retry bounds and deterministic persistence dependencies.

**Signature**

```ts
export interface TestJobOptions<Input = JsonValue, Output = unknown> {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly jobId?: string;
  readonly target: InvocationTarget<Input, Output>;
  readonly retry?: RetryPolicy;
  readonly profile?: string;
  readonly timeoutMs?: number;
  readonly concurrency?: number;
  readonly consumerConcurrency?: number;
  readonly idempotency?: JobIdempotencyDefinition;
  readonly leaseDurationMs?: number;
  readonly ownerId?: string;
  readonly stateRoot?: string;
  readonly startTimeMs?: number;
  readonly random?: () => number;
  readonly randomValues?: readonly number[];
  readonly failures?: TestFailureControls;
  readonly env?: Readonly<Record<string, unknown>>;
  readonly clients?: DependencyClientSources;
  readonly hooks?: InvocationHooks;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/jobs.types.ts#L23)

## `native-jobs-observe.ts`

### nativeJobObservation

Publishes owner state availability without polling or sharing observer cursors.

**Signature**

```ts
declare const nativeJobObservation: (
  state: Ref.Ref<NativeJobsState>,
  clock: TestClock,
  service: string,
  request: NativeWatchRequest,
  context: OperationContext,
) => Stream.Stream<
  | {
      readonly kind: "snapshot";
      readonly run: RunSnapshot;
      readonly observedAt: string;
      readonly epoch: string;
      readonly sequence: number;
      readonly cursor?: string;
      readonly continuity: "state" | "history";
    }
  | {
      readonly kind: "update";
      readonly run: RunSnapshot;
      readonly observedAt: string;
      readonly epoch: string;
      readonly sequence: number;
      readonly cursor?: string;
    },
  unknown,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs-observe.ts#L19)

## `native-jobs-service.ts`

### TestNativeJobs (class)

Owns authoritative native run state, deterministic time and observation synchronization.

**Signature**

```ts
declare class TestNativeJobs
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs-service.ts#L15)

### nativeJobsLayer

Builds one native jobs service, substitutable by providing TestNativeJobs.of in tests.

**Signature**

```ts
declare const nativeJobsLayer: (
  options?: TestJobsAdapterOptions,
) => Layer.Layer<TestNativeJobs, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs-service.ts#L24)

## `native-jobs-state.ts`

### notifyNativeJobs

Publishes state availability without buffers or wall-clock polling.

**Signature**

```ts
declare const notifyNativeJobs: (value: NativeJobsState) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs-state.ts#L9)

## `native-jobs.types.ts`

### NativeJobsService (interface)

Effect native jobs adapter decisions with owned worker and observation lifetimes.

**Signature**

```ts
export interface NativeJobsService {
  readonly state: Ref.Ref<NativeJobsState>;
  readonly clock: TestClock;
  readonly submit: (
    ...args: Parameters<JobsAdapterRuntime["submit"]>
  ) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["submit"]>>, unknown>;
  readonly get: (
    ...args: Parameters<JobsAdapterRuntime["get"]>
  ) => Effect.Effect<RunSnapshot, unknown>;
  readonly list: (
    ...args: Parameters<JobsAdapterRuntime["list"]>
  ) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["list"]>>, unknown>;
  readonly cancel: (
    ...args: Parameters<JobsAdapterRuntime["cancel"]>
  ) => Effect.Effect<Awaited<ReturnType<JobsAdapterRuntime["cancel"]>>, unknown>;
  readonly retry: (
    ...args: Parameters<NonNullable<JobsAdapterRuntime["retry"]>>
  ) => Effect.Effect<Awaited<ReturnType<NonNullable<JobsAdapterRuntime["retry"]>>>, unknown>;
  readonly worker: {
    readonly next: (
      ...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["next"]>
    ) => Effect.Effect<
      Awaited<ReturnType<NonNullable<JobsAdapterRuntime["worker"]>["next"]>>,
      unknown
    >;
    readonly complete: (
      ...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["complete"]>
    ) => Effect.Effect<void, unknown>;
    readonly fail: (
      ...args: Parameters<NonNullable<JobsAdapterRuntime["worker"]>["fail"]>
    ) => Effect.Effect<void, unknown>;
  };
  readonly observe: (
    ...args: Parameters<NonNullable<JobsAdapterRuntime["observe"]>>
  ) => Stream.Stream<RunWatchFrame<RunSnapshot>, unknown>;
  readonly snapshot: (runId: string) => Effect.Effect<RunSnapshot, unknown>;
  readonly close: Effect.Effect<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs.types.ts#L22)

### NativeJobsState (interface)

Owner-local deterministic run, worker, cursor and observation admission state.

**Signature**

```ts
export interface NativeJobsState {
  readonly runs: Map<string, TestNativeRun>;
  readonly keys: Map<string, string>;
  readonly cancelReceipts: Map<string, Awaited<ReturnType<JobsAdapterRuntime["cancel"]>>>;
  readonly retryReceipts: Map<
    string,
    Awaited<ReturnType<NonNullable<JobsAdapterRuntime["retry"]>>>
  >;
  sequence: number;
  closed: boolean;
  changed: Deferred.Deferred<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/native-jobs.types.ts#L8)

## `provider-replacements.ts`

### TestProviderReplacements

**Signature**

```ts
declare const TestProviderReplacements: Readonly<
  Partial<
    Record<
      "bucket" | "cache" | "job" | "event" | "model" | "realtime" | "agent-state",
      Readonly<Record<string, unknown>>
    >
  >
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/provider-replacements.ts#L2)

### activateTestProviders

Acquires native providers and wires dependency clients with partial-failure release.

**Signature**

```ts
declare const activateTestProviders: (
  artifacts: TestApplicationArtifacts | undefined,
  replacements: TestProviderReplacements,
  bindingValues: Readonly<Record<string, JsonValue>> | undefined,
  fakes: TestFakes,
  fakeResources?: boolean,
) => Promise<ProviderRegistry | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/provider-replacements.ts#L49)

### copyTestProviderReplacements

Copies explicit capability/profile replacements before resource acquisition.

**Signature**

```ts
declare const copyTestProviderReplacements: (
  input: TestProviderReplacements | undefined,
) => TestProviderReplacements;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/provider-replacements.ts#L20)

## `provider-replacements.types.ts`

### TestProviderReplacements (type alias)

Explicit capability/profile replacements; absent profiles remain native authority decisions.

**Signature**

```ts
type TestProviderReplacements = Readonly<
  Partial<Record<ProviderCapability, Readonly<Record<string, unknown>>>>
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/provider-replacements.types.ts#L4)

## `runtime-clock.ts`

### TestDeterministicClock (class)

Manual time and native clock scheduling belong to one deterministic owner.

**Signature**

```ts
declare class TestDeterministicClock
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.ts#L137)

### combineSignals

Combines cancellation sources without retaining their listeners after work.

**Signature**

```ts
declare const combineSignals: (...signals: (AbortSignal | undefined)[]) => CombinedSignals;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.ts#L117)

### createDeterministicClock

Creates a manually controlled native Effect clock without wall-time polling.

**Signature**

```ts
declare const createDeterministicClock: (startTime: number) => DeterministicClockService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.ts#L13)

### deterministicClockLayer

Provides a replaceable clock service from the native manual-time implementation.

**Signature**

```ts
declare const deterministicClockLayer: (
  startTime?: number,
) => Layer.Layer<TestDeterministicClock, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.ts#L147)

## `runtime-clock.types.ts`

### ClockWaiter (interface)

Owned deterministic deadline and its native completion callback.

**Signature**

```ts
export interface ClockWaiter {
  readonly at: number;
  readonly resume: (effect: Effect.Effect<void>) => void;
  done: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.types.ts#L6)

### CombinedSignals (interface)

Native cancellation signal and the explicit lifetime of its source listeners.

**Signature**

```ts
export interface CombinedSignals {
  readonly signal: AbortSignal;
  readonly dispose: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.types.ts#L20)

### DeterministicClockService (interface)

Manually controlled native clock with an Effect invocation runner.

**Signature**

```ts
export interface DeterministicClockService {
  readonly service: Clock.Clock;
  readonly clock: TestClock;
  readonly run: InvocationRunner["run"];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-clock.types.ts#L13)

## `runtime-close.ts`

### closeRuntime

Waits for bounded admitted work before cleaning temporary ownership.

**Signature**

```ts
declare const closeRuntime: (
  pending: Set<Promise<unknown>>,
  timeoutMs: number,
  cleanup: (failed: boolean) => Effect.Effect<void, unknown>,
  failed: () => boolean,
) => Effect.Effect<void, unknown, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-close.ts#L11)

## `runtime-context.ts`

### createTestContextFactory

Creates the validated runtime context defaults with an explicit caller patch.

**Signature**

```ts
declare const createTestContextFactory: (patch: Readonly<Record<string, unknown>>) => ({
  invocation,
  signal,
  env,
  time,
}: InvocationContextOptions) => Readonly<{
  invocation: InvocationRecord;
  signal: AbortSignal;
  env: Readonly<Record<string, unknown>>;
  time: PublicClock;
  log: Readonly<{
    trace: () => void;
    debug: () => void;
    info: () => void;
    warn: () => void;
    error: () => void;
  }>;
  jobs: Readonly<{}>;
  events: Readonly<{}>;
  buckets: Readonly<{}>;
  cache: Readonly<{}>;
  agents: Readonly<{}>;
  database: Readonly<{}>;
  auth: Readonly<{ getSession: () => Promise<null> }>;
  constants: Readonly<{}>;
  prompts: Readonly<{}>;
}>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-context.ts#L12)

## `runtime-execution.ts`

### TestRuntimeExecution (class)

Owns invocation admission, cancellation, deterministic dependencies and shutdown.

**Signature**

```ts
declare class TestRuntimeExecution
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-execution.ts#L30)

### testRuntimeLayer

Allocates a synchronously ready runtime domain service after validating all options.

**Signature**

```ts
declare const testRuntimeLayer: <S extends EnvShape = EnvShape>(
  options?: TestRuntimeOptions<S>,
) => Layer.Layer<TestRuntimeExecution, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-execution.ts#L41)

## `runtime-execution.types.ts`

### RuntimeExecutionService (interface)

Effect invocation admission and shutdown with deterministic native runtime state.

**Signature**

```ts
export interface RuntimeExecutionService {
  readonly value: Omit<TestRuntime, "invoke" | "close">;
  readonly invoke: <Target extends StandaloneFunctionTarget>(
    target: Target,
    input: FunctionInput<Target>,
    options?: Omit<InvokeFunctionOptions<FunctionContextOf<Target>>, "env" | "now" | "idSource">,
  ) => Effect.Effect<FunctionOutput<Target>, unknown>;
  readonly close: (options?: TestRuntimeCloseOptions) => Effect.Effect<void, unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-execution.types.ts#L12)

## `runtime-options.ts`

### resolveRuntimeEnv

Resolves explicit values through the application's existing environment authority.

**Signature**

```ts
declare const resolveRuntimeEnv: <S extends EnvShape>(
  options: TestRuntimeOptions<S>,
) => Readonly<Record<string, unknown>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-options.ts#L10)

### validateRuntimeTimeout

Rejects invalid close deadlines before allocating native resources.

**Signature**

```ts
declare const validateRuntimeTimeout: (value: number) => void;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime-options.ts#L63)

## `runtime.ts`

### TestClock

**Signature**

```ts
declare const TestClock: TestClock;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.ts#L10)

### TestRuntime

**Signature**

```ts
declare const TestRuntime: TestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.ts#L11)

### TestRuntimeCloseOptions

**Signature**

```ts
declare const TestRuntimeCloseOptions: TestRuntimeCloseOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.ts#L9)

### TestRuntimeOptions

**Signature**

```ts
declare const TestRuntimeOptions: TestRuntimeOptions<S>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.ts#L8)

### createTestRuntime

Creates a small deterministic runtime for direct function tests.

**Example**

```ts
import { defineEnv } from "@relkit/app/config";
import { createTestRuntime } from "@relkit/testing";

export async function runtimeExample(): Promise<void> {
  const runtime = createTestRuntime({ app: { env: defineEnv({}) } });
  try {
    await runtime.clock.advance(10);
  } finally {
    await runtime.close();
  }
}
```

**See**

- tests/fixtures/checked-examples.ts ownedHelpersExample for checked inference and release.

**Signature**

```ts
declare const createTestRuntime: <S extends EnvShape = EnvShape>(
  options?: TestRuntimeOptions<S>,
) => TestRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.ts#L41)

## `runtime.types.ts`

### TestClock (interface)

Deterministic native time facade advanced only by explicit test commands.

**Signature**

```ts
export interface TestClock {
  readonly now: () => Date;
  readonly currentTimeMs: () => number;
  readonly advance: (milliseconds: number) => Promise<void>;
  readonly setTime: (timestamp: number) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.types.ts#L37)

### TestRuntime (interface)

Owned direct invocation runtime with native dependency fakes and complete shutdown.

**Signature**

```ts
export interface TestRuntime {
  readonly stateRoot: string;
  readonly fakes: TestFakes;
  readonly providers: TestProviderReplacements;
  readonly env: Readonly<Record<string, unknown>>;
  readonly clock: TestClock;
  readonly invoke: <Target extends StandaloneFunctionTarget>(
    target: Target,
    input: FunctionInput<Target>,
    options?: Omit<InvokeFunctionOptions<FunctionContextOf<Target>>, "env" | "now" | "idSource">,
  ) => Promise<FunctionOutput<Target>>;
  readonly close: (options?: TestRuntimeCloseOptions) => Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.types.ts#L45)

### TestRuntimeCloseOptions (interface)

Explicit failed-test state retention policy for runtime shutdown.

**Signature**

```ts
export interface TestRuntimeCloseOptions {
  readonly failed?: boolean;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.types.ts#L32)

### TestRuntimeOptions (interface)

Runtime options retaining the concrete application's environment shape.

**Signature**

```ts
export interface TestRuntimeOptions<S extends EnvShape = EnvShape> {
  readonly registry?: FunctionRegistry;
  readonly logger?: LoggerOptions;
  readonly app?: { readonly env: EnvDefinition<S> };
  readonly environment?: string;
  readonly env?: Readonly<Record<string, unknown>>;
  readonly startTimeMs?: number;
  readonly closeTimeoutMs?: number;
  readonly context?: Readonly<Record<string, unknown>>;
  readonly providers?: TestProviderReplacements;
  /** Caller-owned roots enable explicit restart tests; omitted roots are temporary. */
  readonly stateRoot?: string;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/runtime.types.ts#L17)

## `state-providers.ts`

Supplies local realtime and agent-state providers without selecting a native agent engine.

### createTestAgentStateProvider

Constructs the native local agent state provider at an explicit test root.

**Signature**

```ts
declare const createTestAgentStateProvider: (root: string) => AgentStateProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/state-providers.ts#L23)

### createTestRealtimeProvider

Constructs the native local realtime provider at an explicit test root.

**Signature**

```ts
declare const createTestRealtimeProvider: (root: string) => RealtimeProvider;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/state-providers.ts#L14)

## `state-root.ts`

### TestStateRoot

**Signature**

```ts
declare const TestStateRoot: TestStateRoot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/state-root.ts#L2)

### createTestStateRoot

Creates an owned temporary state root, or opens a caller-owned restart root.

**Signature**

```ts
declare const createTestStateRoot: (requestedPath?: string) => TestStateRoot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/state-root.ts#L12)

## `state-root.types.ts`

Native temporary or caller-owned persistence path with idempotent cleanup.

### TestStateRoot (interface)

Native temporary or caller-owned persistence path with idempotent cleanup.

**Signature**

```ts
export interface TestStateRoot {
  readonly path: string;
  readonly cleanup: (failed: boolean) => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/state-root.types.ts#L2)

## `storage-failure.ts`

### InvalidTestSnapshot (class)

Typed invalid transfer boundary translated to the existing public TypeError family.

**Signature**

```ts
declare class InvalidTestSnapshot
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/storage-failure.ts#L4)

## `test-jobs-adapter-controls.ts`

### cancel

Applies the first native cancellation transition and acknowledgement receipt.

**Signature**

```ts
declare const cancel: (
  runs: Map<string, TestNativeRun>,
  receipts: Map<string, NativeControlReceipt>,
  request: NativeCancelRequest,
  unknownOutcome: boolean,
  service: string,
  clock: TestClock,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-controls.ts#L25)

### retry

Creates a deduplicated native retry with a fresh canonical run identity.

**Signature**

```ts
declare const retry: (
  runs: Map<string, TestNativeRun>,
  receipts: Map<string, NativeControlReceipt>,
  request: NativeRetryRequest,
  unknownOutcome: boolean,
  service: string,
  clock: TestClock,
) => Promise<NativeControlReceipt>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-controls.ts#L72)

### unknown

Builds an explicit ambiguous native write result.

**Signature**

```ts
declare const unknown: (
  code: JobUnknownOutcome["code"],
  operationId: string,
  idempotencyKey?: string,
) => JobUnknownOutcome;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-controls.ts#L125)

## `test-jobs-adapter-support.ts`

### TestNativeRun

**Signature**

```ts
declare const TestNativeRun: TestNativeRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L2)

### detachedNativeSnapshot

Reads a detached native snapshot, including retained state after owner close.

**Signature**

```ts
declare const detachedNativeSnapshot: (
  state: NativeJobsState,
  runId: string,
  service: string,
  clock: TestClock,
) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L17)

### failureOf

Projects an unknown worker failure into the existing public envelope.

**Signature**

```ts
declare const failureOf: (value: unknown) => JobErrorEnvelope;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L93)

### isTerminal

Classifies native job terminal lifecycle states.

**Signature**

```ts
declare const isTerminal: (status: RunSnapshot["status"]) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L33)

### requestKey

Builds the existing canonical submission deduplication identity.

**Signature**

```ts
declare const requestKey: (request: NativeSubmission) => string | undefined;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L117)

### snapshotOf

Projects a native run using the injected observation clock.

**Signature**

```ts
declare const snapshotOf: (run: TestNativeRun, service: string, clock: TestClock) => RunSnapshot;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.ts#L49)

## `test-jobs-adapter-support.types.ts`

### TestNativeRun (interface)

Mutable deterministic native run state with owned worker cancellation.

**Signature**

```ts
export interface TestNativeRun {
  readonly request: NativeSubmission;
  readonly runId: string;
  readonly acceptedAt: string;
  status: RunSnapshot["status"];
  attempt: number;
  startedAt?: string;
  completedAt?: string;
  output?: unknown;
  error?: JobErrorEnvelope;
  retryOfRunId?: string;
  readonly canonicalInput: JobWireEnvelope;
  controller?: AbortController;
  disposeSignal?: () => void;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-support.types.ts#L5)

## `test-jobs-adapter-work.ts`

### complete

Commits a nonterminal worker's successful native outcome.

**Signature**

```ts
declare const complete: (
  run: TestNativeRun | undefined,
  output: unknown,
  clock: TestClock,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L163)

### createRun

Creates one queued native run using an injected acceptance clock.

**Signature**

```ts
declare const createRun: (
  request: NativeSubmission,
  runId: string,
  retryOfRunId: string | undefined,
  clock: TestClock,
) => TestNativeRun;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L27)

### fail

Commits a nonterminal worker's bounded native failure envelope.

**Signature**

```ts
declare const fail: (
  run: TestNativeRun | undefined,
  error: unknown,
  clock: TestClock,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L181)

### handle

Projects the accepted native run identity.

**Signature**

```ts
declare const handle: (run: TestNativeRun) => RunHandle;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L49)

### list

Filters native runs and returns detached deterministic snapshots.

**Signature**

```ts
declare const list: (
  runs: Map<string, TestNativeRun>,
  query: NativeRunQuery,
  service: string,
  clock: TestClock,
) => RunPage<RunSnapshot>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L68)

### next

Admits one queued native task and binds native cancellation.

**Signature**

```ts
declare const next: (
  runs: Map<string, TestNativeRun>,
  context: OperationContext,
  service: string,
  clock: TestClock,
) => Promise<NativeTaskWork | undefined>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter-work.ts#L94)

## `test-jobs-adapter.ts`

### TestJobsAdapter

**Signature**

```ts
declare const TestJobsAdapter: TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.ts#L2)

### TestJobsAdapterOptions

**Signature**

```ts
declare const TestJobsAdapterOptions: TestJobsAdapterOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.ts#L2)

### createDeterministicJobsAdapter

Creates a synchronous compatibility adapter over one deterministic jobs owner.

**Signature**

```ts
declare const createDeterministicJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.ts#L21)

### createTestJobsAdapter

**Signature**

```ts
declare const createTestJobsAdapter: (options?: TestJobsAdapterOptions) => TestJobsAdapter;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.ts#L111)

## `test-jobs-adapter.types.ts`

### TestJobsAdapter (interface)

Owned native jobs adapter with deterministic worker and snapshot test controls.

**Signature**

```ts
export interface TestJobsAdapter extends JobsAdapterRuntime {
  readonly clock: TestClock;
  readonly runNext: () => Promise<import("@relkit/jobs/adapter").NativeTaskWork | undefined>;
  readonly snapshot: (runId: string) => RunSnapshot;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.types.ts#L15)

### TestJobsAdapterOptions (interface)

Deterministic native adapter time, failure injection and unknown-outcome policy.

**Signature**

```ts
export interface TestJobsAdapterOptions {
  readonly logger?: import("@relkit/runtime-effect").LoggerOptions;
  readonly clock?: TestClock;
  readonly startTimeMs?: number;
  readonly service?: string;
  readonly unknown?: Partial<Record<"submit" | "cancel" | "retry", boolean>>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/test-jobs-adapter.types.ts#L6)

## `testing-owner.ts`

### disposeTestingOwner

Releases an existing owner while retaining native failure identity.

**See**

- tests/fixtures/checked-examples.ts deterministicServicesExample for checked ownership.

**Signature**

```ts
declare const disposeTestingOwner: <R, E>(
  owner: ManagedRuntime.ManagedRuntime<R, E>,
) => Promise<void>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/testing-owner.ts#L22)

### runRetainedTestingQuery

Reads retained, resource-free state using the owner's captured observation context.

**Signature**

```ts
declare const runRetainedTestingQuery: <A>(
  context: Context.Context<never>,
  query: Effect.Effect<A, unknown>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/testing-owner.ts#L36)

### testingLoggerLayer

Provisions redacting server logging once at a test helper's ownership boundary.

**See**

- tests/fixtures/checked-examples.ts deterministicServicesExample for checked provisioning.

**Signature**

```ts
declare const testingLoggerLayer: (options?: LoggerOptions) => Layer.Layer<never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/testing-owner.ts#L10)

## `work-ownership.ts`

### admitOwnedWork

Registers scoped work before restoring caller interruption at its join boundary.

**Signature**

```ts
declare const admitOwnedWork: <A>(
  state: WorkOwnershipState,
  scope: Scope.Scope,
  context: Context.Context<never>,
  work: Effect.Effect<A, unknown>,
) => Effect.Effect<A, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.ts#L30)

### joinOwnedWork

Joins every actual completion while retaining failed operations as settled work.

**Signature**

```ts
declare const joinOwnedWork: (
  pending: Iterable<Promise<unknown>>,
) => Effect.Effect<void, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.ts#L56)

### ownedLifecycle

Owns restart and close ordering without replacing native persistence authorities.

**Signature**

```ts
declare const ownedLifecycle: (
  state: WorkOwnershipState,
  scope: Scope.Scope,
  context: Context.Context<never>,
  release: Effect.Effect<void, unknown>,
  acquire: Effect.Effect<void, unknown>,
  cleanup: (failed: boolean) => Effect.Effect<void>,
  closeOperation: OwnedCloseOperation,
) => {
  restart: Effect.Effect<void, unknown, never>;
  close: (failed?: boolean) => Effect.Effect<void, unknown, never>;
};
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.ts#L83)

### runOwnedContext

Runs a native facade callback in its already acquired observation context.

**Signature**

```ts
declare const runOwnedContext: <A>(
  context: Context.Context<never>,
  effect: Effect.Effect<A, unknown>,
) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.ts#L12)

## `work-ownership.types.ts`

Native completion receipts and admission state shared by one scoped harness.

### OwnedCloseOperation (type alias)

Fixed release labels supplied only by the two declaration-owned durable harnesses.

**Signature**

```ts
type OwnedCloseOperation = "job.close" | "event.close";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.types.ts#L12)

### WorkOwnershipState (interface)

Native completion receipts and admission state shared by one scoped harness.

**Signature**

```ts
export interface WorkOwnershipState {
  readonly kind?: string;
  closed: boolean;
  controller: AbortController;
  pending: Set<Promise<unknown>>;
  restarting?: Promise<void>;
  closing?: Promise<void>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/testing/src/work-ownership.types.ts#L2)

---

# Tools API
Source: https://relkit.dev/docs/api/tools

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineTool](/docs/api/tools#definetool)

For configuration and examples, read [tools](/docs/modules/ai/tools), [organization](/docs/modules/service/organization), [ai](/docs/modules/ai).

For a complete workflow, follow [build an offline agent](/guides/ai/build-an-offline-agent).

## Public imports

- `@relkit/tools` — 55 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                          | Kind  | Import from     | Example                                                                      |
| -------------------------------------------------------------------------------------------- | ----- | --------------- | ---------------------------------------------------------------------------- |
| [assertToolDescriptor](/docs/api/tools#asserttooldescriptor)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#asserttooldescriptor)                          |
| [assertToolDescriptorEffect](/docs/api/tools#asserttooldescriptoreffect)                     | Value | `@relkit/tools` | [API example](/docs/api/tools#asserttooldescriptoreffect)                    |
| [createToolRuntime](/docs/api/tools#createtoolruntime)                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#createtoolruntime)                             |
| [createToolRuntimeEffect](/docs/api/tools#createtoolruntimeeffect)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#createtoolruntimeeffect)                       |
| [defineTool](/docs/api/tools#definetool)                                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#definetool)                                    |
| [defineToolEffect](/docs/api/tools#definetooleffect)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#definetooleffect)                              |
| [DefineToolOptions](/docs/api/tools#definetooloptions-interface)                             | Type  | `@relkit/tools` | [API example](/docs/api/tools#definetooloptions-interface)                   |
| [invokeTool](/docs/api/tools#invoketool)                                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#invoketool)                                    |
| [invokeToolEffect](/docs/api/tools#invoketooleffect)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#invoketooleffect)                              |
| [isToolDescriptor](/docs/api/tools#istooldescriptor)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#istooldescriptor)                              |
| [isToolDescriptorEffect](/docs/api/tools#istooldescriptoreffect)                             | Value | `@relkit/tools` | [API example](/docs/api/tools#istooldescriptoreffect)                        |
| [isToolRef](/docs/api/tools#istoolref)                                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#istoolref)                                     |
| [isToolRefEffect](/docs/api/tools#istoolrefeffect)                                           | Value | `@relkit/tools` | [API example](/docs/api/tools#istoolrefeffect)                               |
| [observeTool](/docs/api/tools#observetool-1)                                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#observetool-1)                                 |
| [ResolvedToolTarget](/docs/api/tools#resolvedtooltarget-interface)                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#resolvedtooltarget-interface)                  |
| [resolveToolTarget](/docs/api/tools#resolvetooltarget)                                       | Value | `@relkit/tools` | [API example](/docs/api/tools#resolvetooltarget)                             |
| [resolveToolTargetEffect](/docs/api/tools#resolvetooltargeteffect)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#resolvetooltargeteffect)                       |
| [ToolAllowlistEntry](/docs/api/tools#toolallowlistentry-type-alias)                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolallowlistentry-type-alias)                 |
| [ToolApproval](/docs/api/tools#toolapproval-type-alias)                                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalDecision](/docs/api/tools#toolapprovaldecision-type-alias)                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalDeniedError](/docs/api/functions#functiontoolapprovaldeniederror-class)         | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolapprovaldeniederror-class)     |
| [ToolApprovalRequest](/docs/api/tools#toolapprovalrequest-type-alias)                        | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolApprovalRequiredError](/docs/api/functions#functiontoolapprovalrequirederror-class)     | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolapprovalrequirederror-class)   |
| [ToolApprovalResolver](/docs/api/tools#toolapprovalresolver-type-alias)                      | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolArgumentsFailure](/docs/api/tools#toolargumentsfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#toolargumentsfailure-class)                    |
| [ToolArgumentValidationError](/docs/api/functions#functiontoolargumentvalidationerror-class) | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontoolargumentvalidationerror-class) |
| [ToolCancelledFailure](/docs/api/tools#toolcancelledfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#toolcancelledfailure-class)                    |
| [ToolDescriptor](/docs/api/tools#tooldescriptor-type-alias)                                  | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooldescriptor-type-alias)                     |
| [ToolEffectOptions](/docs/api/tools#tooleffectoptions-type-alias)                            | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooleffectoptions-type-alias)                  |
| [ToolEngine](/docs/api/tools#toolengine-interface)                                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolengine-interface)                          |
| [ToolEngineFailure](/docs/api/tools#toolenginefailure-class)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolenginefailure-class)                       |
| [ToolEngineInvocation](/docs/api/tools#toolengineinvocation-interface)                       | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolengineinvocation-interface)                |
| [ToolEngineLive](/docs/api/tools#toolenginelive)                                             | Value | `@relkit/tools` | [API example](/docs/api/tools#toolenginelive)                                |
| [ToolEngineLiveEffect](/docs/api/tools#toolengineliveeffect)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolengineliveeffect)                          |
| [ToolEngineService](/docs/api/tools#toolengineservice-class)                                 | Value | `@relkit/tools` | [API example](/docs/api/tools#toolengineservice-class)                       |
| [ToolInvocationContext](/docs/api/tools#toolinvocationcontext-interface)                     | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolinvocationcontext-interface)               |
| [ToolInvocationRequest](/docs/api/tools#toolinvocationrequest-interface)                     | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolinvocationrequest-interface)               |
| [ToolInvokeOptions](/docs/api/tools#toolinvokeoptions-type-alias)                            | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolNotAllowedError](/docs/api/tools#toolnotallowederror-class)                             | Value | `@relkit/tools` | [API example](/docs/api/tools#toolnotallowederror-class)                     |
| [ToolNotAllowedFailure](/docs/api/tools#toolnotallowedfailure-class)                         | Value | `@relkit/tools` | [API example](/docs/api/tools#toolnotallowedfailure-class)                   |
| [ToolOperation](/docs/api/tools#tooloperation-type-alias)                                    | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooloperation-type-alias)                      |
| [ToolOperationCancelledError](/docs/api/functions#functiontooloperationcancellederror-class) | Value | `@relkit/tools` | [API example](/docs/api/functions#functiontooloperationcancellederror-class) |
| [ToolOperationFailure](/docs/api/tools#tooloperationfailure-class)                           | Value | `@relkit/tools` | [API example](/docs/api/tools#tooloperationfailure-class)                    |
| [ToolRef](/docs/api/tools#toolref-interface)                                                 | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolref-interface)                             |
| [ToolRefAny](/docs/api/tools#toolrefany-type-alias)                                          | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolRuntime](/docs/api/tools#toolruntime-interface)                                         | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolruntime-interface)                         |
| [ToolRuntimeOptions](/docs/api/tools#toolruntimeoptions-interface)                           | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolruntimeoptions-interface)                  |
| [ToolSideEffect](/docs/api/tools#toolsideeffect-type-alias)                                  | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolSource](/docs/api/tools#toolsource-type-alias)                                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#toolsource-type-alias)                         |
| [ToolTarget](/docs/api/tools#tooltarget-type-alias)                                          | Type  | `@relkit/tools` | [API example](/docs/api/tools#tooltarget-type-alias)                         |
| [ToolTelemetry](/docs/api/tools#tooltelemetry-class)                                         | Value | `@relkit/tools` | [API example](/docs/api/tools#tooltelemetry-class)                           |
| [ToolTelemetryLive](/docs/api/tools#tooltelemetrylive-1)                                     | Value | `@relkit/tools` | [API example](/docs/api/tools#tooltelemetrylive-1)                           |
| [ToolTelemetryService](/docs/api/tools#tooltelemetryservice-interface)                       | Type  | `@relkit/tools` | [Module example](/docs/modules/ai/tools)                                     |
| [ToolUnknownError](/docs/api/tools#toolunknownerror-class)                                   | Value | `@relkit/tools` | [API example](/docs/api/tools#toolunknownerror-class)                        |
| [ToolUnknownFailure](/docs/api/tools#toolunknownfailure-class)                               | Value | `@relkit/tools` | [API example](/docs/api/tools#toolunknownfailure-class)                      |

## `define-tool-predicates.ts`

### assertToolDescriptor

Asserts a tool descriptor.

**Throws**

TypeError when the value is not a tool descriptor.

**Example**

```ts
assertToolDescriptor(value);
```

**Signature**

```ts
declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L78)

### assertToolDescriptorEffect

Asserts a tool descriptor through Effect.

**Example**

```ts
Effect.runSync(assertToolDescriptorEffect(tool));
```

**Signature**

```ts
declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L54)

### isToolDescriptor

Checks a descriptor.

**Example**

```ts
if (isToolDescriptor(value)) await value.invoke({});
```

**Signature**

```ts
declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L45)

### isToolDescriptorEffect

Checks a descriptor through Effect.

**Example**

```ts
Effect.runSync(isToolDescriptorEffect(tool));
```

**Signature**

```ts
declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L19)

### isToolRef

Checks a tool reference.

**Example**

```ts
isToolRef({ ref: { kind: "tool", id: "orders.lookup" } });
```

**Signature**

```ts
declare const isToolRef: (value: unknown) => value is ToolRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L102)

### isToolRefEffect

Checks a tool reference through Effect.

**Example**

```ts
Effect.runSync(isToolRefEffect({ ref: { kind: "tool", id: "orders.lookup" } }));
```

**Signature**

```ts
declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-predicates.ts#L87)

## `define-tool-validation.ts`

### copyFunctionTarget

Copies a validated function target.

**Throws**

TypeError when the target is malformed.

**Example**

```ts
copyFunctionTarget(target);
```

**Signature**

```ts
declare const copyFunctionTarget: <Target extends FunctionRefAny>(
  target: Target,
) => FunctionToolTarget<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L75)

### copyFunctionTargetEffect

Copies and freezes a function target through Effect.

**Example**

```ts
Effect.runSync(copyFunctionTargetEffect(target));
```

**Signature**

```ts
declare const copyFunctionTargetEffect: <Target extends FunctionRefAny>(
  target: Target,
) => Effect.Effect<FunctionToolTarget<Target>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L36)

### hasOwn

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L15)

### hasOwnEffect

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L16)

### isFunctionTarget

**Signature**

```ts
declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L17)

### isFunctionTargetEffect

**Signature**

```ts
declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L18)

### isNonEmptyString

**Signature**

```ts
declare const isNonEmptyString: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L19)

### isNonEmptyStringEffect

**Signature**

```ts
declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L20)

### isPositiveInteger

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L21)

### isPositiveIntegerEffect

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L22)

### isRecord

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L23)

### isRecordEffect

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L24)

### isToolApproval

**Signature**

```ts
declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L25)

### isToolApprovalEffect

**Signature**

```ts
declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L26)

### isToolSideEffect

**Signature**

```ts
declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L27)

### isToolSideEffectEffect

**Signature**

```ts
declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L28)

### positiveInteger

Asserts a safe positive integer.

**Throws**

TypeError when the value is invalid.

**Example**

```ts
positiveInteger(5, "timeoutMs");
```

**Signature**

```ts
declare const positiveInteger: (value: unknown, name: string) => asserts value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L180)

### positiveIntegerEffect

Requires a safe positive integer through Effect.

**Example**

```ts
Effect.runSync(positiveIntegerEffect(5, "timeoutMs"));
```

**Signature**

```ts
declare const positiveIntegerEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<number, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L162)

### requiredText

Requires nonempty trimmed text.

**Throws**

TypeError when the value is empty.

**Example**

```ts
requiredText(" read ", "description");
```

**Signature**

```ts
declare const requiredText: (value: unknown, name: string) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L152)

### requiredTextEffect

Requires nonempty trimmed text through Effect.

**Example**

```ts
Effect.runSync(requiredTextEffect(" read ", "description"));
```

**Signature**

```ts
declare const requiredTextEffect: (
  value: unknown,
  name: string,
) => Effect.Effect<string, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L137)

### validateApproval

Validates a tool approval policy.

**Throws**

TypeError when the policy is unknown.

**Example**

```ts
validateApproval("never");
```

**Signature**

```ts
declare const validateApproval: (value: unknown) => ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L127)

### validateApprovalEffect

Validates a tool approval policy through Effect.

**Example**

```ts
Effect.runSync(validateApprovalEffect("never"));
```

**Signature**

```ts
declare const validateApprovalEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolApproval, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L111)

### validateSideEffect

Validates a tool side-effect policy.

**Throws**

TypeError when the policy is unknown.

**Example**

```ts
validateSideEffect("read");
```

**Signature**

```ts
declare const validateSideEffect: (value: unknown) => ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L102)

### validateSideEffectEffect

Validates a tool side-effect policy through Effect.

**Example**

```ts
Effect.runSync(validateSideEffectEffect("read"));
```

**Signature**

```ts
declare const validateSideEffectEffect: (
  value: unknown,
) => Effect.Effect<FunctionToolSideEffect, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool-validation.ts#L86)

## `define-tool.ts`

### defineTool

Defines a frozen, handler-free tool view over one function.

**Throws**

TypeError for malformed target, metadata, or ID.

**Example**

```ts
import { defineFunction } from "@relkit/functions";
import { z } from "@relkit/schema";
import { defineTool } from "@relkit/tools";
const lookup = defineFunction({
  id: "orders.lookup",
  input: z.string(),
  output: z.string(),
  handler: (id) => id,
});
const tool = defineTool({
  id: "orders.lookup-tool",
  target: lookup,
  description: "Read order",
  sideEffect: "read",
  approval: "never",
});
```

**Signature**

```ts
declare const defineTool: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => ToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L137)

Since v0.1.0

### "./define-tool.types.js" (namespace export)

Re-exports all named exports from the "./define-tool.types.js" module.

**Signature**

```ts
export * from "./define-tool.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L29)

### ToolApprovalDeniedError

**Signature**

```ts
declare const ToolApprovalDeniedError: typeof FunctionToolApprovalDeniedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L39)

### ToolApprovalRequiredError

**Signature**

```ts
declare const ToolApprovalRequiredError: typeof FunctionToolApprovalRequiredError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L40)

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L41)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof FunctionToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L42)

### assertToolDescriptor

**Signature**

```ts
declare const assertToolDescriptor: (value: unknown) => asserts value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L31)

### assertToolDescriptorEffect

**Signature**

```ts
declare const assertToolDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ToolDescriptor<string>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L32)

### defineToolEffect

Defines a frozen, handler-free tool view through Effect.

**Example**

```ts
Effect.runSync(
  defineToolEffect({
    id: "orders.lookup",
    target,
    description: "Read order",
    sideEffect: "read",
    approval: "never",
  }),
);
```

**Signature**

```ts
declare const defineToolEffect: <const Id extends string, const Target extends FunctionRefAny>(
  options: DefineToolOptions<Id, Target>,
) => Effect.Effect<ToolDescriptor<Id, Target>, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L50)

### isToolDescriptor

**Signature**

```ts
declare const isToolDescriptor: (value: unknown) => value is ToolDescriptor<string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L33)

### isToolDescriptorEffect

**Signature**

```ts
declare const isToolDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L34)

### isToolRef

**Signature**

```ts
declare const isToolRef: (value: unknown) => value is ToolRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L35)

### isToolRefEffect

**Signature**

```ts
declare const isToolRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.ts#L36)

## `define-tool.types.ts`

### DefineToolOptions (interface)

Authoring options for a handler-free tool view.

**Example**

```ts
const options: DefineToolOptions<"orders.lookup", typeof target> = {
  id: "orders.lookup",
  target,
  description: "Read an order",
  sideEffect: "read",
  approval: "never",
};
```

**Signature**

```ts
export interface DefineToolOptions<
  Id extends string,
  Target extends FunctionRefAny,
> extends FunctionToolMetadata {
  readonly id?: Id;
  readonly target: Target;
  readonly onBefore?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferInput<Target["input"]>
  >;
  readonly onAfter?: import("@relkit/functions").FunctionToolHook<
    import("@relkit/schema").InferOutput<Target["output"]>
  >;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L51)

### ToolApproval (type alias)

Approval policy inherited from a function tool.

**Signature**

```ts
type ToolApproval = FunctionToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L17)

### ToolApprovalDecision (type alias)

Decision returned by a tool approval resolver.

**Signature**

```ts
type ToolApprovalDecision = FunctionToolApprovalDecision;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L19)

### ToolApprovalRequest (type alias)

Request passed to a tool approval resolver.

**Signature**

```ts
type ToolApprovalRequest = FunctionToolApprovalRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L21)

### ToolApprovalResolver (type alias)

Resolver for tool approval requests.

**Signature**

```ts
type ToolApprovalResolver = FunctionToolApprovalResolver;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L23)

### ToolDescriptor (type alias)

Frozen, handler-free tool descriptor.

**Example**

```ts
const descriptor: ToolDescriptor<"orders.lookup.tool"> = defineTool(options);
```

**Signature**

```ts
type ToolDescriptor<
  Id extends string,
  Target extends FunctionRefAny = FunctionRefAny,
> = FunctionToolDescriptor<Id, Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L43)

### ToolInvokeOptions (type alias)

Options for invoking the function view of a tool.

**Signature**

```ts
type ToolInvokeOptions = FunctionToolInvokeOptions;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L25)

### ToolRef (interface)

Stable reference to a tool descriptor.

**Example**

```ts
const ref: ToolRef<"orders.lookup"> = { ref: { kind: "tool", id: "orders.lookup" } };
```

**Signature**

```ts
export interface ToolRef<Id extends string = string> {
  readonly ref: { readonly kind: "tool"; readonly id: Id };
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L30)

### ToolRefAny (type alias)

Any stable tool reference.

**Signature**

```ts
type ToolRefAny = ToolRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L35)

### ToolSideEffect (type alias)

Effect policy inherited from a function tool.

**Signature**

```ts
type ToolSideEffect = FunctionToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L15)

### ToolTarget (type alias)

Validated function target copied into a tool.

**Example**

```ts
const copied: ToolTarget<typeof target> = copyFunctionTarget(target);
```

**Signature**

```ts
type ToolTarget<Target extends FunctionRefAny> = FunctionToolTarget<Target>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/define-tool.types.ts#L39)

## `index.ts`

### "./define-tool.js" (namespace export)

Re-exports all named exports from the "./define-tool.js" module.

**Signature**

```ts
export * from "./define-tool.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L1)

### "./runtime.js" (namespace export)

Re-exports all named exports from the "./runtime.js" module.

**Signature**

```ts
export * from "./runtime.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L2)

### ToolOperation

**Signature**

```ts
declare const ToolOperation: ToolOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L9)

### ToolOperationFailure

**Signature**

```ts
declare const ToolOperationFailure: typeof ToolOperationFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L4)

### ToolTelemetry

**Signature**

```ts
declare const ToolTelemetry: typeof ToolTelemetry;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L5)

### ToolTelemetryLive

**Signature**

```ts
declare const ToolTelemetryLive: Layer<ToolTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L6)

### ToolTelemetryService

**Signature**

```ts
declare const ToolTelemetryService: ToolTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L9)

### observeTool

**Signature**

```ts
declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect<A, E, R>,
) => Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/index.ts#L7)

## `runtime-engine.ts`

### ToolEngineLive

Provides a common engine to an Effect invocation.

**Throws**

Unexpected construction defects.

**Example**

```ts
ToolEngineLive({ invoke: async ({ input }) => input });
```

**Signature**

```ts
declare const ToolEngineLive: (engine: ToolEngine) => Layer.Layer<ToolEngineService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L30)

### ToolEngineLiveEffect

Constructs a composable engine Layer through Effect.

**Example**

```ts
Effect.runSync(ToolEngineLiveEffect(engine));
```

**Signature**

```ts
declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer.Layer<ToolEngineService, never, never>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L17)

### ToolEngineService (class)

Replaceable engine used by Effect tool invocation.

**Example**

```ts
Effect.provide(invokeToolEffect(request), ToolEngineLive(engine));
```

**Signature**

```ts
declare class ToolEngineService
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-engine.ts#L8)

## `runtime-errors.ts`

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof ToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L71)

### ToolArgumentsFailure (class)

Tagged Effect failure for malformed JSON or schema validation.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolArgumentsFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolArgumentsFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L50)

### ToolCancelledFailure (class)

Tagged Effect failure for cancellation before engine dispatch.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolCancelledFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolCancelledFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L58)

### ToolEngineFailure (class)

Tagged Effect failure from the common engine boundary.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolEngineFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolEngineFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L66)

### ToolNotAllowedError (class)

Compatibility error for a registered tool excluded by policy.

**Example**

```ts
throw new ToolNotAllowedError("orders.delete");
```

**Signature**

```ts
declare class ToolNotAllowedError { constructor(readonly toolId: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L22)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TOOL_NOT_ALLOWED"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L23)

### ToolNotAllowedFailure (class)

Tagged Effect failure for a tool excluded by the allowlist.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolNotAllowedFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolNotAllowedFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L42)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L71)

### ToolUnknownError (class)

Compatibility error for a tool ID absent from the registered source.

**Example**

```ts
throw new ToolUnknownError("orders.missing");
```

**Signature**

```ts
declare class ToolUnknownError { constructor(readonly toolId: string) }
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L10)

### code (property)

**Signature**

```ts
readonly code: "RELKIT_TOOL_UNKNOWN"
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L11)

### ToolUnknownFailure (class)

Tagged Effect failure for an unknown registered tool.

**Example**

```ts
Effect.catchTag(invokeToolEffect(request), "ToolUnknownFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolUnknownFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-errors.ts#L34)

## `runtime-input.ts`

### parseToolArgumentsEffect

Parses a model-returned argument value through Effect.

**Example**

```ts
Effect.runSync(parseToolArgumentsEffect('{"id":1}'));
```

**Signature**

```ts
declare const parseToolArgumentsEffect: (
  value: unknown,
) => Effect.Effect<unknown, ToolArgumentsFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-input.ts#L11)

### validateToolArgumentsEffect

Validates tool input through the inherited standard schema.

**Example**

```ts
await Effect.runPromise(validateToolArgumentsEffect(schema, { id: 1 }));
```

**Signature**

```ts
declare const validateToolArgumentsEffect: (
  schema: StandardSchemaV1<unknown, unknown>,
  value: unknown,
) => Effect.Effect<void, ToolArgumentsFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-input.ts#L32)

## `runtime-resolution.ts`

### findToolEffect

Finds a canonical descriptor in any supported collection.

**Example**

```ts
Effect.runSync(findToolEffect([tool], tool.id));
```

**Signature**

```ts
declare const findToolEffect: (
  source: ToolSource,
  id: string,
) => Effect.Effect<any, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L61)

### isToolAllowedEffect

Checks a tool's canonical ID against an allowlist.

**Example**

```ts
Effect.runSync(isToolAllowedEffect(tool.id, [tool.id]));
```

**Signature**

```ts
declare const isToolAllowedEffect: (
  id: string,
  allowlist: ReadonlyArray<ToolAllowlistEntry>,
) => Effect.Effect<boolean, ToolOperationFailure, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L89)

### resolveToolTarget

Resolves a tool's function ID and inherited schemas.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
resolveToolTarget(tool);
```

**Signature**

```ts
declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L51)

### resolveToolTargetEffect

Resolves a tool's function ID and inherited schemas through Effect.

**Example**

```ts
Effect.runSync(resolveToolTargetEffect(tool));
```

**Signature**

```ts
declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime-resolution.ts#L14)

## `runtime.ts`

### "./runtime.types.js" (namespace export)

Re-exports all named exports from the "./runtime.types.js" module.

**Signature**

```ts
export * from "./runtime.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L34)

### ToolArgumentValidationError

**Signature**

```ts
declare const ToolArgumentValidationError: typeof FunctionToolArgumentValidationError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L36)

### ToolArgumentsFailure

**Signature**

```ts
declare const ToolArgumentsFailure: typeof ToolArgumentsFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L43)

### ToolCancelledFailure

**Signature**

```ts
declare const ToolCancelledFailure: typeof ToolCancelledFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L42)

### ToolEngineFailure

**Signature**

```ts
declare const ToolEngineFailure: typeof ToolEngineFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L44)

### ToolEngineLive

**Signature**

```ts
declare const ToolEngineLive: (engine: ToolEngine) => Layer<ToolEngineService, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolEngineLiveEffect

**Signature**

```ts
declare const ToolEngineLiveEffect: (
  engine: ToolEngine,
) => Effect.Effect<Layer<ToolEngineService, never, never>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolEngineService

**Signature**

```ts
declare const ToolEngineService: typeof ToolEngineService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L46)

### ToolNotAllowedError

**Signature**

```ts
declare const ToolNotAllowedError: typeof ToolNotAllowedError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L39)

### ToolNotAllowedFailure

**Signature**

```ts
declare const ToolNotAllowedFailure: typeof ToolNotAllowedFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L41)

### ToolOperationCancelledError

**Signature**

```ts
declare const ToolOperationCancelledError: typeof ToolOperationCancelledError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L37)

### ToolUnknownError

**Signature**

```ts
declare const ToolUnknownError: typeof ToolUnknownError;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L38)

### ToolUnknownFailure

**Signature**

```ts
declare const ToolUnknownFailure: typeof ToolUnknownFailure;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L40)

### createToolRuntime

Creates a reusable Promise runtime.

**Throws**

Unexpected defects from runtime construction.

**Example**

```ts
const runtime = createToolRuntime({ tools: [tool], engine });
```

**Signature**

```ts
declare const createToolRuntime: (options: ToolRuntimeOptions) => ToolRuntime;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L179)

### createToolRuntimeEffect

Creates a reusable compatibility runtime through Effect.
The allowlist is copied at creation; the caller retains ownership of tools and engine.

**Example**

```ts
Effect.runSync(createToolRuntimeEffect({ tools: [tool], engine }));
```

**Signature**

```ts
declare const createToolRuntimeEffect: (
  options: ToolRuntimeOptions,
) => Effect.Effect<ToolRuntime, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L152)

### invokeTool

Invokes one allowlisted tool through the common engine.

**Throws**

ToolUnknownError, ToolNotAllowedError, argument errors, or engine rejection.

**Example**

```ts
await invokeTool({ tools: [tool], engine, toolId: "orders.lookup", arguments: {} });
```

**Signature**

```ts
declare const invokeTool: (options: ToolRuntimeOptions & ToolEffectOptions) => Promise<unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L142)

### invokeToolEffect

Invokes an allowlisted tool with a replaceable Effect engine service.
Validation finishes before engine dispatch. Cancellation before dispatch
prevents the engine from starting. Interruption and caller cancellation reach
the engine through its invocation signal.

**Example**

```ts
await Effect.runPromise(
  Effect.provide(
    invokeToolEffect({ tools: [tool], toolId: "orders.lookup", arguments: {} }),
    ToolEngineLive(engine),
  ),
);
```

**Signature**

```ts
declare const invokeToolEffect: (
  options: ToolEffectOptions,
) => Effect.Effect<
  unknown,
  | ToolOperationFailure
  | ToolArgumentsFailure
  | ToolUnknownFailure
  | ToolNotAllowedFailure
  | ToolCancelledFailure
  | ToolEngineFailure,
  ToolEngineService
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L57)

### resolveToolTarget

**Signature**

```ts
declare const resolveToolTarget: (tool: ToolDescriptor<string>) => ResolvedToolTarget;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L47)

### resolveToolTargetEffect

**Signature**

```ts
declare const resolveToolTargetEffect: (tool: ToolDescriptor<string>) => Effect.Effect<
  Readonly<{
    errors?: ReadonlyArray<ErrorDescriptorAny>;
    functionId: string;
    input: StandardSchemaV1<unknown, unknown>;
    output: StandardSchemaV1<unknown, unknown>;
  }>,
  ToolOperationFailure,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.ts#L47)

## `runtime.types.ts`

### ResolvedToolTarget (interface)

Function target and schemas resolved from a tool.

**Example**

```ts
const target: ResolvedToolTarget = resolveToolTarget(tool);
```

**Signature**

```ts
export interface ResolvedToolTarget {
  readonly functionId: string;
  readonly input: StandardSchemaV1;
  readonly output: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L102)

### ToolAllowlistEntry (type alias)

One allowed tool ID or reference.

**Example**

```ts
const allowed: ToolAllowlistEntry = "orders.lookup.tool";
```

**Signature**

```ts
type ToolAllowlistEntry = string | ToolRefAny | ToolRefAny["ref"];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L46)

### ToolEffectOptions (type alias)

Effect invocation input; the engine arrives from ToolEngineService.

**Example**

```ts
const request: ToolEffectOptions = { tools: [tool], toolId: tool.id, arguments: {} };
```

**Signature**

```ts
type ToolEffectOptions = Omit<ToolRuntimeOptions, "engine"> & ToolInvocationRequest;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L60)

### ToolEngine (interface)

Small engine seam that keeps tools independent of the engine package.

**Example**

```ts
const engine: ToolEngine = { invoke: async (request) => request.input };
```

**Signature**

```ts
export interface ToolEngine {
  /** Invoke a validated target through the common engine.
   * @param options - Target schemas, input, and inherited invocation context.
   * @returns The function output or an engine rejection.
   * @example await engine.invoke(invocation);
   */
  readonly invoke: (options: ToolEngineInvocation) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L27)

### ToolEngineInvocation (interface)

Invocation forwarded to the common function engine.

**Example**

```ts
const invocation: ToolEngineInvocation = {
  functionId: "orders.lookup",
  input: {},
  source: "tool",
  inputSchema,
  outputSchema,
};
```

**Signature**

```ts
export interface ToolEngineInvocation {
  readonly functionId: string;
  readonly input: unknown;
  readonly source: "tool";
  readonly inputSchema: StandardSchemaV1;
  readonly outputSchema: StandardSchemaV1;
  readonly errors?: readonly ErrorDescriptorAny[];
  readonly timeoutMs?: number;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly toolHooks?: unknown;
  readonly progressSink?: ProgressSink;
  readonly parent?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L9)

### ToolInvocationContext (interface)

Optional cancellation context for a runtime call.

**Example**

```ts
const context: ToolInvocationContext = { signal: controller.signal };
```

**Signature**

```ts
export interface ToolInvocationContext {
  readonly signal?: AbortSignal;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L77)

### ToolInvocationRequest (interface)

Input for one engine-backed tool invocation.

**Example**

```ts
const request: ToolInvocationRequest = { toolId: "orders.lookup", arguments: {} };
```

**Signature**

```ts
export interface ToolInvocationRequest {
  readonly toolId: string;
  /** Parsed JSON or model-returned JSON text. */
  readonly arguments: unknown;
  readonly signal?: AbortSignal;
  readonly hooks?: unknown;
  readonly parent?: unknown;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L65)

### ToolRuntime (interface)

Reusable Promise compatibility runtime.

**Example**

```ts
await runtime.invoke("orders.lookup", { id: "a" });
```

**Signature**

```ts
export interface ToolRuntime {
  /** Invoke one registered tool.
   * @param toolId - Canonical tool ID.
   * @param arguments_ - Parsed input or JSON text.
   * @param options - Optional cancellation context.
   * @returns Engine output or a rejected compatibility error.
   * @example await runtime.invoke("orders.lookup.tool", { id: "one" });
   */
  readonly invoke: (
    toolId: string,
    arguments_: unknown,
    options?: ToolInvocationContext,
  ) => Promise<unknown>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L84)

### ToolRuntimeOptions (interface)

Runtime dependencies and optional allowlist.

**Example**

```ts
const options: ToolRuntimeOptions = { tools: [tool], engine };
```

**Signature**

```ts
export interface ToolRuntimeOptions {
  readonly tools: ToolSource;
  readonly engine: ToolEngine;
  readonly allowedTools?: readonly ToolAllowlistEntry[];
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L51)

### ToolSource (type alias)

Supported tool collections.

**Example**

```ts
const tools: ToolSource = [tool];
```

**Signature**

```ts
type ToolSource =
  | readonly ToolDescriptor<string>[]
  | ReadonlyMap<string, ToolDescriptor<string>>
  | Readonly<Record<string, ToolDescriptor<string>>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/runtime.types.ts#L39)

## `tool-observability.ts`

### ToolOperation

**Signature**

```ts
declare const ToolOperation: ToolOperation;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L11)

### ToolOperationFailure (class)

Expected tool input or authoring failure with the original adapter error.

**Example**

```ts
Effect.catchTag(defineToolEffect(options), "ToolOperationFailure", () => Effect.void);
```

**Signature**

```ts
declare class ToolOperationFailure
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L16)

### ToolTelemetry (class)

Replaceable telemetry boundary for all tool operations.

**Example**

```ts
Effect.provide(defineToolEffect(options), ToolTelemetryLive);
```

**Signature**

```ts
declare class ToolTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L24)

### ToolTelemetryLive

Live Effect metric and span observer.

**Example**

```ts
Effect.runSync(Effect.provide(Effect.void, ToolTelemetryLive));
```

**Signature**

```ts
declare const ToolTelemetryLive: Layer.Layer<ToolTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L37)

### ToolTelemetryService

**Signature**

```ts
declare const ToolTelemetryService: ToolTelemetryService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L11)

### observeTool

Adds bounded operation telemetry while preserving the original channels.

**Example**

```ts
observeTool("is-ref", Effect.succeed(true));
```

**Signature**

```ts
declare const observeTool: <A, E, R>(
  operation: ToolOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L45)

### runToolPromise

Runs a Promise compatibility adapter and restores its original error.

**Throws**

The original input error or an unexpected defect.

**Example**

```ts
await runToolPromise(Effect.succeed(1));
```

**Signature**

```ts
declare const runToolPromise: <A, E>(effect: Effect.Effect<A, E>) => Promise<A>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L96)

### runToolSync

Runs a synchronous compatibility adapter and restores its original error.

**Throws**

The original input error or an unexpected defect.

**Example**

```ts
runToolSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runToolSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L82)

### toolAttempt

Evaluates a step within an already observed operation.

**Example**

```ts
yield * toolAttempt("define", () => descriptor);
```

**Signature**

```ts
declare const toolAttempt: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L142)

### toolTry

Captures a marked validation error from a synchronous calculation.

**Example**

```ts
Effect.runSync(toolTry("required-text", () => "ok"));
```

**Signature**

```ts
declare const toolTry: <A>(
  operation: ToolOperation,
  evaluate: () => A,
) => Effect.Effect<A, ToolOperationFailure>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.ts#L129)

## `tool-observability.types.ts`

### ToolOperation (type alias)

Fixed names for tool operations; values must never contain user input.

**Example**

```ts
const operation: ToolOperation = "invoke";
```

**Signature**

```ts
type ToolOperation =
  | "define"
  | "is-descriptor"
  | "assert-descriptor"
  | "is-ref"
  | "copy-target"
  | "validate-side-effect"
  | "validate-approval"
  | "is-side-effect"
  | "is-approval"
  | "required-text"
  | "positive-integer"
  | "is-positive-integer"
  | "is-function-target"
  | "is-non-empty-string"
  | "is-record"
  | "has-own"
  | "resolve-target"
  | "engine-layer"
  | "invoke"
  | "create-runtime";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.types.ts#L6)

### ToolTelemetryService (interface)

Replaceable observer used to verify spans and metrics in tests.

**Signature**

```ts
export interface ToolTelemetryService {
  /** Observe an operation without changing its channels.
   * @param operation - Stable, bounded operation name.
   * @param effect - Work to observe.
   * @returns The same success and failure channels.
   * @example telemetry.observe("is-ref", Effect.succeed(true));
   */
  readonly observe: <A, E, R>(
    operation: ToolOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-observability.types.ts#L29)

## `tool-predicates.ts`

### hasOwn

Checks an own property.

**Example**

```ts
hasOwn({ id: 1 }, "id");
```

**Signature**

```ts
declare const hasOwn: (value: object, key: PropertyKey) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L136)

### hasOwnEffect

Checks an own property through Effect.

**Example**

```ts
Effect.runSync(hasOwnEffect({ id: 1 }, "id"));
```

**Signature**

```ts
declare const hasOwnEffect: (
  value: object,
  key: PropertyKey,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L123)

### isFunctionTarget

Checks a function target.

**Example**

```ts
isFunctionTarget(target);
```

**Signature**

```ts
declare const isFunctionTarget: (
  value: unknown,
) => value is import("@relkit/functions").FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L167)

### isFunctionTargetEffect

Checks a function target through Effect.

**Example**

```ts
Effect.runSync(isFunctionTargetEffect(target));
```

**Signature**

```ts
declare const isFunctionTargetEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L145)

### isNonEmptyString

Checks a nonempty string.

**Example**

```ts
isNonEmptyString("hello");
```

**Signature**

```ts
declare const isNonEmptyString: (value: unknown) => value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L92)

### isNonEmptyStringEffect

Checks a nonempty string through Effect.

**Example**

```ts
Effect.runSync(isNonEmptyStringEffect("hello"));
```

**Signature**

```ts
declare const isNonEmptyStringEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L80)

### isPositiveInteger

Checks a safe positive integer.

**Example**

```ts
isPositiveInteger(2);
```

**Signature**

```ts
declare const isPositiveInteger: (value: unknown) => value is number;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L71)

### isPositiveIntegerEffect

Checks a safe positive integer through Effect.

**Example**

```ts
Effect.runSync(isPositiveIntegerEffect(2));
```

**Signature**

```ts
declare const isPositiveIntegerEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L59)

### isRecord

Checks a plain non-array object.

**Example**

```ts
isRecord({ id: 1 });
```

**Signature**

```ts
declare const isRecord: (value: unknown) => value is Record<PropertyKey, unknown>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L113)

### isRecordEffect

Checks a plain non-array object through Effect.

**Example**

```ts
Effect.runSync(isRecordEffect({ id: 1 }));
```

**Signature**

```ts
declare const isRecordEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L101)

### isToolApproval

Checks a tool approval policy.

**Example**

```ts
isToolApproval("never");
```

**Signature**

```ts
declare const isToolApproval: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolApproval;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L48)

### isToolApprovalEffect

Checks a tool approval policy through Effect.

**Example**

```ts
Effect.runSync(isToolApprovalEffect("never"));
```

**Signature**

```ts
declare const isToolApprovalEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L36)

### isToolSideEffect

Checks a tool side-effect policy.

**Example**

```ts
isToolSideEffect("read");
```

**Signature**

```ts
declare const isToolSideEffect: (
  value: unknown,
) => value is import("./define-tool.types.js").ToolSideEffect;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L25)

### isToolSideEffectEffect

Checks a tool side-effect policy through Effect.

**Example**

```ts
Effect.runSync(isToolSideEffectEffect("read"));
```

**Signature**

```ts
declare const isToolSideEffectEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/tools/src/tool-predicates.ts#L11)

---

# Build your first API
Source: https://relkit.dev/docs/learn

Build an Orders API one step at a time. Each chapter continues the application from the previous chapter, so keep the same project directory.

> **Before you begin**
>
> You need basic TypeScript, a terminal, and Bun 1.3.10 or later. The first request runs locally
> without a database or cloud account.

1. [Create and run an API](/docs/learn/create-an-app). Start the server and receive a greeting.

2. [Add an Orders endpoint](/docs/learn/first-route). Create an order and reject invalid input.

3. [Save orders](/docs/learn/save-orders). Persist and retrieve application data.

4. [Protect orders](/docs/learn/protect-orders). Add sign-in and require a session.

5. [Test the Orders API](/docs/learn/test-orders). Check successful requests and expected failures.

6. [Develop locally](/docs/learn/local-development). Understand validation, reloads, and optional inspection.

7. [Build and run for production](/docs/learn/build-and-run). Run the built server and verify its behavior.

Start with **[Create and run an API](/docs/learn/create-an-app)**.

## Understand the concepts

After you have a working endpoint, use [Core concepts](/docs/learn/concepts) to understand functions, schemas, services, and the application graph. These pages support the tutorial; you can return to them whenever you need an explanation.

---

# Build and run for production
Source: https://relkit.dev/docs/learn/build-and-run

Build the Orders API and run the production server on your machine. You'll verify that the same
account can still read its stored order after the development server stops.

Continue from [Local development](/docs/learn/local-development), with the tests and migrations from the preceding chapters complete.

1. ## 1. Build and start the server

    Stop `bun run dev` first. Keep `DATABASE_PATH`, `BETTER_AUTH_URL`, and the **same**
    `BETTER_AUTH_SECRET` used for the existing accounts. Keep the migrations and SQLite file in place.

    ```sh title="Terminal — relkit-orders"
    set -a
    . ./.env
    set +a
    bun run check
    bun run typecheck
    bun run test
    bun run build
    bun run start
    ```

    The ignored `.env` contains the same secret from the auth chapter; changing it would
    invalidate existing sessions. Keep this terminal open while the local production server runs.

    Production builds exclude the rich development Inspector even when `inspector.enabled`
    was selected during development. The optional [standalone Inspector](/docs/modules/operations/inspector)
    runs separately from `bun run dev`; it is not part of `bun run start`.

2. ## 2. Sign in and read the order

    In a second terminal, sign in with the account from the authentication chapter and verify the
    protected read again:

    ```sh title="Second terminal — relkit-orders"
    auth_cookies=$(mktemp -t relkit-orders-cookies)
    curl -i -c "$auth_cookies" http://127.0.0.1:3000/api/auth/sign-in/email \
      -H 'content-type: application/json' -H 'origin: http://127.0.0.1:3000' \
      --data '{"email":"demo@example.com","password":"local-demo-password-123"}'
    curl -i http://127.0.0.1:3000/orders/private-1
    curl -i -b "$auth_cookies" http://127.0.0.1:3000/orders/private-1
    ```

    Expect `401` without a cookie and `found: true` with the same account's valid cookie.
    The order data should survive both development-server and production-server restarts because
    it is stored in `orders.sqlite`.

    Your local application is complete. For another capability, use the relevant feature guide;
    for exact signatures or flags, use the API and CLI references. Cloud deployment is a separate
    optional task covered by [Deployment](/docs/modules/deployment).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/routes` API](/docs/api/routes)

- [`templates/default/v1/api/package.json`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/package.json)

---

# Core concepts
Source: https://relkit.dev/docs/learn/concepts

Use these pages to understand the code you've written in the Orders tutorial. Start with functions and schemas, then explore how RELKIT connects the application. Development,
tests, HTTP, events, jobs, the Inspector, generated clients, and deployment all consume that graph instead of
maintaining separate descriptions of the application.

## Learn the model in order

**[Application configuration](/docs/learn/concepts/application)**

Use defineApp to connect the server, environment, and integrations in relkit.config.ts.

**[Environment contracts](/docs/learn/concepts/environment)**

Use defineEnv to declare typed values, defaults, and secrets.

**[Functions](/docs/learn/concepts/functions)**

Define reusable behavior with validated input, output, errors, and dependencies.

**[Schemas and errors](/docs/learn/concepts/schemas)**

Keep runtime boundaries explicit and failures safe for callers.

**[Context and environment](/docs/learn/concepts/context)**

Use invocation-scoped capabilities and typed runtime configuration.

Start with the application model and functions. Schemas define values crossing a boundary; declared errors
define expected failures. Context grants one invocation access to its approved capabilities, while the
environment contract resolves process configuration before handlers run.

## One source, many consumers

The certified minimal starter keeps the root configuration intentionally small:

```ts title="templates/default/v1/minimal/relkit.config.ts"
/** Declares backend defaults; inspection remains disabled unless explicitly enabled. */
import { defineApp } from "@relkit/app/config";
import env from "@app/platform/env.js";
// relkit:create:deployment-imports

export default defineApp({
  env,
  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
  server: { port: 3000, maxBodyBytes: 1_048_576, apiDocs: { ui: "scalar" } },
  // relkit:create:deployment
});
```

Source files are the application. `.relkit/generated` and `.relkit/build` are derived artifacts; inspect them
when diagnosing a problem, but repair the descriptor, configuration, or environment that produced them.

```text title="Application flow"
TypeScript descriptors → relkit check → application graph
                                      ↘ dev · tests · build · inspector · deployment
```

## Check your understanding

From a generated application, run:

```sh title="Terminal — relkit-orders"
bun run check
bun run relkit graph print
```

`check` evaluates configuration, discovers descriptors, validates graph relationships, and refreshes generated
contracts. `graph print` lets you inspect the resulting IDs and edges without starting the server or creating
external resources.

Continue with [Service](/docs/modules/service) after these concepts to organize behavior by domain and choose the
public operations other domains and transports may call.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/schema` API](/docs/api/schema)

- [`templates/default/v1/api/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/relkit.config.ts)

---

# Application configuration
Source: https://relkit.dev/docs/learn/concepts/application

Your application configuration connects the server, environment values, integrations, and optional tools in one place: `relkit.config.ts`. The compiler evaluates it to connect the environment
contract, integration bindings, server policy, telemetry, Inspector, and optional deployment roles. Domain
handlers do not import this file.

Use [defineApp](/docs/api/app#defineapp) from `@relkit/app/config` to declare this configuration.
`defineConfig` is no longer exported by RELKIT. The environment declaration comes from
[defineEnv](/docs/api/config#defineenv), explained in [Environment contracts](/docs/learn/concepts/environment).

## Configure the application with defineApp [#read-the-generated-configuration]

```ts title="templates/default/v1/minimal/relkit.config.ts"
/** Declares backend defaults; inspection remains disabled unless explicitly enabled. */
import { defineApp } from "@relkit/app/config";
import env from "@app/platform/env.js";
// relkit:create:deployment-imports

export default defineApp({
  env,
  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
  server: { port: 3000, maxBodyBytes: 1_048_576, apiDocs: { ui: "scalar" } },
  // relkit:create:deployment
});
```

The certified minimal app starts local-only: one environment contract, bounded telemetry capture and
an application listener. Inspection is disabled; the [standalone tool](/docs/modules/operations/inspector) has
its own install/enable/run procedure. Cloud and deployment remain unselected, and the AWS/Pulumi
creation tuple is currently unavailable. Add only explicitly [selected integration packages](/docs/modules/integrations)
and their native SDKs before importing their constructors into this config.

## Import Platform fragments explicitly

Keep domain-independent configuration under `src/platform/` when the root configuration
becomes long. Import each fragment into `relkit.config.ts` and pass it to the existing
`defineApp` option. For example:

Create the shared server fragment:

```ts title="src/platform/server.ts"
/**
 * Shares backend listener/body limits through an explicitly imported Platform
 * fragment. The application config merges this plain descriptor; importing it
 * starts no listener and selects no optional integration or Inspector tool.
 */
export const server = { port: 3000, maxBodyBytes: 1_048_576 };
```

In the existing root configuration, import `server` from `@app/platform/server.js` and pass it to
`defineApp` alongside the existing `env` and other options. Preserve those existing options when merging.

The same explicit-import pattern applies to Inspector, telemetry, provider and deployment
configuration. A filename does not activate a fragment. Unused Platform modules are not
autoloaded, and imported configuration still must not acquire native clients or provision
resources. Platform fragments cannot import services, routes or application tooling.

Add an explicit application `id` before the application owns durable deployment state. Keep the same ID across
staging and production; stacks isolate environments. Changing a deployed application ID can make its resources
appear to have a new owner.

## Keep evaluation deterministic

Configuration describes topology. It must not open a database connection, call a remote API, start a server,
or create cloud resources during module import. Integration constructors describe bindings; runtimes activate
their clients only after the graph has passed validation.

Use each layer for one responsibility:

| Concern                                                          | Source of truth                                              |
| ---------------------------------------------------------------- | ------------------------------------------------------------ |
| Stable identity, ports, limits, telemetry, and binding selection | `relkit.config.ts`                                           |
| Runtime values and secrets                                       | The [environment contract](/docs/learn/concepts/environment) |
| Business behavior                                                | [Functions](/docs/learn/concepts/functions)                  |
| Public domain boundary                                           | [Services](/docs/modules/service/define)                     |
| Durable task/job bindings and schedules                          | [Jobs](/docs/modules/jobs/bindings)                          |
| Adapter and infrastructure selection                             | [Integrations](/docs/modules/integrations)                   |

## Verify a topology change

1. ### Change one setting

    Edit `server.maxBodyBytes`, a provider profile, or another configuration value. Keep credentials out of
    literals and pass named secret bindings to integrations.

2. ### Validate without starting the app

    ```sh title="Terminal — relkit-orders"
    bun run check
    bun run relkit graph print
    ```

    Expect one application graph with the configured bindings and no external provisioning.

3. ### Restart listener changes

    Development can activate descriptor changes without dropping the last valid generation. Port and listener
    changes may require stopping and restarting `bun run dev`.

    If a release check rejects a `docker(adapter)` binding, add a connected or supported infrastructure source.
    Docker recipes are local development services and never become deployment resources.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)

- [`templates/default/v1/api/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/relkit.config.ts)

---

# Invocation context
Source: https://relkit.dev/docs/learn/concepts/context

A function's second parameter, `context`, gives that invocation access to logging, time, cancellation, and its declared resources. RELKIT builds it from the checked graph, so a function
receives common runtime capabilities plus typed clients for only the resources it declares. Never store context
in a module variable or reuse it after the invocation completes.

## Use declared clients

> **Before you begin**
>
> This larger commerce reference assumes its selected cache is installed and bound. When adapting it
> to a minimal app, complete [cache setup](/guides/caching/cache-product-prices) first. Declaring a
> context edge does not install an adapter or native SDK.

```ts title="examples/commerce/src/services/orders/functions/create-order.function.ts"
/** Prices validated order input through the declared cache, records request tracing and derives its receipt key. */
import { defineFunction } from "@relkit/app/functions";
import prices from "../cache/prices.cache.js";
import { receiptObjectName } from "../../../platform/receipt-object.js";
import { createOrderOutput, orderInput } from "../../../platform/schemas.js";

const createOrder = defineFunction({
  // RELKIT validates these schemas before the handler runs.
  input: orderInput,
  output: createOrderOutput,
  dependencies: {
    cache: { prices },
  },
  timeoutMs: 10_000,
  concurrency: 100,
  handler: async (input, context) => {
    // Dependencies are accessed through the checked execution context.
    const unitPrice = await context.trace.span(
      "pricing.calculate",
      { attributes: { "pricing.strategy": "catalog" } },
      () => context.cache.prices.getOrSet({ sku: input.sku }, async () => 1_000),
    );
    context.trace.event("pricing.calculated", { "pricing.unit_cents": unitPrice });
    context.trace.setAttributes({ "pricing.quantity": input.quantity });
    const totalCents = unitPrice * input.quantity;
    return {
      orderId: input.orderId,
      receiptKey: receiptObjectName(input.orderId),
      totalCents,
    };
  },
});

export default createOrder;
```

This function declares the `prices` cache, so its handler receives `context.cache.prices`. Merely importing a
cache or putting it in the same domain does not grant access.

Event publication uses an explicit `publishes` list rather than `dependencies`:

```ts title="apps/docs/examples/events/create-order.function.ts"
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const createOrder = defineFunction({
  input: z.object({
    orderId: z.string().min(1),
    sku: z.string().min(1),
    quantity: z.number().int().positive(),
  }),
  output: z.object({
    orderId: z.string(),
    sku: z.string(),
    totalCents: z.number().int().nonnegative(),
  }),
  publishes: ["orders.created"],
  handler: async (input, context) => {
    const order = { orderId: input.orderId, sku: input.sku, totalCents: input.quantity * 100 };
    await context.events["orders.created"].publish(order);
    return order;
  },
});

export default createOrder;
```

The exact event ID becomes available under `context.events`; publishing any undeclared ID fails the checked edge.

## Know the common context

| Value                                          | Use it for                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------- |
| `invocation`                                   | ID, trace, correlation, source, attempt, timing, deadline, and service metadata |
| `signal`                                       | Cancelling work and passing cancellation to lower-level calls                   |
| `env`                                          | Values resolved by the application's typed environment contract                 |
| `log`                                          | Structured, invocation-correlated records                                       |
| `trace`                                        | Child spans, point-in-time events, and attributes on the active span            |
| `time`                                         | Testable `now()` and abort-aware `sleep()` behavior                             |
| `jobs`, `events`, `buckets`, `cache`, `agents` | Clients authorized by declarations on the function                              |
| `database`, `auth`, `constants`, `prompts`     | Registered application context supplied by specialized integrations             |

There is no service middleware or `context.service`. A service exposes public functions and events; it does not
inject handler state. Database and Auth are specialized application context integrations, documented in
[Database](/docs/modules/database) and [Auth sessions](/docs/modules/auth/sessions).

RELKIT traces routes, functions, declared clients, jobs, events, tools, and agents automatically. Use
`context.trace` only for application work the runtime cannot infer. See [Observability](/docs/modules/operations/observability#add-application-trace-detail)
for the three tracing operations and an executable example.

## Add access safely

1. ### Define and bind the capability

    Follow its guide and choose the integration profile in `relkit.config.ts`.

2. ### Declare the graph edge

    Add the descriptor under the matching `dependencies` key. For publication, add the exact event ID to
    `publishes`.

3. ### Verify the edge and fake

    ```sh title="Terminal — relkit-orders"
    bun run check
    bun run test
    ```

    Provider-backed unit and application tests should receive explicit deterministic fakes.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/functions` API](/docs/api/functions)

- [`examples/commerce/src/services/orders/functions/create-order.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/functions/create-order.function.ts)

---

# Environment contracts
Source: https://relkit.dev/docs/learn/concepts/environment

An environment contract turns process values, such as a log level or database URL, into validated application settings. Every process value starts as text; the contract parses it, applies intentional defaults, identifies
secrets, and controls the values available through `context.env`.

[defineEnv](/docs/api/config#defineenv) declares these settings in `src/platform/env.ts`.
The [env builders](/docs/api/config#env) describe each field. Pass the declaration to
[defineApp](/docs/api/app#defineapp) in `relkit.config.ts` to make it part of your application.
Declaring the contract does not read environment values; RELKIT resolves them when starting the runtime.

## Declare values with defineEnv [#define-application-values]

```ts title="templates/default/v1/api/src/platform/env.ts"
import { defineEnv, env } from "@relkit/app/config";

export default defineEnv({
  LOG_LEVEL: env.literal("trace", "debug", "info", "warn", "error").default("info"),
});
```

Builders such as `env.string()`, `env.url()`, `env.boolean()`, numeric variants, and `env.literal(...)` define
the accepted runtime value. Defaults are useful for harmless local policy such as log level. Credentials and
other required production values should fail clearly when absent instead of receiving placeholder defaults.

`env.secret()` marks a value as sensitive so generated output, diagnostics, telemetry, and Inspector payloads
can redact it. Secret marking is a safety boundary, not permission to log the value.

## Separate environment from binding references

The contract passed as `defineApp({ env })` resolves values available to application handlers. Integration
configuration also uses named binding references such as `binding.string(...)` and `binding.secret(...)`.
Those references describe runtime wiring for an adapter; they are not additional `context.env` fields unless
the application environment contract declares them too.

Use source-controlled configuration for stable topology and policy. Use environment values for machine-, stack-,
or secret-specific data. Never place resolved credentials in source, graphs, manifests, deployment plans, or
test snapshots.

## Inspect configuration safely

```sh title="Terminal — relkit-orders"
bun run relkit env check
bun run relkit env list
bun run relkit env explain LOG_LEVEL
bun run relkit env example
```

`check` validates the active values, `list` reports value status without printing secret contents, `explain`
describes one declaration, and `example` renders a safe template. Run `bun run check` after changing the contract
so generated types and graph metadata stay current.

Generated commands run under Bun, which loads its normal dotenv files for the process.
For one-shot and production commands, an existing process environment value takes precedence. `.env.example` is an informational
template; RELKIT does not load it as runtime configuration. Keep its placeholder values
separate from real credentials. Moving services leaves the root dotenv files in place.

During `bun dev`, RELKIT reloads active dotenv files for each candidate, including after a
failed reload. Keys declared in those files are managed by the files: additions and edits
replace startup values, and deleting a key removes its previous file-managed value. Other
inherited environment values and explicit RELKIT runtime settings remain in effect.

The startup `NODE_ENV` selects `.env.development`, `.env.production`, or `.env.test`, with
development as the fallback for an absent or custom value. `.env.local` has higher precedence
and is excluded in test mode. `.env.<mode>.local` has the highest file precedence.
Creating, deleting, or atomically replacing an active dotenv file also triggers a reload.
A rejected candidate leaves the previous valid version serving until the repair succeeds;
neither ordinary nor prepared startup requires restarting the CLI after a dotenv repair.

The CLI's `--environment` selects the command's provider environment. It does not turn a
custom application field named `RELKIT_ENV` into business configuration. RELKIT owns that
reserved runtime selector; the application contract continues to describe its own values.

> **Framework-owned variables**
>
> `PORT` and `RELKIT_ENV` are reserved. Configure the listener through `server.port` and select a
> provider environment with the CLI's `--environment` option. Do not declare either name as a custom
> environment field.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/config` API](/docs/api/config)

- [`templates/default/v1/api/src/platform/env.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/platform/env.ts)

---

# Declared errors
Source: https://relkit.dev/docs/learn/concepts/errors

Declare an error when callers need to handle an expected failure, such as an order that does not exist. An unexpected exception is a defect: RELKIT records it internally and returns a safe boundary failure
instead of exposing a stack or provider detail.

## Scaffold a typed error

From the application root, with an existing `orders` service:

```sh
bun run relkit add error receipt-rejected --service orders
```

Creates `src/services/orders/errors/receipt-rejected.error.ts` with `{ message: string }` data and
`retry: "never"`. It stays internal. Add it to the relevant function's `errors` list yourself;
a service bundle containing an error wires it to the bundle's example function automatically.

For every scaffolding flag, see the [error command reference](/docs/api/cli#relkit-add-error-name).

## Define a stable failure

```ts title="examples/commerce/src/services/orders/errors/order-not-found.error.ts"
/** Carries the missing order identity from lookup to an HTTP 404 with the established one-second retry hint. */
import { defineError } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const orderNotFound = defineError({
  id: "orders.not-found",
  data: z.object({
    /** Requested order identity preserved in the public failure message and payload. */
    orderId: z.string(),
  }),
  message: ({ orderId }) => `Order ${orderId} was not found`,
  http: { status: 404 },
  retry: { kind: "later", afterMs: 1_000 },
});

export default orderNotFound;
```

The `id` is the durable contract used by graphs, clients, traces, and matching. `data` limits the details callers
may receive. `http.status` contributes a typed HTTP response, while `retry` tells durable delivery whether another
attempt could help.

Register the descriptor in a function's `errors` list and throw the constructed declared value. Do not convert
every caught exception into a declared error; callers should depend only on failures the domain promises.

## Verify the public contract

The order lookup function uses the declared error when no record exists:

```ts title="examples/commerce/src/services/orders/functions/get-order.function.ts"
/** Emits lookup progress and returns the demonstration order or its declared order-not-found error. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import orderNotFound from "../errors/order-not-found.error.js";
import { orderLookupInput, orderLookupOutput } from "../../../platform/schemas.js";

const getOrder = defineFunction({
  input: orderLookupInput,
  output: orderLookupOutput,
  progress: z.object({
    stage: z.union([z.literal("lookup-started"), z.literal("lookup-completed")]),
  }),
  errors: [orderNotFound],
  handler: async (input, context) => {
    await context.progress.emit({ stage: "lookup-started" });
    if (input.orderId === "missing") return new orderNotFound(input);
    await context.progress.emit({ stage: "lookup-completed" });
    return { orderId: input.orderId, status: "confirmed", totalCents: 1_000 };
  },
});

export default getOrder;
```

```sh title="Terminal — relkit-orders"
bun run check
curl -i http://localhost:3000/orders/missing
```

Expect HTTP `404` with the stable error code and validated data. Tests should assert those fields and the status,
not a complete internal message or stack trace.

## Treat retry as bounded guidance

- `"never"` means the same operation should not be retried automatically.
- `"later"` allows a durable transport to use its normal backoff.
- `{ kind: "later", afterMs }` supplies a minimum delay; the integration may wait longer.

HTTP and direct invocation do not automatically retry. Jobs and event delivery apply their own bounded policies,
so a retryable error never means an unbounded loop. See [task retries](/docs/modules/jobs/retries-and-idempotency) and
[Event delivery](/docs/modules/events/consume) for transport behavior.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/functions` API](/docs/api/functions)

- [`examples/commerce/src/services/orders/errors/order-not-found.error.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/errors/order-not-found.error.ts)

---

# Functions
Source: https://relkit.dev/docs/learn/concepts/functions

A function contains a piece of application behavior, such as calculating a price or creating an order. It declares runtime input and output schemas,
expected errors, provider-backed dependencies, optional publication access, and one handler. Routes, jobs,
event consumers, tools, agents, and direct calls all enter the same invocation engine.

Functions remain request- or event-scoped operations. When work must outlive the initiating request, define a
[task](/docs/modules/jobs/tasks) and expose it through a [task-first job](/docs/modules/jobs/quickstart); do not turn a
function target into a durable worker by adding queue fields.

## Scaffold a callable function

With an existing `orders` service, run from the application root:

```sh
bun run relkit add function send-receipt --service orders
```

This creates `src/services/orders/functions/send-receipt.function.ts` and exposes `sendReceipt` through
`src/services/orders/service.ts`. The placeholder accepts and returns a string `value`; replace its schemas
and handler with your domain behavior. Its stable ID is `orders.send-receipt`.

Pass `--internal` to omit public service exposure. Use `--create-service orders` instead of
`--service orders` only if the domain does not exist. No test files are generated.

For every scaffolding flag, see the [function command reference](/docs/api/cli#relkit-add-function-name).

## Read a complete function

```ts title="templates/default/v1/api/src/services/orders/functions/create-order.function.ts"
/** Validates order input, invokes the service-local pricing function, and returns the calculated order. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import priceOrder from "@app/services/orders/functions/price-order.function.js";

const orderInput = z.object({
  orderId: z.string().min(1),
  sku: z.string().min(1),
  quantity: z.number().int().positive(),
});

const orderOutput = z.object({
  orderId: z.string(),
  sku: z.string(),
  totalCents: z.number().int().nonnegative(),
});

const createOrder = defineFunction({
  input: orderInput,
  output: orderOutput,

  handler: async (input) => {
    const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
    const order = {
      orderId: input.orderId,
      sku: input.sku,
      totalCents,
    };

    return order;
  },
});

export default createOrder;
```

The handler receives validated input. Its return value is validated before the invocation succeeds. The example
calls `priceOrder.invoke(...)`, so the nested operation keeps validation, deadlines, cancellation, tracing, and
causation. Calling another descriptor's handler directly bypasses that contract.

### Use this function from the frontend

Expose `createOrder` through its Orders service and a route. The API example maps that public
member to `POST /orders`:

```ts title="src/routes/orders/route.ts — backend"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineServiceRoutes } from "@relkit/app/routes";
import orders from "@app/services/orders/service.js";

export const { POST } = defineServiceRoutes(orders, {
  POST: { member: "createOrder", successStatus: 201 },
});
```

After [frontend setup and pulling this API example's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`:

```tsx title="src/CreateOrder.tsx — frontend"
"use client";

/** Calls the API example's Orders function through its public route, retaining the generated input and price result. */
import { useRelkitClient, useRouteMutation } from "@relkit/client/react";

/** Creates one order in the API example without importing the backend service.
 * @returns A guarded submission action and its typed price or failure. */
export function CreateOrder() {
  const { status } = useRelkitClient();
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() => create.mutate({ orderId: crypto.randomUUID(), sku: "book", quantity: 2 })}
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Total: {create.data.totalCents} cents</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

This calls the same `createOrder` function through `POST /orders`: `orderId`, `sku`, and `quantity`
come from its input schema, and `totalCents` comes from its output schema. The browser calls RPC;
it never imports the descriptor or calls `.invoke()`. Service membership needs a client-exposed
route to become a browser operation.

Reference: [`useRouteMutation`](/docs/api/client#useroutemutation).
Continue with [mutation state and recovery](/docs/modules/client/mutations).

## Define the boundary

### Start with input and output

Put a schema beside its only consumer, or in the owning domain when several descriptors share it. Keep
transport fields such as cookies and raw headers in the route unless they are genuine domain input.

### Declare failures and capabilities

List only errors callers are expected to handle. Declare only the jobs, buckets, caches, and agents the
handler uses. Event publication is separate: list exact event IDs in `publishes`.

### Implement transport-independent behavior

Use the supplied context, honor its abort signal, and return the declared output. Let unexpected defects
cross RELKIT's safe boundary rather than converting them into unstable public errors.

### Hooks and transport policy

`onBefore` transforms validated input before the handler. `onAfter` transforms successful output before final
output validation. Use hooks only for function policy that must apply to every invocation source; use HTTP
middleware for request-native policy.

## Test the operation directly

```ts title="templates/default/v1/api/tests/unit/orders.function.test.ts"
/** Checks orders.function through the supported public RELKIT APIs. */
import { expect, test } from "bun:test";
import { invokeFunction } from "@relkit/testing";
import orders from "@app/services/orders/service.js";

test("createOrder invokes pricing", async () => {
  const result = await invokeFunction(orders.createOrder, {
    orderId: "order-1",
    sku: "book",
    quantity: 3,
  });

  expect(result).toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
});
```

```sh title="Terminal — relkit-orders"
bun test tests/unit/orders.function.test.ts
```

`invokeFunction` runs the descriptor through an isolated engine. A function that needs provider clients receives
explicit test fakes; tests do not infer production replacements from `RELKIT_ENV`.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/functions` API](/docs/api/functions)

- [`templates/default/v1/api/src/services/orders/functions/create-order.function.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/services/orders/functions/create-order.function.ts)

---

# Runtime schemas
Source: https://relkit.dev/docs/learn/concepts/schemas

A schema checks whether a value has the shape your application accepts, including when that value arrives over HTTP. RELKIT schemas stay executable, so functions, routes, jobs, events,
caches, tools, generated OpenAPI, and clients can share one contract. Treat values arriving from a caller,
transport, persisted payload, or provider as unknown until a schema accepts them.

## Model domain values

```ts title="examples/commerce/src/platform/schemas.ts"
import { z } from "@relkit/app/schema";

export const orderInput = z.object({
  orderId: z.string().min(1),
  sku: z.string().min(1),
  quantity: z.number().int().positive(),
  customerEmail: z.string().email(),
});

export const createOrderOutput = z.object({
  orderId: z.string(),
  receiptKey: z.string(),
  totalCents: z.number().int().nonnegative(),
});

export const orderLookupInput = z.object({ orderId: z.string().min(1) });

export const orderLookupOutput = z.object({
  orderId: z.string(),
  status: z.string(),
  totalCents: z.number().int().nonnegative(),
});

export const orderMutationInput = z.object({
  orderId: z.string().min(1),
  state: z.string().min(1),
});
export const orderDeleteInput = z.object({
  orderId: z.string().min(1),
  reason: z.string().optional(),
});
export const orderDeleteOutput = z.object({ orderId: z.string(), deleted: z.boolean() });
export const orderSearchInput = z.object({ status: z.string().optional() });
export const orderSearchOutput = z.object({ status: z.string(), count: z.number().int() });

export const pathInput = z.object({ parts: z.array(z.string()).optional() });
export const pathOutput = z.object({ path: z.string() });

export const receiptInput = z.object({
  orderId: z.string(),
  receiptKey: z.string(),
});

export const receiptOutput = z.object({ receiptId: z.string() });

export const authorizationInput = z.object({ authorization: z.string() });
export const authorizationOutput = z.object({ allowed: z.boolean() });

export const supportInput = z.object({ message: z.string().min(1) });
export const supportOutput = z.object({ answer: z.string() });
```

Describe what the domain accepts: non-empty identifiers, integer and range constraints, closed literals, and
named object fields. Optional means a caller may omit a value; a default means omission resolves to a value.
Those contracts are different.

Keep a schema beside one descriptor when it is private. Move it into the owning domain only when several
descriptors intentionally share the same value.

## Let descriptors enforce the boundary

A function validates `input` before its handler and validates `output` before completion. An invalid caller value
is a boundary error; an invalid function result is an application defect because the handler broke its declared
contract. Routes map safe input failures to HTTP responses without running business side effects.

```sh title="Terminal — relkit-orders"
curl -i -X POST http://localhost:3000/orders \
  -H "content-type: application/json" \
  -d '{"orderId":"order-1","sku":"book","quantity":0}'
```

Expect HTTP `422` for the invalid positive quantity. Do not parse the same value again inside the handler;
duplicate validation creates extra work and can produce different errors for the same contract.

## Evolve persisted contracts carefully

Adding an optional input is often compatible; making it required is not. Removing an output field can break a
generated client. Event and durable-job payloads may outlive the release that wrote them, so test a representative
older payload and version a contract when producers and consumers cannot change together.

Run the graph and behavior checks after a schema change:

```sh title="Terminal — relkit-orders"
bun run check
bun run typecheck
bun run test
```

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/schema` API](/docs/api/schema)

- [`examples/commerce/src/platform/schemas.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/platform/schemas.ts)

---

# Create and run an API
Source: https://relkit.dev/docs/learn/create-an-app

Start a RELKIT application and send it an HTTP request. You'll use this application throughout the Orders tutorial.

> **Before you begin**
>
> Before you begin, install **Bun 1.3.10 or later**.

1. ## 1. Create the application [#create-the-project]

    Run these commands in the directory where you want your project. Choose **Minimal**, keep **None** for jobs, accept the suggested destination, and confirm creation:

    ```sh title="Terminal — parent directory"
    bunx create-relkit@latest relkit-orders
    cd relkit-orders
    cp .env.example .env
    ```

    The default is the certified `minimal` template. The generator installs its dependencies and checks the application. Run the remaining commands from `relkit-orders`.

2. ## 2. Start the server [#run-it-and-make-a-request]

    ```sh title="Terminal — relkit-orders"
    bun run dev
    ```

    Keep this terminal running. The server normally listens on `http://localhost:3000`.

3. ## 3. Send a request

    Open a second terminal and send:

    ```sh title="Second terminal"
    curl -i http://localhost:3000/hello\?name=RELKIT
    ```

    You should receive HTTP `200` and this response:

    ```json
    { "message": "Hello, RELKIT!" }
    ```

    Your application is responding to HTTP requests. Next, you'll **[add an endpoint that creates an order](/docs/learn/first-route)**.

## What the starter gave you

A **route** connects an HTTP method and path to application behavior. The starter's `GET /hello` route calls a function that creates the greeting.

- `src/routes/hello/route.ts` defines the route.
- `src/services/hello/functions/` contains the greeting function.
- `src/services/hello/service.ts` exposes that function through the Hello service.
- `relkit.config.ts` configures the application.

You edit these TypeScript files. RELKIT writes derived output to `.relkit/generated`.

## If a step fails

Run `bun run check` in the application directory and read its first diagnostic. If port `3000` is already in use, set another `PORT` in `.env` and use that port in your request.

The first application needs no database or cloud credentials. [Creation options](/docs/modules/cli/create-an-app) covers installation controlled by another tool, Git settings, and generator choices. Inspection is disabled by default. The [Inspector](/docs/modules/operations/inspector) is available as a separate, optional tool.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/config` API](/docs/api/config)

- [`templates/default/v1/api/README.md`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/README.md)

---

# Add an Orders endpoint
Source: https://relkit.dev/docs/learn/first-route

Add `POST /orders` to the application from [Create and run an API](/docs/learn/create-an-app).
You'll calculate an order's price, change the bulk-price rule, and check that invalid quantities are rejected.

> **Before you begin**
>
> Keep `bun run dev` running in the same `relkit-orders` directory. Use a second terminal for
> requests.

1. ## 1. Add the Orders domain [#add-the-orders-domain]

    From the application root, scaffold the two functions and their service:

    ```sh title="Second terminal — relkit-orders"
    bun run relkit add function price-order --create-service orders
    bun run relkit add function create-order --service orders
    ```

    The first command creates `src/services/orders/service.ts` and
    `functions/price-order.function.ts` beneath that service. The second adds
    `functions/create-order.function.ts` and exposes `createOrder` through `service.ts`.
    Both functions start with placeholder schemas and handlers.

    Replace the generated files with the examples below. If you prefer to create files manually,
    add the same paths and contents instead of running these commands. If a file already exists,
    edit it; `relkit add` does not overwrite it.

    A **function** contains application behavior. Its input and output **schemas** describe which values
    the function accepts and returns. Start with the function that calculates a price:

    ```ts title="src/services/orders/functions/price-order.function.ts"
    /** Calculates integer order totals at 100 cents per item for the create-order function. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const priceOrder = defineFunction({
      input: z.object({ quantity: z.number().int().positive() }),
      output: z.object({ totalCents: z.number().int().nonnegative() }),
      handler: ({ quantity }) => ({ totalCents: quantity * 100 }),
    });

    export default priceOrder;
    ```

    ```ts title="src/services/orders/functions/create-order.function.ts"
    /** Validates order input, invokes the service-local pricing function, and returns the calculated order. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    const orderInput = z.object({
      orderId: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
    });

    const orderOutput = z.object({
      orderId: z.string(),
      sku: z.string(),
      totalCents: z.number().int().nonnegative(),
    });

    const createOrder = defineFunction({
      input: orderInput,
      output: orderOutput,

      handler: async (input) => {
        const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
        const order = {
          orderId: input.orderId,
          sku: input.sku,
          totalCents,
        };

        return order;
      },
    });

    export default createOrder;
    ```

    A **service** exposes the functions other parts of your application can call. Check that the
    generated Orders service matches this source:

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import createOrder from "@app/services/orders/functions/create-order.function.js";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    export default defineService({
      functions: { createOrder, priceOrder },
    });
    ```

    Now scaffold the HTTP route. `--map POST=createOrder` selects the public service member:

    ```sh title="Second terminal — relkit-orders"
    bun run relkit add route /orders \
      --mode service-route --service orders --map POST=createOrder
    ```

    This creates `src/routes/orders/route.ts` with `defineServiceRoutes`. Replace it with the source
    below to return HTTP `201` when an order is created; the scaffold's shorthand uses HTTP `200`.

    ```ts title="src/routes/orders/route.ts"
    /** Maps the HTTP endpoint to its owning service's public member. */
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { POST } = defineServiceRoutes(orders, {
      POST: { member: "createOrder", successStatus: 201 },
    });
    ```

    The running development session validates the new source and activates it only after the generated
    route returns the expected response.

    The [CLI module](/docs/modules/cli/add-artifacts) explains service selection and other artifacts.
    Use the [function command reference](/docs/api/cli#relkit-add-function-name) and
    [route command reference](/docs/api/cli#relkit-add-route-path) for all options.

2. ## 2. Follow the request [#follow-the-request]

    The path and HTTP method come from `src/routes/orders/route.ts`. The route selects the public
    `createOrder` operation and returns `201` after it succeeds. The service exposes `createOrder` and
    `priceOrder` from the Orders domain.

    `createOrder` validates `orderId`, `sku`, and a positive integer `quantity`, then invokes `priceOrder`.
    That function owns the price rule. The route stays small so the same behavior can serve other callers.

    ```text
    POST /orders → route → Orders service → createOrder → priceOrder → validated JSON
    ```

3. ## 3. Change one rule [#change-one-rule]

    Open `src/services/orders/functions/price-order.function.ts`. Replace its handler with the
    source below. Orders of 10 or more units now cost 90 cents each; smaller orders still cost 100 cents
    each. The input and output schemas remain unchanged.

    ```ts title="src/services/orders/functions/price-order.function.ts"
    /** Calculates tutorial totals at 100 cents per item, applying the 90-cent bulk price from ten items onward. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const priceOrder = defineFunction({
      input: z.object({ quantity: z.number().int().positive() }),
      output: z.object({ totalCents: z.number().int().nonnegative() }),
      handler: ({ quantity }) => ({ totalCents: quantity * (quantity >= 10 ? 90 : 100) }),
    });

    export default priceOrder;
    ```

    The development server checks and reloads this source. Verify the changed price:

    ```sh title="Second terminal — relkit-orders"
    curl -i -X POST http://localhost:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"bulk-1","sku":"book","quantity":10}'
    ```

    Expect HTTP `201` and `totalCents: 900`. Then send an invalid quantity:

    ```sh title="Second terminal — relkit-orders"
    curl -i -X POST http://localhost:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"bad-1","sku":"book","quantity":0}'
    ```

    Expect a validation response, not an order. Run `bun run check` and `bun run typecheck` after the
    change. `check` verifies the discovered route and function contracts; typecheck verifies TypeScript.

    The response still disappears after each request because this chapter has no database.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/routes` API](/docs/api/routes)

- [`templates/default/v1/api/src/routes/orders/route.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/routes/orders/route.ts)

---

# Develop locally
Source: https://relkit.dev/docs/learn/local-development

Continue in the tested `relkit-orders` app from [Test the Orders API](/docs/learn/test-orders).
Keep the same SQLite file and authentication environment. This chapter deliberately makes one
temporary source error, repairs it, and checks the active app.

1. ## 1. Know the local surfaces [#know-the-local-surfaces]

    | Surface                 | Default address                                 | What it shows                                      |
    | ----------------------- | ----------------------------------------------- | -------------------------------------------------- |
    | Backend                 | `http://localhost:3000`                         | Your Orders routes                                 |
    | Optional Inspector tool | `http://localhost:3210`                         | Functions, routes, requests, logs, and diagnostics |
    | HTTP contract           | `http://localhost:3000/_relkit/v1/openapi.json` | Generated endpoint contracts                       |
    | Readiness               | `http://localhost:3000/_relkit/v1/health/ready` | Whether the active generation can serve            |

    If you want the optional UI, complete [Inspector installation, bridge enablement and independent launch](/docs/modules/operations/inspector).
    `bun run dev` starts the backend; the separate tool provides the optional UI and history. You can
    check readiness, routes and JSON OpenAPI below without the tool.

    With both processes running, open the tool's UI. Choose **Routes**, then `POST /orders` to see the
    public function it targets. Open **Functions** and find the Orders pricing and creation
    operations. The inspector shows the checked application, not a second configuration to edit.

    On an unchanged installed project, development reuses a prepared snapshot only after checking its
    complete source, generated graph, dependency, and tool identities. A missing, stale, corrupt, or
    ineligible snapshot returns to the normal full validation path; it never weakens candidate health or
    last-known-good switching. Run `bunx --no-install relkit dev --prepare` when you want to perform that
    finite validation ahead of the interactive session.

    Backend readiness is independent of the Inspector. Explicit `inspector.enabled` starts only the private
    authenticated bridge on `127.0.0.1:0`; it installs or launches no UI or history store. The standalone
    tool owns port 3210 and persistent history. Stopping it leaves the backend serving, while bounded
    bridge capture may report gaps until a collector reconnects.

    The commerce demo below shows the same **Routes** navigation item and **Open route** action
    you will use in your app:

    ![Inspector Routes page with Orders routes and Open route controls](/inspector-light.png)

2. ## 2. See a failed reload safely [#see-a-failed-reload-safely]

    In `src/routes/orders/route.ts`, temporarily misspell `defineServiceRoutes` and save. The
    development terminal reports a source diagnostic. The last valid generation remains active;
    a new broken candidate does not replace it. Restore the spelling and save again.

    Check readiness and the protected route after the repaired generation activates:

    ```sh title="Second terminal — relkit-orders"
    curl -i http://localhost:3000/_relkit/v1/health/ready
    curl -i http://localhost:3000/orders/private-1
    ```

    Expect readiness success and `401` for the signed-out Orders request. If the app did not
    reactivate, run `bun run check` and fix its first diagnostic. The last valid generation can
    serve requests while a changed candidate is invalid, but an initial startup failure has no
    previous generation to keep serving.

3. ## 3. Inspect the generated contract [#inspect-the-generated-contract]

    Open the HTTP contract above and find `POST /orders` and `GET /orders/{orderId}`. For an interactive
    reference, [explicitly select Scalar](/docs/modules/http/openapi). Compare
    their methods, paths, and request shapes with the source. The checked graph and OpenAPI files
    under `.relkit/generated` are useful for diagnosis; repair source, then rerun `check`.

    ### Verify changes

    `bun run check`, `bun run typecheck`, and `bun run test` cover different concerns: graph
    relationships, TypeScript types, and behavior.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/routes` API](/docs/api/routes)

- [`templates/default/v1/api/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/relkit.config.ts)

---

# Protect your orders
Source: https://relkit.dev/docs/learn/protect-orders

This chapter extends the same SQLite-backed `relkit-orders` app. You will add a local Better Auth
service, then require a session for both Orders routes. A caller cannot choose an order owner in
request JSON; the server gets that identity from the session. Stop `bun run dev` before migrating.

1. ## 1. Add authentication to the existing database [#add-authentication-to-the-existing-database]

    The auth scaffold installs Better Auth and creates its service and `/api/auth` route. It reuses
    the database service already in the app. It does not apply a migration or create a secret.

    ```sh title="Terminal — relkit-orders"
    bun run relkit add auth --adapter better-auth --database-dialect sqlite
    ```

    This includes the native SDK, development declaration peers and selected repairs. If you pass
    `--no-install`, finish with `bun install` and `bun run check` before continuing. The
    [manual auth setup](/docs/modules/auth/better-auth) is an alternative, not another required installation.

    Application HTTP fixtures must now import `createTestApplication` from
    `@relkit/testing/better-auth`, including the existing Hello test. The native helper activates both
    auth and its database; see [the complete updated fixtures](/docs/learn/test-orders).

    **Extend** `src/services/database/schema/index.ts` with the auth tables. The complete source below
    retains `orders` and adds the `user`, `session`, `account`, and `verification` exports Better Auth
    requires. Do not replace an existing business table when adapting this to your own application.

    ```ts title="src/services/database/schema/index.ts"
    /** Registers tutorial order ownership columns alongside native Better Auth user/session/account/verification tables. */
    import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";

    export const orders = sqliteTable("orders", {
      orderId: text().primaryKey(),
      sku: text().notNull(),
      quantity: integer().notNull(),
      totalCents: integer().notNull(),
      ownerId: text(),
    });

    const timestamps = {
      createdAt: integer({ mode: "timestamp" }).notNull(),
      updatedAt: integer({ mode: "timestamp" }).notNull(),
    };
    export const user = sqliteTable("user", {
      id: text().primaryKey(),
      name: text().notNull(),
      email: text().notNull().unique(),
      emailVerified: integer({ mode: "boolean" }).notNull(),
      image: text(),
      ...timestamps,
    });

    export const session = sqliteTable("session", {
      id: text().primaryKey(),
      expiresAt: integer({ mode: "timestamp" }).notNull(),
      token: text().notNull().unique(),
      ipAddress: text(),
      userAgent: text(),
      userId: text().notNull(),
      ...timestamps,
    });

    export const account = sqliteTable(
      "account",
      {
        id: text().primaryKey(),
        accountId: text().notNull(),
        issuer: text().notNull(),
        providerId: text().notNull(),
        userId: text().notNull(),
        accessToken: text(),
        refreshToken: text(),
        idToken: text(),
        accessTokenExpiresAt: integer({ mode: "timestamp" }),
        refreshTokenExpiresAt: integer({ mode: "timestamp" }),
        scope: text(),
        password: text(),
        ...timestamps,
      },
      (table) => [uniqueIndex("account_issuer_account_id").on(table.issuer, table.accountId)],
    );

    export const verification = sqliteTable("verification", {
      id: text().primaryKey(),
      identifier: text().notNull(),
      value: text().notNull(),
      expiresAt: integer({ mode: "timestamp" }).notNull(),
      ...timestamps,
    });
    ```

    Replace `src/platform/env.ts` with the existing fields plus the auth secret and base URL:

    ```ts title="src/platform/env.ts"
    import { defineEnv, env } from "@relkit/app/config";

    export default defineEnv({
      LOG_LEVEL: env.literal("trace", "debug", "info", "warn", "error").default("info"),
      DATABASE_PATH: env.string().default("./orders.sqlite"),
      BETTER_AUTH_SECRET: env.secret(),
      BETTER_AUTH_URL: env.url().default(new URL("http://127.0.0.1:3000")),
    });
    ```

    Set a stable local secret in the terminal that starts the app, then append it to the ignored
    `.env` for later restarts. Never commit that file.

    ```sh title="Terminal — relkit-orders"
    export DATABASE_PATH=./orders.sqlite
    export BETTER_AUTH_URL=http://127.0.0.1:3000
    export BETTER_AUTH_SECRET="$(openssl rand -base64 32)"
    printf 'BETTER_AUTH_URL=%s\nBETTER_AUTH_SECRET=%s\n' \
      "$BETTER_AUTH_URL" "$BETTER_AUTH_SECRET" >> .env
    ```

    Review `src/services/auth/service.ts` and make it match the email/password configuration below:

    ```ts title="src/services/auth/service.ts"
    /** Declares email/password Better Auth using the configured URL and the sole database owner's native tables. */
    import { defineBetterAuthService } from "@relkit/better-auth";

    export default defineBetterAuthService({
      baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
      emailAndPassword: { enabled: true },
    });
    ```

    The auth mount handles `/api/auth` and rejects signed-out calls to both `/orders` and
    `/orders/*`. Replace the scaffolded route with:

    ```ts title="src/routes/api/auth/[[...auth]]/route.ts"
    /** Mounts native Better Auth once for all methods and protects both root and descendant order routes. */
    import { defineRoute } from "@relkit/app/routes";
    import auth from "@app/services/auth/service.js";

    export const ALL = defineRoute({
      handler: auth.handler,
      auth: { protected: ["/orders", "/orders/*"] },
    });
    ```

    Generate a second migration and inspect its SQL before applying it. This keeps the existing
    Orders table and adds auth tables; do not regenerate the initial migration.

    ```sh title="Terminal — relkit-orders"
    bun --bun drizzle-kit generate --name=auth
    bun run relkit db migrate
    bun run check
    ```

2. ## 2. Associate orders with the signed-in user [#associate-orders-with-the-signed-in-user]

    Replace the two Orders functions below. `createOrder` obtains the user ID from the session
    and stores it with the row. `getOrder` matches both `orderId` and the session's user ID;
    someone else's order returns `found: false`.

    ```ts title="src/services/orders/functions/create-order.function.ts"
    /** Prices validated order input and persists it with the authenticated session user's ownership. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";
    const order = z.object({
      orderId: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
    });
    export default defineFunction({
      input: order,
      output: z.object({
        orderId: z.string(),
        sku: z.string(),
        quantity: z.number().int().positive(),
        totalCents: z.number().int().nonnegative(),
      }),
      handler: async (input, context) => {
        const session = await context.auth.getSession();
        if (session === null) throw new Error("Authentication required");
        const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
        const saved = await context.database.orders.insert({
          data: { ...input, totalCents, ownerId: session.user.id },
        });
        return {
          orderId: saved.orderId,
          sku: saved.sku,
          quantity: saved.quantity,
          totalCents: saved.totalCents,
        };
      },
    });
    ```

    ```ts title="src/services/orders/functions/get-order.function.ts"
    /** Reads a validated order ID only within the authenticated user's ownership and returns a concealed missing result otherwise. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    export default defineFunction({
      input: z.object({ orderId: z.string().min(1) }),
      output: z.object({
        found: z.boolean(),
        order: z
          .object({
            orderId: z.string(),
            sku: z.string(),
            quantity: z.number(),
            totalCents: z.number(),
          })
          .optional(),
      }),
      handler: async ({ orderId }, context) => {
        const session = await context.auth.getSession();
        if (session === null) throw new Error("Authentication required");
        const row = await context.database.orders.findOne({
          where: { orderId, ownerId: session.user.id },
        });
        return row === null
          ? { found: false }
          : {
              found: true,
              order: {
                orderId: row.orderId,
                sku: row.sku,
                quantity: row.quantity,
                totalCents: row.totalCents,
              },
            };
      },
    });
    ```

    ```text
    request cookie → session → user ID → Orders query → owner-matching row
    ```

    Rows created in the previous chapter have no owner. These protected reads do not reveal them to
    new accounts; this tutorial does not guess who owned an anonymous order.

3. ## 3. Sign in and verify access [#sign-in-and-verify-access]

    Run `bun run typecheck` and `bun run dev` in the terminal with the auth environment set. In
    another terminal, first call `GET /orders/saved-1` without a cookie; expect HTTP `401`.
    Then create a local account and save its cookie:

    ```sh title="Second terminal — relkit-orders"
    auth_cookies=$(mktemp -t relkit-orders-cookies)
    curl -i -c "$auth_cookies" http://127.0.0.1:3000/api/auth/sign-up/email \
      -H 'content-type: application/json' -H 'origin: http://127.0.0.1:3000' \
      --data '{"name":"Demo","email":"demo@example.com","password":"local-demo-password-123"}'
    curl -i -b "$auth_cookies" -X POST http://127.0.0.1:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"private-1","sku":"book","quantity":3}'
    curl -b "$auth_cookies" http://127.0.0.1:3000/orders/private-1
    ```

    Expect sign-up and POST success, followed by `found: true`. A different signed-in account
    receives `found: false` for `private-1`.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/auth-drizzle/src/services/auth/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/auth/service.ts)

---

# Save and retrieve orders
Source: https://relkit.dev/docs/learn/save-orders

The Orders route from [the previous chapter](/docs/learn/first-route) only calculates a response.
Here you will store that result in SQLite and add `GET /orders/:orderId`. Stop `bun run dev`
before changing the database. Keep working in the same `relkit-orders` application.

1. ## 1. Add the local database [#add-the-local-database]

    Scaffold the supported Drizzle service. This installs the compatible packages and creates an
    `items` placeholder. **Replace** that placeholder with the Orders schema below; do not keep both.

    ```sh title="Terminal — relkit-orders"
    bun run relkit add database --orm drizzle --dialect sqlite
    ```

    This also installs Drizzle Kit and registers the release-owned Drizzle declaration repair. If you
    pass `--no-install`, complete `bun install` and `bun run check` before the next step. For a manual
    alternative, follow [database installation](/docs/modules/database/define); do not run both setup paths.

    Replace `src/services/database/schema/index.ts` with one Orders table. `orderId` is the unique key;
    `ownerId` is empty until the next chapter adds sign-in. Existing anonymous demonstration orders
    will not become anyone's private orders automatically.

    ```ts title="src/services/database/schema/index.ts"
    /** Declares the tutorial's SQLite order identity, quantity, price and optional ownership columns for native registration. */
    import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

    export const orders = sqliteTable("orders", {
      orderId: text().primaryKey(),
      sku: text().notNull(),
      quantity: integer().notNull(),
      totalCents: integer().notNull(),
      ownerId: text(),
    });
    ```

    Use Bun's SQLite driver in `src/services/database/service.ts`. Replace the scaffolded service with:

    ```ts title="src/services/database/service.ts"
    /** Lazily opens the configured SQLite database, registers tutorial tables and closes its owned client on disposal. */
    import { Database } from "bun:sqlite";
    import { defineDrizzleService } from "@relkit/drizzle";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import * as schema from "./schema/index.js";

    export default defineDrizzleService({
      schema,
      client: ({ env }) => drizzle({ client: new Database(env.DATABASE_PATH) }),
      dispose: (database) => database.$client.close(),
    });
    ```

    Replace `src/platform/env.ts` to keep the existing log-level setting and add the SQLite file path:

    ```ts title="src/platform/env.ts"
    import { defineEnv, env } from "@relkit/app/config";

    export default defineEnv({
      LOG_LEVEL: env.literal("trace", "debug", "info", "warn", "error").default("info"),
      DATABASE_PATH: env.string().default("./orders.sqlite"),
    });
    ```

    Update `tsconfig.json` so TypeScript loads the context registry produced by `relkit check`.
    Keep the starter's `@app/*` alias; the complete config below adds the generated declaration
    and includes the migration script.

    ```json title="tsconfig.json"
    {
      "$schema": "https://json.schemastore.org/tsconfig",
      "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "moduleResolution": "Bundler",
        "baseUrl": ".",
        "paths": { "@app/*": ["src/*"] },
        "lib": ["ES2022"],
        "types": ["bun"],
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "exactOptionalPropertyTypes": true,
        "verbatimModuleSyntax": true,
        "isolatedModules": true,
        "noEmit": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true
      },
      "files": [".relkit/generated/context-registry.d.ts"],
      "include": [
        "src/**/*.ts",
        "tests/**/*.ts",
        "scripts/**/*.ts",
        "drizzle.config.ts",
        "relkit.config.ts"
      ],
      "exclude": ["node_modules", ".relkit"]
    }
    ```

    Add the SQLite path to the ignored `.env` file, preserving its existing settings. The same path will be loaded when you
    restart the app or run the production build. Keep the database out of source control too.

    ```sh title="Terminal — relkit-orders"
    printf '\nDATABASE_PATH=./orders.sqlite\n' >> .env
    printf '\norders.sqlite\n' >> .gitignore
    ```

2. ## 2. Save an order [#save-an-order]

    The existing `createOrder` function already validates input and calls `priceOrder`. Replace
    `src/services/orders/functions/create-order.function.ts` so it inserts the calculated result into the
    Orders table. The response now includes the original `quantity` as well as the price.

    ```ts title="src/services/orders/functions/create-order.function.ts"
    /** Prices validated order input and persists its selected fields through the tutorial's native database context. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";
    const order = z.object({
      orderId: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
    });
    export default defineFunction({
      input: order,
      output: z.object({
        orderId: z.string(),
        sku: z.string(),
        quantity: z.number().int().positive(),
        totalCents: z.number().int().nonnegative(),
      }),
      handler: async (input, context) => {
        const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
        const saved = await context.database.orders.insert({
          data: { ...input, totalCents, ownerId: null },
        });
        return {
          orderId: saved.orderId,
          sku: saved.sku,
          quantity: saved.quantity,
          totalCents: saved.totalCents,
        };
      },
    });
    ```

3. ## 3. Add a read operation [#add-a-read-operation]

    From the application root, scaffold the read function:

    ```sh title="Terminal — relkit-orders"
    bun run relkit add function get-order --service orders
    ```

    This creates `src/services/orders/functions/get-order.function.ts` and exposes `getOrder` through
    the service. Replace its placeholder with the lookup below. It returns `found: false` when there
    is no row, so callers receive no fabricated order. For manual setup, create the same file instead.

    ```ts title="src/services/orders/functions/get-order.function.ts"
    /** Reads the requested database order and returns validated selected fields or an explicit missing result. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    export default defineFunction({
      input: z.object({ orderId: z.string().min(1) }),
      output: z.object({
        found: z.boolean(),
        order: z
          .object({
            orderId: z.string(),
            sku: z.string(),
            quantity: z.number(),
            totalCents: z.number(),
          })
          .optional(),
      }),
      handler: async ({ orderId }, context) => {
        const row = await context.database.orders.findOne({ where: { orderId } });
        return row === null
          ? { found: false }
          : {
              found: true,
              order: {
                orderId: row.orderId,
                sku: row.sku,
                quantity: row.quantity,
                totalCents: row.totalCents,
              },
            };
      },
    });
    ```

    Replace `src/services/orders/service.ts` to expose that operation alongside the existing two functions:

    ```ts title="src/services/orders/service.ts"
    /** Exposes tutorial creation, lookup and pricing functions through the immediate orders service boundary. */
    import { defineService } from "@relkit/app/services";
    import createOrder from "@app/services/orders/functions/create-order.function.js";
    import getOrder from "@app/services/orders/functions/get-order.function.js";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    export default defineService({ functions: { createOrder, getOrder, priceOrder } });
    ```

    Scaffold the read route after updating the function and service:

    ```sh title="Terminal — relkit-orders"
    bun run relkit add route /orders/:orderId \
      --mode service-route --service orders --map GET=getOrder
    ```

    This creates `src/routes/orders/[orderId]/route.ts`. Its directory supplies the URL parameter;
    the named `GET` export selects the public `getOrder` member. The generated shorthand and the
    explicit mapping below select the same operation; use this source to match the tutorial:

    ```ts title="src/routes/orders/[orderId]/route.ts"
    /** Maps the order GET route to its service lookup member with inferred path input and validated response. */
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { GET } = defineServiceRoutes(orders, { GET: { member: "getOrder" } });
    ```

4. ## 4. Keep existing HTTP tests compatible [#keep-existing-http-tests-compatible]

    Application test fixtures load the app's declared services, even when a test only calls `/hello`.
    After adding the database, replace the starter's generic `createTestApplication` import with
    `@relkit/testing/drizzle` in every application fixture. Keep `invokeFunction` unit tests on the
    generic helper when they inject their own dependencies.

    Update the existing Hello HTTP test:

    ```ts title="tests/integration/hello.route.test.ts"
    /** Keeps the starter's Hello HTTP coverage after the application selects a native Drizzle service. */
    import { afterAll, expect, test } from "bun:test";
    import { createTestApplication } from "@relkit/testing/drizzle";
    import config from "../../relkit.config.js";

    const testApp = await createTestApplication(config);

    test("GET /hello", async () => {
      const response = await testApp.http.get("/hello?name=Mustafa");
      expect(response.status).toBe(200);
      expect(await response.json()).toEqual({ message: "Hello, Mustafa!" });
    });

    afterAll(() => testApp.close());
    ```

5. ## 5. Migrate, run, and check [#migrate-run-and-check]

    Replace the scaffolded `drizzle.config.ts` with this configuration. It refuses an unset or
    in-memory path so the migration cannot quietly target the wrong database.

    ```ts title="drizzle.config.ts"
    /** Configures native tutorial schema migrations against grouped order tables and an explicitly selected SQLite file. */
    import { defineConfig } from "drizzle-kit";

    const path = process.env.DATABASE_PATH;
    if (path === undefined || path.trim() === "" || path === ":memory:") {
      throw new Error("Set DATABASE_PATH to the SQLite file you intend to migrate");
    }

    export default defineConfig({
      schema: "./src/services/database/schema/index.ts",
      dialect: "sqlite",
      out: "./src/services/database/migrations",
      dbCredentials: { url: path },
    });
    ```

    Generate and review the initial SQL migration, then apply it and start the app:

    Use installed RELKIT migration tooling, which selects the Bun-native SQLite driver.
    Keep generated SQL and required metadata tracked beside the database service in
    `src/services/database/migrations`; do not copy runner code into the application.

    ```sh title="Terminal — relkit-orders"
    export DATABASE_PATH=./orders.sqlite
    bun --bun drizzle-kit generate --name=initial
    bun run relkit db migrate
    bun run check
    bun run typecheck
    bun run dev
    ```

    In another terminal, submit a new order and read it back:

    ```sh title="Second terminal — relkit-orders"
    curl -i -X POST http://localhost:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"saved-1","sku":"book","quantity":10}'
    curl http://localhost:3000/orders/saved-1
    ```

    Expect HTTP `201` with `totalCents: 900`; the GET response has `found: true` and the same
    order. Restart `bun run dev` and repeat the GET: the result remains. Use a new `orderId` for
    another POST because the database enforces uniqueness.

    This chapter's API has no access control yet.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/data-model/src/services/database/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/service.ts)

---

# Test the Orders API
Source: https://relkit.dev/docs/learn/test-orders

This chapter tests the `relkit-orders` app from [Protect your orders](/docs/learn/protect-orders).
It needs the auth migration generated in that chapter. Tests create an isolated SQLite file and
two accounts, so they do not alter the database used by `bun run dev`.

The minimal starter already installs `@relkit/testing` as development tooling. Its generic harness
does not provide database/auth SDKs: keep the selected installations and repairs from the previous
chapters, and use the `@relkit/testing/better-auth` leaf shown in the integration tests.

1. ## 1. Test pricing without HTTP [#test-pricing-without-http]

    The price function is reusable application behavior. Add `tests/unit/orders-pricing.test.ts`
    to check the regular and bulk prices directly, without starting a server:

    ```ts title="tests/unit/orders-pricing.test.ts"
    /** Verifies regular and ten-item bulk totals through the tutorial's original checked pricing function. */
    import { expect, test } from "bun:test";
    import { invokeFunction } from "@relkit/testing";
    import priceOrder from "../../src/services/orders/functions/price-order.function.js";

    test("bulk pricing preserves the regular price below ten", async () => {
      expect(await invokeFunction(priceOrder, { quantity: 3 })).toEqual({ totalCents: 300 });
      expect(await invokeFunction(priceOrder, { quantity: 10 })).toEqual({ totalCents: 900 });
    });
    ```

    Add `tests/unit/orders.function.test.ts` with the version below. It tests the public
    pricing operation without acquiring a database.

    ```ts title="tests/unit/orders.function.test.ts"
    /** Invokes the tutorial pricing member directly to verify its ten-item discount independently of HTTP. */
    import { expect, test } from "bun:test";
    import { invokeFunction } from "@relkit/testing";
    import orders from "@app/services/orders/service.js";

    test("priceOrder is available without the HTTP route", async () => {
      expect(await invokeFunction(orders.priceOrder, { quantity: 10 })).toEqual({ totalCents: 900 });
    });
    ```

    Replace the minimal starter's Hello integration test with the version below. The endpoint
    is unchanged, but every test application now needs the auth secret declared in `src/platform/env.ts`.

    ```ts title="tests/integration/hello.route.test.ts"
    /** Exercises the complete auth tutorial application through its selected native test owner. */
    import { afterAll, expect, test } from "bun:test";
    import { createTestApplication } from "@relkit/testing/better-auth";
    import config from "../../relkit.config.js";

    const testApp = await createTestApplication(config, {
      env: { BETTER_AUTH_SECRET: "isolated-test-secret-never-use-in-production-12345" },
    });

    test("GET /hello", async () => {
      const response = await testApp.http.get("/hello?name=Mustafa");
      expect(response.status).toBe(200);
      expect(await response.json()).toEqual({ message: "Hello, Mustafa!" });
    });

    afterAll(() => testApp.close());
    ```

2. ## 2. Test the HTTP and database boundary [#test-the-http-and-database-boundary]

    Add `tests/integration/orders.route.test.ts` with this test. It migrates a
    temporary SQLite database, signs up Alice and Bob, creates an order for Alice, checks Bob cannot
    read it, and rejects invalid input. It also checks that a signed-out request receives `401`.

    ```ts title="tests/integration/orders.route.test.ts"
    /** Verifies migrated order persistence and authentication through the selected native test owner. */
    import { expect, test } from "bun:test";
    import { Database } from "bun:sqlite";
    import { mkdtemp, rm } from "node:fs/promises";
    import { tmpdir } from "node:os";
    import { join, resolve } from "node:path";
    import { createTestApplication, type TestApplication } from "@relkit/testing/better-auth";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import { migrate } from "drizzle-orm/bun-sqlite/migrator";
    import config from "../../relkit.config.js";
    const headers = { "content-type": "application/json", origin: "http://127.0.0.1:3000" };
    test("orders persist and remain private to their owner", async () => {
      const root = await mkdtemp(join(tmpdir(), "relkit-orders-guide-"));
      const path = join(root, "orders.sqlite");
      const previous = process.env.BETTER_AUTH_SECRET;
      process.env.BETTER_AUTH_SECRET = "isolated-test-secret-never-use-in-production-12345";
      const sqlite = new Database(path);
      try {
        await migrate(drizzle({ client: sqlite }), {
          migrationsFolder: resolve(import.meta.dir, "../../src/services/database/migrations"),
        });
      } finally {
        sqlite.close();
      }
      const app = await createTestApplication(config, {
        env: { DATABASE_PATH: path, BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET },
      });
      try {
        expect((await app.http.get("/orders/order-1")).status).toBe(401);
        const alice = await signUp(app, "Alice", "alice@example.com");
        const bob = await signUp(app, "Bob", "bob@example.com");
        const created = await app.http.post("/orders", {
          headers: { ...headers, ...alice },
          body: JSON.stringify({ orderId: "order-1", sku: "book", quantity: 10 }),
        });
        expect(created.status).toBe(201);
        expect(await created.json()).toMatchObject({ totalCents: 900 });
        expect(await (await app.http.get("/orders/order-1", { headers: alice })).json()).toMatchObject({
          found: true,
        });
        expect(await (await app.http.get("/orders/order-1", { headers: bob })).json()).toEqual({
          found: false,
        });
        const invalid = await app.http.post("/orders", {
          headers: { ...headers, ...alice },
          body: JSON.stringify({ orderId: "bad", sku: "book", quantity: 0 }),
        });
        expect(invalid.status, await invalid.text()).toBe(422);
      } finally {
        await app.close();
        if (previous === undefined) delete process.env.BETTER_AUTH_SECRET;
        else process.env.BETTER_AUTH_SECRET = previous;
        await rm(root, { recursive: true, force: true });
      }
    });

    /** Acquires the same native session cookie for each distinct order owner. */
    async function signUp(app: TestApplication, name: string, email: string) {
      const response = await app.http.post("/api/auth/sign-up/email", {
        headers,
        body: JSON.stringify({ name, email, password: "local-test-password-123" }),
      });
      expect(response.status).toBe(200);
      return { cookie: response.headers.get("set-cookie")?.split(";", 1)[0] ?? "" };
    }
    ```

    The test uses `createTestApplication` for the in-process HTTP boundary. It covers these paths in
    the test harness; it does not prove every production server behavior. Keep the manual requests
    from the previous chapters for the running backend.

3. ## 3. Run the checks [#run-the-checks]

    From the application root, with the migration files still present:

    ```sh title="Terminal — relkit-orders"
    bun run check
    bun run typecheck
    bun run test
    ```

    Expect all commands to exit `0`. If the integration test cannot find `drizzle/`, finish the
    two migrations from the preceding chapters. If another test still asserts the starter's old
    response shape, update that assertion to include `quantity` and stored behavior.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/testing` API](/docs/api/testing)
- [`@relkit/routes` API](/docs/api/routes)

- [`templates/default/v1/api/tests/integration/orders.route.test.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/tests/integration/orders.route.test.ts)

---

# Modules
Source: https://relkit.dev/docs/modules

Choose the capability you want to add or configure. Each module explains its purpose, configuration, supported operations, and limits.

"Modules" is a documentation category. Your application still uses services, routes, and platform configuration.

## Application foundations

**[Application configuration with defineApp](/docs/learn/concepts/application)**

Configure the application

**[Environment contracts with defineEnv](/docs/learn/concepts/environment)**

Declare environment values

**[Constants and prompts](/docs/modules/service/context-values)**

Share constants and prompt text

**[Services](/docs/modules/service)**

Organize application behavior

**[HTTP](/docs/modules/http)**

Accept HTTP requests

**[CLI](/docs/modules/cli)**

Create, develop, and build an app

## Data and background work

**[Database](/docs/modules/database)**

Store and query application data

**[Authentication](/docs/modules/auth)**

Sign in and protect requests

**[Buckets](/docs/modules/storage)**

Store files

**[Caching](/docs/modules/caching)**

Reuse computed values

**[Events](/docs/modules/events)**

React to application events

**[Jobs](/docs/modules/jobs)**

Run work in the background

## Clients and operations

**[Typed Client](/docs/modules/client)**

Call your API from a frontend

**[Frontend guide](/guides/frontend/connect-react)**

Connect a React app to your backend, step by step

**[Realtime](/docs/modules/realtime)**

Share live updates

**[Integrations](/docs/modules/integrations)**

Connect infrastructure

**[Provider authoring](/docs/modules/integrations/provider-authoring)**

Implement a provider

**[Local providers](/docs/modules/integrations/local-providers)**

Own local runtime state

**[Deployment](/docs/modules/deployment)**

Run with Docker and choose a production host and providers

**[Operations](/docs/modules/operations)**

Test, inspect, and diagnose

**[Programmatic tooling](/docs/modules/cli/automation)**

Build editor or CLI automation

## AI workflows

**[AI](/docs/modules/ai)**

Add tools and model workflows

To complete an end-to-end task, choose a [guide](/guides). For exact signatures and command options, use [Reference](/docs/api).
The [public API directory](/docs/api/public) also lists every supported package and import path,
including companion types and advanced runtime helpers.

---

# AI agents overview
Source: https://relkit.dev/docs/modules/ai

Use agents when your application needs a model to interpret a request and choose how to complete it. Tools let it do useful work in
your app: look up an order, search a catalog, or prepare a response using current data.

> **Start here**
>
> Start with [Build an offline agent](/guides/ai/build-an-offline-agent) for installation, a working
> assistant, and a test without a model API key. The [Agents](/docs/api/agents),
> [Tools](/docs/api/tools), and [LangChain integration](/docs/api/integrations/langchain) references
> describe the exact APIs.

**RELKIT agents run through native LangChain and LangGraph APIs.** RELKIT connects those workflows to
your application's functions, validation, permissions, durable threads, and execution limits. Use
`defineAgent` for model-driven work, or `defineGraph` and `defineGraphNode` for explicit workflows.
Adding subagents, skills, memory files, or a backend to `defineAgent` selects native DeepAgents
behavior through the same declaration.

Use an agent when the next step depends on a user's question. Use an ordinary function when you already know the steps, such as calculating a total or saving an order.

## Pre-setup

Use local Docker Redis for agent checkpoints and live updates. Model execution is a separate
choice: begin with the deterministic model in the [offline agent guide](/guides/ai/build-an-offline-agent).
Docker does not supply a hosted model or an API key.

1. **Install agent execution and Redis support**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.15 @relkit/local@0.7.14 langchain@1.5.10 langsmith@0.10.8
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The agent cohort also installs the filesystem provider used by the offline tutorial. This
    configuration selects Docker Redis for the running application instead.

2. **Configure checkpoint and realtime profiles**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Agent checkpoints and live updates use separate Docker Redis capabilities. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { redisAgentState, redisRealtime } from "@relkit/redis";

    export default defineApp({
      env: defineEnv({}),
      realtime: docker(redisRealtime()),
      "agent-state": docker(redisAgentState()),
      defaults: { realtime: "default", "agent-state": "default" },
    });
    ```

    Use `stateProfile: "default"` in the agent, or omit it to select this default. Redis credentials
    come from Docker. The deterministic model needs no environment key. When selecting a hosted model,
    declare its required key as `env.secret()` in your existing `defineEnv`, supply it to the backend
    process, and follow that model's [native configuration](/docs/modules/ai/agents).
    The declaration validates the key; it does not configure the model automatically.

    Tools exposed only through MCP do not need checkpoint storage. Workspace files use a separate
    [bucket profile](/docs/modules/storage#pre-setup) when selected.

3. **Check and start after registering the agent**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

## The AI APIs

Usually, adding tools to a model means writing argument schemas, dispatching tool calls, handling results, and controlling how long the model can keep working. RELKIT lets you reuse validated functions as tools, choose which tools an agent can use, and set limits on each run.

| API                 | What you use it for                                                       |
| ------------------- | ------------------------------------------------------------------------- |
| `defineAgent`       | Set native model, tool, middleware, DeepAgents, and client behavior.      |
| `defineGraph`       | Register a typed native LangGraph workflow and its public result.         |
| `defineGraphNode`   | Validate graph-node state updates, routes, and human continuation.        |
| `defineTool`        | Give an existing function a tool name, description, and execution policy. |
| `function.asTool()` | Turn a function into a tool directly.                                     |
| `mcp`               | Choose whether a tool is available to external MCP clients.               |

The same tool can serve a RELKIT agent and an external AI client through **Model Context Protocol (MCP)**. You do not need a RELKIT agent just to expose tools over MCP.

## Native framework boundary

Pass compatible LangChain models, tools, and middleware directly—there is no public adapter wrapper.
RELKIT function-backed tools remain native-compatible while preserving function execution, validation,
authorization, and tool policies. LangGraph owns scheduling and control flow; RELKIT validates declared
state and public output around it.

## Observe durable execution

Client-exposed agents stream one canonical event history over HTTP iteration, AG-UI SSE, or WebSocket.
AG-UI is independently opt-in. Only when selecting that protocol, install its SDK and set
`server.agUi` to `true` in your existing application configuration:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @ag-ui/core@0.0.59
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This optional protocol is validated before readiness; ordinary
typed agent RPC and streaming do not select it.
The typed client exposes messages, tools, progress, selected middleware state, waiting requests, nested
execution, and final output separately. Every run, observation, control, and continuation supplies an
application-owned `threadId`; mounting a hook never invents one or starts work.

See [Agent streaming](/docs/modules/ai/streaming) and [Threads and recovery](/docs/modules/ai/threads-recovery).

For the complete native boundary, continue with [Native runtime and DeepAgents](/docs/modules/ai/native-runtime)
and [LangGraph, persistence, and resume](/docs/modules/ai/graphs-persistence).

## Choose where to start

Follow the [greeting-assistant tutorial](/guides/ai/build-an-offline-agent) to add an agent to an existing app and test it without a model API key.

Already have application functions? [Turn one into a tool](/docs/modules/ai/function-tools), then [give it to an agent](/docs/modules/ai/agents) or [connect an MCP client](/docs/modules/ai/mcp).

With the separately installed and enabled [Inspector](/docs/modules/operations/inspector), open **Agents**
to review an agent's tools and limits, or **Tools** to review the functions each tool calls.

> **Review MCP access**
>
> MCP is disabled by default. When you explicitly enable it, tools are exposed unless you set `mcp:
> false`. Before making your app reachable by other users, review tool visibility and protect
> `/mcp`. An agent's tools list does not restrict the MCP endpoint.

---

# Define an agent
Source: https://relkit.dev/docs/modules/ai/agents

An agent uses a language model to decide which steps and tools can answer a request. For a fixed sequence of steps, use [a function](/docs/learn/concepts/functions).

Pass compatible LangChain models, tools, and middleware directly. RELKIT validates the declared input,
output, limits, tool policies, and public client contract around the native execution. For exact options,
use the [native agent reference](/docs/api/integrations/langchain#defineagent).

See [Native runtime and DeepAgents](/docs/modules/ai/native-runtime) for the supported package cohort, public
typing boundary, and deep-agent limitations. For explicit workflows and durable continuation, use
[LangGraph, persistence, and resume](/docs/modules/ai/graphs-persistence).

## Pre-setup

Complete [agent setup](/docs/modules/ai#pre-setup) to install the native runtime and configure
Docker Redis for `agent-state` and `realtime`. Keep the agent's `stateProfile` aligned with
the configured default. A hosted model additionally needs its SDK and secret environment
value; the deterministic example needs no model key. Filesystem state remains an explicit
alternative in the offline tutorial.

## Scaffold an agent

Add a native agent to an existing service with the installed CLI:

```sh title="Terminal — application root"
bun run relkit add agent Assistant --service hello \
  --instructions "Answer greeting questions."
```

This creates `src/services/hello/agents/assistant.agent.ts` with an offline model and no tools.
Replace its input/output schemas and instructions with your task. Add tools explicitly when
needed; scaffolding does not expose an HTTP endpoint or enable an agent client automatically.

As an alternative to manually creating the agent, this scaffold plans and normally installs the native
integration and four SDK peers itself. With `--no-install`, run `bun install` and `bun run check`
afterward. It does not select your realtime/agent-state profiles for you. The scaffold uses a
deterministic offline model. Replace that model in
server code when you are ready to configure a production provider.

For every agent scaffolding flag, see the [agent command reference](/docs/api/cli#relkit-add-agent-name).

## Scaffold a reusable prompt

Create a prompt before referencing it from an agent:

```sh
bun run relkit add prompt greeting-policy --service hello \
  --text "Answer greeting questions." --text "Keep answers brief."
```

The prompt is saved as `src/services/hello/prompts/greeting-policy.prompt.ts`; repeated non-empty `--text`
values preserve separate prompt segments. In headless execution at least one `--text` is required.
Prompts are internal descriptors, not public service members. Pass the prompt descriptor as the
agent's `instructions` when you need reusable policy text.

When creating a new agent, select it with `--prompt greeting-policy` instead of `--instructions`.
Use `--tool <tool>` for each existing tool to attach. For an existing agent, edit its descriptor
instead of running `add agent` again. See [constants and prompts](/docs/modules/service/context-values)
for their shared-value contract.

For every prompt scaffolding flag, see the [prompt command reference](/docs/api/cli#relkit-add-prompt-name).

## Install the native runtime

> **Before you begin**
>
> Start with an [existing minimal app](/docs/learn/create-an-app). Its generic agent contracts do
> not install native execution. When adding the declaration manually, install the explicit
> integration and SDK cohort before importing `defineAgent` from `@relkit/langchain`:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.15 @relkit/local@0.7.14 langchain@1.5.10 langsmith@0.10.8
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The recipe includes the optional filesystem providers used by the
[offline tutorial](/guides/ai/build-an-offline-agent#configure-the-runtime). For the default running
application, keep the Docker Redis profiles from pre-setup. Generic contracts from `@relkit/agents`
or `@relkit/app/agents` do not install LangChain.

Model-provider packages are application dependencies. The generated sample uses LangChain's offline
`FakeToolCallingModel`, so its tests and first run need no account, network request, or paid service.

## Define the task

This agent answers greeting questions using a single tool. Create it after [defining the lookup tool](/docs/modules/ai/function-tools).

```ts title="src/services/hello/agents/assistant.agent.ts"
/** Runs an offline greeting agent with RELKIT/native tools, todo middleware and public state observation. */
import { defineAgent } from "@relkit/langchain";
import { z } from "@relkit/app/schema";
import { FakeToolCallingModel, todoListMiddleware, tool } from "langchain";
import lookup from "@app/services/hello/tools/lookup.tool.js";

export const uppercase = tool(async ({ text }: { readonly text: string }) => text.toUpperCase(), {
  name: "uppercase",
  description: "Uppercase text without leaving the process",
  schema: z.object({ text: z.string() }),
});

export default defineAgent({
  id: "hello.assistant",

  input: z.object({ message: z.string().min(1) }),
  output: z.object({ answer: z.string() }),

  model: new FakeToolCallingModel({
    toolCalls: [
      [
        {
          name: "write_todos",
          args: { todos: [{ content: "Answer the greeting", status: "completed" }] },
          id: "todo-1",
        },
      ],
      [
        {
          name: "relkit_output",
          args: { value: { answer: "Hello from the offline LangChain model." } },
          id: "output-1",
        },
      ],
    ],
  }),
  instructions: "Answer greeting questions with the available tools.",
  tools: [lookup, uppercase],
  middleware: [todoListMiddleware()],
  stateProfile: "default",
  client: {
    public: true,
    state: ["todos"],
    events: { notice: z.object({ message: z.string() }) },
  },
  chat: { input: "message", output: "answer" },
  controls: ["stop"],

  limits: {
    maxSteps: 4,
    maxToolCalls: 4,
    timeoutMs: 10_000,
  },
});
```

`input` describes what your app sends; `output` describes the answer your app expects. RELKIT validates both. Output validation checks the shape, not whether the model's answer is factually correct.

Write `instructions` that explain when to use each tool and how to answer. The agent can call only tools in its `tools` array. Start with the smallest set needed for the task.

### Use this agent from the frontend

After [frontend setup and pulling the greeting agent's contract](/guides/frontend/connect-react),
render this component under the provider. Supply a stable business `threadId` owned by your
application, such as the ID of the conversation the user opened:

```tsx title="src/Assistant.tsx"
"use client";

/** Sends one greeting to the documented hello.assistant agent and observes its typed answer. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Keeps the application-owned thread identity stable across rendering and observation.
 * @param props - Authorized conversation identity retained by the application.
 * @returns A greeting action, the observed answer, and explicit submission failure. */
export function Assistant({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const assistant = useAgent("hello.assistant");
  const [failure, setFailure] = useState("");

  /** Submits once and preserves uncertain outcomes for explicit recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function sendGreeting() {
    try {
      await assistant.send("Hello, RELKIT!", { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || assistant.status !== "idle" || failure !== ""}
        onClick={sendGreeting}
      >
        Say hello
      </button>
      <p role="status">{assistant.output?.answer ?? assistant.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

This is the same `hello.assistant` declaration: `client.public` exposes it, `chat.input: "message"`
makes `send` accept a string, and `chat.output: "answer"` selects its typed answer. Mounting
`useAgent` does not start a run. The backend owns models, credentials, tools, and authorization.

Reference: [`useAgent`](/docs/api/client#useagent).
Continue with [streaming and controls](/docs/modules/ai/streaming) or
[thread recovery](/docs/modules/ai/threads-recovery).

## Set limits

All three `limits` are required positive integers:

| Option         | What it limits                  |
| -------------- | ------------------------------- |
| `maxSteps`     | Model steps in a run.           |
| `maxToolCalls` | Total tool calls in a run.      |
| `timeoutMs`    | Total run time in milliseconds. |

If a run exceeds a limit, it fails rather than continuing indefinitely. Set limits that fit your task and handle failures in the calling application.

## Choose a model

`model` accepts a compatible native LangChain model instance or a lazy application model. Install and
configure the provider package in server code; never put credentials, live instances, or provider
payloads in browser contracts. Subagents inherit the parent model unless they declare an override.

## Run the typed client

Expose the agent through `client`, then select it with `useAgent`. Run, observe, stop, and resume calls
all require the caller's stable business thread ID:

For this declaration, select `hello.assistant`; `send(message, { threadId })` accepts a string
because `chat.input` maps it to `message`, and the final `output.answer` follows the output schema.
`stop({ threadId })` is available because the agent declares `stop`. The
[Frontend guide](/guides/frontend/connect-react) establishes the provider and contract pull, and
[Agent streaming and controls](/docs/modules/ai/streaming#use-from-the-frontend) shows a complete
typed UI, including how a different agent's policy changes the available controls.

Reference: [`useAgent`](/docs/api/client#useagent).

The generated selector narrows initial input, final output, selected middleware state, tools, custom
events, waiting replies, and controls. A resume uses the same thread with `{ resume: true }`; it does not
start a replacement run.

Keep authorization in your application functions. Model instructions are not a replacement for checking whether the current user may read or change data.

## Streaming

The client-exposed agent has a durable thread journal: `useAgent` restores its authorized snapshot and
observes text parts, tool calls, progress, approvals, selected state, nested execution, and terminal
output incrementally. Mounting the hook never creates a thread or starts a run. See
[Agent streaming](/docs/modules/ai/streaming) and [Threads and recovery](/docs/modules/ai/threads-recovery).

---

# Tool approvals
Source: https://relkit.dev/docs/modules/ai/approvals

Require approval before a tool performs an action that needs the user's decision, such as cancelling an order. The model may propose the action; it must not approve itself.

Native LangChain middleware and tools may interrupt execution, but they do not replace RELKIT's tool
policy. Use the policies and trusted invocation decisions below for function-backed tools.

> **Before you begin**
>
> Start with an existing [function-backed tool](/docs/modules/ai/tools). These approval policies do
> not require a model SDK; native agent execution and its [test
> helpers](/guides/ai/build-an-offline-agent#test-without-a-model-key) require the explicit
> `@relkit/langchain` installation.

## Choose a policy

`defineTool.approval` and `.asTool({ approval })` accept exactly three policy strings:

The examples below are alternatives: choose the policy that fits each tool.

| `approval` | Behavior                                                                       |
| ---------- | ------------------------------------------------------------------------------ |
| `never`    | No separate approval decision is required.                                     |
| `on-write` | Require approval for `write` and `external` actions, but not `none` or `read`. |
| `always`   | Require approval for every call, including reads.                              |

Declare `sideEffect` accurately. A write incorrectly marked as a read can skip an intended `on-write` approval.

### No approval for a read

Use `never` when the operation may run without a separate confirmation:

```ts title="src/services/hello/tools/lookup.tool.ts"
/** Exposes the hello function as a read-only greeting tool with its existing two-second timeout. */
import hello from "@app/services/hello/functions/hello.function.js";

export default hello.asTool({
  id: "hello.lookup",
  description: "Read a greeting for a supplied name",

  sideEffect: "read",
  approval: "never",
  timeoutMs: 2_000,
});
```

### Approval for writes

This `defineTool` example requires confirmation because its side effect is `write`:

```ts title="src/services/orders/tools/cancel-order.tool.ts"
import { defineTool } from "@relkit/app/tools";
import deleteOrder from "../../src/services/orders/functions/delete-order.function.js";

export const cancelOrder = defineTool({
  id: "orders.cancel-order-on-write",
  target: deleteOrder,
  description: "Cancel an order after confirmation",

  sideEffect: "write",
  approval: "on-write",
  timeoutMs: 2_000,
  mcp: false,
});
```

It uses the existing order-deletion function. `mcp: false` keeps this approval-required tool out of MCP.

### Approval on every call

This order-cancellation tool requires approval on every call:

```ts title="src/services/orders/tools/cancel-order.tool.ts"
/** Exposes the order deletion function as a write tool requiring explicit approval before invocation. */
import deleteOrder from "../functions/delete-order.function.js";

const cancelOrder = deleteOrder.asTool({
  id: "orders.cancel-order",
  description: "Cancel one order after a human approves the write",
  sideEffect: "write",
  approval: "always",
  timeoutMs: 2_000,
});

export default cancelOrder;
```

The function must still check whether the caller may cancel that order. Approval does not replace authorization.

## Use an approval callback

The tool's `approval` policy is not a function. The callback goes in the second argument of **`tool.invoke()`**, where your application supplies the decision for that call.

The callback may return `true` or `"approved"` to allow execution, and `false` or `"denied"` to stop it. It may also return a Promise of any of those values. It receives `{ toolId, sideEffect, policy }`; capture the specific action's arguments from your calling code.

### Wait for a trusted confirmation

For the `on-write` tool above, call your own confirmation flow before cancelling:

```ts title="Calling cancelOrder with an asynchronous decision"
/** Invokes cancellation only after the trusted confirmation flow approves the exact order.
 * @param orderId - Order identity shown to confirmation and passed to the tool.
 * @param confirm - Trusted asynchronous decision callback.
 * @returns The native checked deletion result when approval succeeds.
 * @throws The original invocation failure when confirmation denies or fails. */
export async function cancelOrderWithApproval(
  orderId: string,
  confirm: (message: string) => Promise<boolean>,
): Promise<{ orderId: string; deleted: boolean }> {
  return cancelOrder.invoke(
    { orderId },
    {
      // Ask your trusted confirmation flow about this specific order.
      approval: async () => {
        const confirmed = await confirm(`Cancel order ${orderId}?`);
        return confirmed ? "approved" : "denied";
      },
    },
  );
}
```

Your app supplies `confirm` from a trusted UI or approval service. Bind the decision to the authenticated user and this specific order; do not take approval from model-generated arguments or an unchecked request field. Setting the tool policy alone does not create a confirmation screen.

### Test synchronous decisions

These unit-test examples show every supported decision value. The unconditional callbacks are test stubs, not a production approval flow:

```ts title="tests/tool-approvals.test.ts — decision values"
await expect(
  cancelOrder.invoke({ orderId: "order-123" }, { approval: () => true }),
).resolves.toEqual({ orderId: "order-123", deleted: true });

await expect(
  cancelOrder.invoke({ orderId: "order-123" }, { approval: () => "approved" }),
).resolves.toEqual({ orderId: "order-123", deleted: true });

await expect(
  cancelOrder.invoke({ orderId: "order-123" }, { approval: () => false }),
).rejects.toMatchObject({ code: "RELKIT_APPROVAL_DENIED" });

await expect(
  cancelOrder.invoke({ orderId: "order-123" }, { approval: () => "denied" }),
).rejects.toMatchObject({ code: "RELKIT_APPROVAL_DENIED" });
```

A missing callback on an approval-required call fails with `RELKIT_APPROVAL_REQUIRED`; a denied decision fails with `RELKIT_APPROVAL_DENIED`. A callback that throws also stops execution. A callback is not called when the policy does not require approval.

## Agent and MCP behavior

A client-exposed agent that declares the `approve` control publishes approval waiting state through its
durable thread. The typed hook exposes `approve(approvalId, { threadId })` and
`deny(approvalId, { threadId })`; the caller must use the same authorized business thread. The
[agent test helper](/docs/api/testing) can supply scripted approvals for deterministic tests.

Over [MCP](/docs/modules/ai/mcp#protect-access), approval-required calls are currently rejected; there is no MCP approval-and-resume flow. Keep these tools out of MCP with `mcp: false` if clients cannot use them.

---

# Functions as tools
Source: https://relkit.dev/docs/modules/ai/function-tools

Turn an existing function into a tool with `.asTool()` so an agent or MCP client can call it. Keep the business logic in the function and add a description and execution policy for AI callers.

> **Before you begin**
>
> Start with an [installed minimal app](/docs/learn/create-an-app). Function-backed tools need no
> LangChain integration. [MCP](/docs/modules/ai/mcp) and [native
> agents](/guides/ai/build-an-offline-agent) each add their own selected dependencies when you
> choose those execution paths.

1. ## Define the function

    This small function returns a greeting. In a real app, the function might look up a product or fetch an order the current user is allowed to see.

    ```ts title="src/services/hello/functions/hello.function.ts"
    /** Returns a validated named greeting and logs each invocation through RELKIT's request context. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const hello = defineFunction({
      id: "hello.greet",

      input: z.object({ name: z.string().min(1).default("world") }),
      output: z.object({ message: z.string() }),

      /**
       * Logs the greeting invocation and returns the validated greeting response.
       * @param input - Validated name from the function schema.
       * @param context - RELKIT invocation context owning structured logging.
       * @returns Greeting response matching the output schema.
       */
      handler: async ({ name }, context) => {
        context.log.info("hello invoked", { name });

        return { message: `Hello, ${name}!` };
      },
    });

    export default hello;
    ```

2. ## Turn it into a tool

    Import the function into a tool file and call `.asTool()`:

    ```ts title="src/services/hello/tools/lookup.tool.ts"
    /** Exposes the hello function as a read-only greeting tool with its existing two-second timeout. */
    import hello from "@app/services/hello/functions/hello.function.js";

    export default hello.asTool({
      id: "hello.lookup",
      description: "Read a greeting for a supplied name",

      sideEffect: "read",
      approval: "never",
      timeoutMs: 2_000,
    });
    ```

    The tool accepts the same input and returns the same output as `hello`. The function remains callable by the rest of your app.

    Use a normal `defineFunction` here. Event-only functions created with `defineEventFunction` cannot become tools.

3. ## Use the tool

    Add `lookup` to an [agent's tools](/docs/modules/ai/agents), or call `hello.lookup` from [an MCP client](/docs/modules/ai/mcp). Both use the same greeting function.

    `.asTool()` and [`defineTool({ target: hello, ... })`](/docs/modules/ai/tools) are alternatives; you do not need both. Both expose the tool to MCP by default. Set `mcp: false` if the tool should be available only inside your app.

---

# LangGraph, persistence, and resume
Source: https://relkit.dev/docs/modules/ai/graphs-persistence

A graph describes a workflow whose steps and branching rules belong to your application. RELKIT registers the declared topology and compiles a native LangGraph while preserving native reducers,
parallel scheduling, conditional edges, loops, `Send`, subgraphs, retry behavior, and pending writes.

Agent graph state and checkpoint resources remain the authority for graph continuation. A task may invoke an
agent, but task retries do not silently replace the graph's thread or checkpoint identity; use the existing
agent continuation contract.

> **Before you begin**
>
> Complete the [native agent installation and runtime bindings](/guides/ai/build-an-offline-agent)
> first. For a browser caller, also complete [frontend client setup](/docs/modules/client) in its
> own package.

## Define state and control flow

The commerce review graph runs two branches, joins them, loops once, interrupts for a boolean, and returns
only its selected output:

```ts title="examples/commerce/src/services/orders/agents/order-review.agent.ts"
const orderReview = defineGraph({
  state,
  input: z.object({ orderId: z.string() }),
  output: z.object({ result: z.string() }),
  nodes: [inventory, risk, retry, review, finish],
  edges: (edge) =>
    edge
      .addEdge(START, "load-inventory")
      .addEdge(START, "assess-risk")
      .addEdge(["load-inventory", "assess-risk"], "retry")
      .addConditionalEdges("retry", ({ attempts }) => (attempts === 1 ? "again" : "ready"), {
        again: "retry",
        ready: "review",
      })
      .addEdge("finish", END),
  checkpointer: orderCheckpoints,
  store: orderMemory,
  limits: { maxSteps: 10, maxToolCalls: 1, timeoutMs: 20_000 },
  stateProfile: "agents",
  client: {
    public: true,
    state: ["inventory", "risk", "attempts", "approved", "result"],
  },
  controls: ["stop"],
});
```

### Run and resume this graph from the frontend

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider with your application's stable business `threadId`:

```tsx title="src/OrderReview.tsx"
"use client";

/** Starts the commerce review graph and answers its boolean interrupt on the same business thread. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Keeps initial input and a waiting reply distinct while rendering the graph's final result.
 * @param props - Authorized order-review thread retained by the application.
 * @returns Start/approve actions, current result, and visible submission failure. */
export function OrderReview({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const review = useAgent("orders.order-review");
  const [failure, setFailure] = useState("");

  /** Starts one review; uncertain acceptance is left for explicit thread recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function startReview() {
    try {
      await review.run({ orderId: "demo-1" }, { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  /** Replies with the review node's declared boolean on the original thread.
   * @returns Completion after the continuation is accepted or its failure is displayed. */
  async function approve() {
    try {
      await review.run(true, { threadId, resume: true });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || review.status !== "idle" || failure !== ""}
        onClick={startReview}
      >
        Start review
      </button>
      <button
        disabled={status !== "ready" || review.status !== "waiting" || failure !== ""}
        onClick={approve}
      >
        Approve order
      </button>
      <p role="status">{review.output?.result ?? review.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

`defineGraph` generates an agent client too. The initial `run` receives `{ orderId }`; the review
node's `resume: z.boolean()` makes the continuation accept a boolean. Resume the same thread with
`{ resume: true }`, and show the final `output.result`. Do not send a replacement initial run to
answer an interrupt or replay an uncertain submission.

Reference: [`useAgent`](/docs/api/client#useagent).
Continue with [threads and recovery](/docs/modules/ai/threads-recovery).

`StateSchema` owns native state and reducer behavior. A `defineGraphNode` input schema projects the fields
that node can read; its output validates an object partial update. Declare every possible `Command`
destination in `ends`. The edge builder accepts only registered node IDs plus valid `START` and `END`
sentinels, so stale destinations fail type checking and compilation.

`interrupt()` is graph control flow, not a normal function failure. The review node declares
`resume: z.boolean()`, then returns a native `Command` that applies the validated reply and routes to
`finish`. A resumed node starts again according to LangGraph semantics. Put the interrupt before an
irreversible effect, or make that effect idempotent with a durable business key or application-owned
transaction.

## Declare checkpoint and memory resources

Checkpoint history and long-term memory are separate resources:

```ts title="examples/commerce/src/services/orders/agents/order-agent-persistence.ts"
/** Shares borrowed in-memory LangGraph checkpoint and memory drivers across the example's order agents. */
import { InMemoryStore, MemorySaver } from "@langchain/langgraph";
import { defineCheckpointerDb, defineMemoryDb } from "@relkit/langchain";

// Replace these borrowed native drivers with SQLite, Postgres, MongoDB, or Redis in production.
export const orderCheckpoints = defineCheckpointerDb({
  id: "orders.agent-checkpoints",
  client: new MemorySaver(),
});

export const orderMemory = defineMemoryDb({
  id: "orders.agent-memory",
  client: new InMemoryStore(),
});
```

`defineCheckpointerDb` accepts a native `BaseCheckpointSaver`; `defineMemoryDb` accepts a native
`BaseStore`. The tested driver cohort is:

| Resource     | Supported native implementations                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------- |
| Checkpointer | `MemorySaver`, SQLite, PostgreSQL, MongoDB, Redis and shallow Redis, or a compatible custom saver |
| Memory store | `InMemoryStore`, PostgreSQL, MongoDB, or a compatible custom store                                |

The tested `RedisStore` does not satisfy the selected LangGraph `BaseStore` declarations: it lacks
the lifecycle methods and operation-specific batch result typing required by `defineMemoryDb`.
Strict Redis memory-store compatibility is therefore not guaranteed in this cohort. This declaration
limitation does not establish that Redis memory cannot run through LangGraph's internal batching
wrapper. The Redis and shallow Redis checkpointer entries above remain supported separately.

Driver-specific retention, TTL, serialization, shallow-history, and semantic-search capabilities remain
native. RELKIT does not flatten them into options that every driver supposedly supports.

The in-memory saver/store in the example are supplied by the selected LangGraph SDK. External driver
packages are application-owned dependencies. Install only the driver you choose, in the backend root;
these pins come from the native integration's tested driver declarations:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

| Driver   | Tested package                                 | Install only your selected driver                        |
| -------- | ---------------------------------------------- | -------------------------------------------------------- |
| sqlite   | @langchain/langgraph-checkpoint-sqlite@1.0.4   | `bun add @langchain/langgraph-checkpoint-sqlite@1.0.4`   |
| postgres | @langchain/langgraph-checkpoint-postgres@1.0.5 | `bun add @langchain/langgraph-checkpoint-postgres@1.0.5` |
| mongodb  | @langchain/langgraph-checkpoint-mongodb@1.4.1  | `bun add @langchain/langgraph-checkpoint-mongodb@1.4.1`  |
| redis    | @langchain/langgraph-checkpoint-redis@1.0.11   | `bun add @langchain/langgraph-checkpoint-redis@1.0.11`   |

An installation/type compatibility check does not initialize its database or certify a production
driver deployment. Keep the Redis memory-store limitation above when choosing a driver.

## Initialize and own resources explicitly

RELKIT never calls driver `.setup()`, runs migrations, creates tables or indexes, installs extensions, or
pushes an application schema during compilation, inspection, activation, or an ordinary request. Perform
the driver's documented initialization as an explicit application or infrastructure step before starting
workers.

A supplied instance is borrowed by default and is never closed by RELKIT. A factory is owned by default;
owned resources require a `dispose` callback and are released once. Set `ownership` explicitly when the
default does not match the real lifecycle.

Prefer a dedicated AI database. Sharing a physical database requires a compatible underlying client,
isolated tables or schemas, a restricted role, and migration filters that keep checkpoint/store objects out
of the application Drizzle lifecycle. A RELKIT Redis cache provider is not a Redis saver or store.

## Resume the same business thread

Every initial run, observation, stop, steering operation, follow-up, approval, and continuation supplies a
caller-owned `threadId`. RELKIT never derives one from input, remembers an implicit current thread, or
generates a fallback. Internal run, task, attempt, and operation IDs are separate.

After the graph persists its checkpoint and waiting contract, submit the exact declared reply on the same
thread with `{ resume: true }`. A boolean wait rejects text such as `"yes"`; RELKIT does not interpret it.
The runtime binds the continuation to the waiting revision, scope, action, policy, and response schema,
deduplicates an accepted receipt, and fences competing workers.

See [Threads and recovery](/docs/modules/ai/threads-recovery) for restart and external-effect safety, and
[Agent streaming](/docs/modules/ai/streaming) for the public event sequence.

---

# Tools over MCP
Source: https://relkit.dev/docs/modules/ai/mcp

Model Context Protocol (MCP) lets an AI client discover and call the tools you expose from your application. RELKIT serves tools at `/mcp` using **Streamable HTTP**. You do not need to define an agent or write a separate MCP server.

## Pre-setup

MCP needs no provider service or new `defineEnv` fields by itself. Configure a tool's dependencies
through their modules' local Docker setup when required; keep your existing environment contract.

The endpoint is opt-in. First [define a function-backed tool](/docs/modules/ai/function-tools) in your
existing minimal app. From its root, install only the MCP SDK, then set `server.mcp` to `true`
in the existing `relkit.config.ts`, preserving other server settings:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @modelcontextprotocol/server@2.3.0
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This tool-only path needs no `@relkit/langchain`, model SDK or model key. Startup validates the
selected SDK before readiness. Ordinary REST/RPC and OpenAPI do not load MCP.

## Choose which tools to expose

When the endpoint is enabled, discovered tools created with `defineTool` or `.asTool()` are eligible
by default. Omitting a tool's `mcp` field is equivalent to `mcp: true`; the server endpoint itself
defaults to disabled. For example, the [greeting tool](/docs/modules/ai/function-tools) appears as
`hello.lookup`, with a `name` argument and a `message` result.

Set an explicit `timeoutMs` on tools you expose through MCP. The current runtime fails MCP calls when this option is omitted; the greeting example uses `2_000` milliseconds.

An agent's `tools` array controls that agent only. It does not limit which tools MCP clients can discover or call.

## Disable MCP for one tool

Set `mcp: false` in either `defineTool` or `.asTool()`:

```ts title="src/services/hello/tools/private-lookup.tool.ts"
import hello from "@app/services/hello/functions/hello.function.js";

export const privateLookup = hello.asTool({
  id: "hello.private-lookup",
  description: "Read a greeting inside this app only",

  sideEffect: "read",
  approval: "never",
  timeoutMs: 2_000,
  mcp: false,
});
```

`hello.private-lookup` will not appear in MCP's tool list or be callable over MCP. You can still add it to a RELKIT agent's `tools` array.

## Disable the MCP endpoint

Set `server.mcp` to `false` in your existing `relkit.config.ts`, preserving your other server settings:

```ts title="relkit.config.ts — inside defineApp()"
server: {
  port: 3000,
  mcp: false,
},
```

This disables `/mcp` for the entire app. It does not disable ordinary tool calls or your agents' declared tools.

## Connect a client

Start your existing app from its root:

```sh
bun run check
bun run dev
```

If the checked graph requires a model binding, supply its named credentials before starting it. Calling the
greeting tool itself does not need a model, so a tool-only app remains key-free. No `RELKIT_ENV` value installs
a hidden model provider.

In a client that supports Streamable HTTP, add your backend's MCP URL. With the default backend port, use `http://localhost:3000/mcp`, not the RELKIT Inspector port `3210`.

You can also list tools with the MCP Inspector CLI. Run this in a second terminal:

```sh
bunx @modelcontextprotocol/inspector@2.3.0 --cli \
  http://localhost:3000/mcp \
  --transport http \
  --method tools/list
```

With the greeting example installed, the response includes `hello.lookup` and its input schema. This command does not call a language model.

## Call a tool

Invoke the greeting tool directly through MCP:

```sh
bunx @modelcontextprotocol/inspector@2.3.0 --cli \
  http://localhost:3000/mcp \
  --transport http \
  --method tools/call \
  --tool-name hello.lookup \
  --tool-arg name=Ada
```

The result includes `structuredContent` with `{ "message": "Hello, Ada!" }`. RELKIT validates the arguments against the function's input schema before calling it.

## Protect access

Before exposing the backend outside your machine, authenticate requests to `/mcp` and authorize actions in each target function. Hiding a tool from an agent is not access control for MCP. Your MCP client must send the credentials your app expects.

> **Approval-required tools cannot run over MCP yet**
>
> MCP currently rejects tools with `approval: "always"`, and tools with `approval: "on-write"` when
> their side effect is `write` or `external`. It returns an approval-required error without running
> the function. A client's confirmation dialog does not satisfy this policy. Do not remove a
> required approval just to make a call succeed.

If no tools appear, check that the files are exported under your domain's `tools` directory, `mcp` is not disabled on the tool or server, and the app has reloaded.

---

# Native runtime and DeepAgents
Source: https://relkit.dev/docs/modules/ai/native-runtime

RELKIT runs ordinary agents through LangChain and uses DeepAgents when you select capabilities such as subagents, skills, or memory files. There is no public conversion wrapper or application-level runtime adapter.

## Use the certified package cohort

Native execution belongs to the explicit `@relkit/langchain` integration. Its selected SDK cohort
comes from that integration's dependency metadata. The following setup also selects the local runtime
profiles used by the [first-agent tutorial](/guides/ai/build-an-offline-agent#configure-the-runtime):

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.15 @relkit/local@0.7.14 langchain@1.5.10 langsmith@0.10.8
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

Import native `defineAgent`, `defineGraph`, and persistence resources from `@relkit/langchain`.
Generic descriptors and public event/state contracts remain available from `@relkit/app/agents`.
Install the model-provider package used by the application separately. DeepAgents is required only
when a declaration selects a deep capability; AG-UI has its own independent
[transport installation](/docs/modules/ai#observe-durable-execution). Neither belongs in a tool-only MCP app.

If a deep capability is activated without that package, execution fails with
`RELKIT_DEEPAGENTS_UNAVAILABLE` and names the required version. Optional model, saver, store, and backend
packages remain application dependencies; a missing import fails before execution, while an incompatible
checkpointer or store fails protocol validation instead of being cast to a supported driver.

## Combine native and RELKIT behavior

This agent passes a native model, native tool, real `todoListMiddleware()`, and RELKIT function-backed
tools through one declaration:

```ts title="examples/commerce/src/services/orders/agents/order-support.agent.ts"
/** Composes the offline support model, explicit order/native tools, todo middleware and shared checkpoint/memory drivers. */
import { defineAgent } from "@relkit/langchain";
import { todoListMiddleware } from "langchain";
import { supportInput, supportOutput } from "../../../platform/schemas.js";
import lookupOrder from "../tools/lookup-order.tool.js";
import cancelOrder from "../tools/cancel-order.tool.js";
import { createCommerceModel } from "./commerce-model.js";
import { orderCheckpoints, orderMemory } from "./order-agent-persistence.js";
import { orderStatus } from "./order-native-tool.js";

const orderSupport = defineAgent({
  // Inputs and final answers remain schema checked around the model call.
  input: supportInput,
  output: supportOutput,
  model: createCommerceModel("support"),
  instructions: "Answer order questions using the read-only order lookup tool.",
  // Only explicitly listed application tools are available to the agent.
  tools: [lookupOrder, cancelOrder, orderStatus],
  middleware: [todoListMiddleware()],
  checkpointer: orderCheckpoints,
  store: orderMemory,
  // Bound both tool use and total execution time.
  limits: { maxSteps: 4, maxToolCalls: 4, timeoutMs: 60_000 },
  stateProfile: "agents",
  client: { public: true, state: ["todos"] },
  chat: { input: "message", output: "answer" },
  controls: ["steer", "follow-up", "stop", "approve"],
});

export default orderSupport;
```

RELKIT function tools still execute through the common function engine, including schema validation,
authorization, cancellation, tracing, approval policy, and output validation. Native tools execute through
their native contract. Unknown native output remains `unknown` unless the declaration supplies output
schema metadata; RELKIT does not infer a contract by running the tool.

Middleware state is private unless `client.state` selects a contributed key. In the example, `todos` is
inferred from `todoListMiddleware()` and becomes a precise generated status union. `values` remains
undefined until an authorized snapshot or state event arrives. Messages, tool calls, progress, custom
events, waiting requests, and final `output` remain separate client fields.

Declared custom-event and tool schemas remain exact. Opaque native extensions use an explicit dynamic
discriminator with `unknown` data instead of widening every known event or tool.

## Add DeepAgents capabilities

Only for a declaration using deep capabilities, use this selected recipe instead of the ordinary-agent
recipe. SDK installation alone does not expand the currently verified native capability boundary:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.15 @relkit/local@0.7.14 deepagents@1.13.3 langchain@1.5.10 langsmith@0.10.8
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This declaration adds a subagent, skills, memory files, a RELKIT bucket backend, checkpointer, and store:

```ts title="examples/commerce/src/services/orders/agents/order-deep.agent.ts"
/** Delegates offline inventory checks to an inherited-model specialist using shared persistence and a private bucket workspace. */
import { defineAgent } from "@relkit/langchain";
import { supportInput, supportOutput } from "../../../platform/schemas.js";
import agentWorkspace from "../buckets/agent-workspace.bucket.js";
import lookupOrder from "../tools/lookup-order.tool.js";
import { createCommerceModel } from "./commerce-model.js";
import { orderCheckpoints, orderMemory } from "./order-agent-persistence.js";

const inventorySpecialist = defineAgent({
  id: "inventory-specialist",
  description: "Checks inventory delegated by the commerce assistant.",
  input: supportInput,
  output: supportOutput,
  instructions: "COMMERCE_INVENTORY_SPECIALIST: answer the delegated inventory question.",
  tools: [lookupOrder],
  limits: { maxSteps: 3, maxToolCalls: 2, timeoutMs: 10_000 },
});

const orderDeep = defineAgent({
  input: supportInput,
  output: supportOutput,
  model: createCommerceModel("deep"),
  instructions: "Delegate inventory checks to the specialist and return its conclusion.",
  tools: [],
  subagents: [inventorySpecialist],
  // Seed these paths in the workspace bucket to inject team-specific guidance.
  skills: ["/skills/commerce/"],
  memory: ["/AGENTS.md"],
  backend: agentWorkspace,
  checkpointer: orderCheckpoints,
  store: orderMemory,
  limits: { maxSteps: 6, maxToolCalls: 4, timeoutMs: 60_000 },
  stateProfile: "agents",
  client: { public: true },
  chat: { input: "message", output: "answer" },
  controls: ["stop"],
});

export default orderDeep;
```

Children inherit the parent model unless they declare one. They share the caller-supplied root thread and
use isolated native checkpoint namespaces; nested scopes do not become independent business threads.
Root cancellation and limits include child execution. Start an unrelated child operation with another
application-owned thread ID.

RELKIT does not emulate Python-only APIs, LangSmith Agent Server, or arbitrary structured-agent message
conversion. A RELKIT bucket backend implements the supported DeepAgents filesystem protocol, but Redis
cache clients are not saver/store drivers and generic S3 clients are not treated as DeepAgents backends.

## Understand public event semantics

One authorized, redacted event sequence feeds HTTP iteration, AG-UI SSE, WebSocket, snapshots, replay,
generated clients, and Inspector. The transports do not execute the agent independently. Disconnecting an
observer does not cancel execution; reconnect restores a consistent snapshot and continues after its
journal cursor. A cursor gap triggers explicit snapshot recovery rather than silent event loss.

Public events preserve root, node, task, attempt, subgraph, and subagent scope where metadata is known.
Raw checkpoints, commands, private middleware state, provider payloads, system prompts, credentials,
hidden reasoning, and unrestricted native state never enter browser contracts.

---

# Agent streaming and controls
Source: https://relkit.dev/docs/modules/ai/streaming

Stream agent updates to a client while keeping cancellation and other controls available.

> **Before you begin**
>
> Complete the [native agent installation and runtime bindings](/guides/ai/build-an-offline-agent)
> first. For a browser caller, also complete [frontend client setup](/docs/modules/client) in its
> own package.

## Expose the declared controls

Client-exposed agents require an agent-state profile. `useAgent` exposes only controls declared by the
agent: steer, follow-up, stop, and approval/denial. An agent with a reachable approval-requiring tool
must declare the approve capability.

```ts title="examples/commerce/src/services/orders/agents/order-support.agent.ts"
/** Composes the offline support model, explicit order/native tools, todo middleware and shared checkpoint/memory drivers. */
import { defineAgent } from "@relkit/langchain";
import { todoListMiddleware } from "langchain";
import { supportInput, supportOutput } from "../../../platform/schemas.js";
import lookupOrder from "../tools/lookup-order.tool.js";
import cancelOrder from "../tools/cancel-order.tool.js";
import { createCommerceModel } from "./commerce-model.js";
import { orderCheckpoints, orderMemory } from "./order-agent-persistence.js";
import { orderStatus } from "./order-native-tool.js";

const orderSupport = defineAgent({
  // Inputs and final answers remain schema checked around the model call.
  input: supportInput,
  output: supportOutput,
  model: createCommerceModel("support"),
  instructions: "Answer order questions using the read-only order lookup tool.",
  // Only explicitly listed application tools are available to the agent.
  tools: [lookupOrder, cancelOrder, orderStatus],
  middleware: [todoListMiddleware()],
  checkpointer: orderCheckpoints,
  store: orderMemory,
  // Bound both tool use and total execution time.
  limits: { maxSteps: 4, maxToolCalls: 4, timeoutMs: 60_000 },
  stateProfile: "agents",
  client: { public: true, state: ["todos"] },
  chat: { input: "message", output: "answer" },
  controls: ["steer", "follow-up", "stop", "approve"],
});

export default orderSupport;
```

## Use from the frontend

After [frontend setup and contract pull](/guides/frontend/connect-react), use
[`useAgent`](/docs/api/client#useagent) under `RelkitClientProvider`. This component selects
`orders.order-support`, the agent above, and reads its typed `answer`:

```tsx title="src/OrderSupport.tsx"
"use client";

/** Sends an explicit support request to the commerce agent and renders its public typed answer. */
import { useAgent, useRelkitClient } from "@relkit/client/react";
import { useState } from "react";

/** Uses an application-owned business thread rather than creating one during rendering.
 * @param props - Authorized thread identity retained by the application.
 * @returns A send action, observed answer, and visible submission failure. */
export function OrderSupport({ threadId }: { readonly threadId: string }) {
  const { status } = useRelkitClient();
  const support = useAgent("orders.order-support");
  const [failure, setFailure] = useState("");

  /** Submits once; uncertain acceptance stays visible for explicit recovery.
   * @returns Completion after acceptance or displaying the failure. */
  async function askSupport() {
    setFailure("");
    try {
      await support.send("Where is order demo-1?", { threadId });
    } catch (error) {
      setFailure(String(error));
    }
  }

  return (
    <section>
      <button
        disabled={status !== "ready" || support.status !== "idle" || failure !== ""}
        onClick={askSupport}
      >
        Ask about the order
      </button>
      <p role="status">{support.output?.answer ?? support.status}</p>
      {failure && <p role="alert">{failure}. Check this thread before submitting again.</p>}
    </section>
  );
}
```

Pass an application-owned thread ID, for example `<OrderSupport threadId="support:order-demo-1" />`,
and retain it when reopening the same conversation. The hook does not create a thread on mount.
The selected backend declaration determines the available client operations:

| Backend declaration                               | Typed frontend behavior                                                     |
| ------------------------------------------------- | --------------------------------------------------------------------------- |
| `chat` mapping                                    | `send(message, { threadId })`; other agents use `run(input, { threadId })`. |
| Input and output schemas                          | Typed initial input and `output`.                                           |
| `client.state`, tool contracts, and custom events | Selected `values`, `toolCalls`, `timeline`, and event payloads.             |
| Declared controls                                 | Stop, steer, follow-up, approval, and denial methods only when supported.   |
| A graph continuation schema                       | `run(reply, { threadId, resume: true })` for the same waiting thread.       |

`observe({ threadId })` reconnects to an existing authorized thread. Never replace an uncertain run
by choosing a new thread ID. See [threads and recovery](/docs/modules/ai/threads-recovery) and
[approvals](/docs/modules/ai/approvals) for those flows. Generic HTTP streams use
[`useStream`](/docs/modules/http/streaming#use-from-the-frontend) instead.

## Observe without blocking execution

Persistent journal acceptance is separate from browser delivery. Slow observers detach with
`SLOW_CONSUMER` and recover from the journal; they never backpressure model or tool execution.
Browser projections contain validated public messages, parts, progress, tool data, and results—not
provider payloads, internal prompts, credentials, private context, or private reasoning.

Agent content streams and task progress/streams are separate contracts. Use a task job's run ID and generated
job client for background work; do not treat an agent graph state or realtime channel as a task run.

---

# Threads and recovery
Source: https://relkit.dev/docs/modules/ai/threads-recovery

Restore an agent thread after a reconnect or restart without pretending uncertain work has completed.

> **Before you begin**
>
> Complete the [native agent installation and runtime bindings](/guides/ai/build-an-offline-agent)
> first. For a browser caller, also complete [frontend client setup](/docs/modules/client) in its
> own package.

## Restore one consistent snapshot

Loading a thread returns one consistent snapshot and matching journal checkpoint. The browser installs
the snapshot completely, then reads records strictly after that checkpoint. Older history is finite,
authenticated cursor pagination tied to the pinned snapshot.

```ts title="examples/commerce/src/services/orders/agents/order-support.agent.ts"
/** Composes the offline support model, explicit order/native tools, todo middleware and shared checkpoint/memory drivers. */
import { defineAgent } from "@relkit/langchain";
import { todoListMiddleware } from "langchain";
import { supportInput, supportOutput } from "../../../platform/schemas.js";
import lookupOrder from "../tools/lookup-order.tool.js";
import cancelOrder from "../tools/cancel-order.tool.js";
import { createCommerceModel } from "./commerce-model.js";
import { orderCheckpoints, orderMemory } from "./order-agent-persistence.js";
import { orderStatus } from "./order-native-tool.js";

const orderSupport = defineAgent({
  // Inputs and final answers remain schema checked around the model call.
  input: supportInput,
  output: supportOutput,
  model: createCommerceModel("support"),
  instructions: "Answer order questions using the read-only order lookup tool.",
  // Only explicitly listed application tools are available to the agent.
  tools: [lookupOrder, cancelOrder, orderStatus],
  middleware: [todoListMiddleware()],
  checkpointer: orderCheckpoints,
  store: orderMemory,
  // Bound both tool use and total execution time.
  limits: { maxSteps: 4, maxToolCalls: 4, timeoutMs: 60_000 },
  stateProfile: "agents",
  client: { public: true, state: ["todos"] },
  chat: { input: "message", output: "answer" },
  controls: ["steer", "follow-up", "stop", "approve"],
});

export default orderSupport;
```

## Keep uncertain work visible

Each execution segment has immutable run state. A settled segment returns its thread to idle when no
approval or follow-up remains; approval and worker interruption stay visible. Lost responses are
reconciled through scoped receipts. Claim expiry, generation loss, or an uncertain external effect
never causes automatic restart.

## Keep interrupted nodes safe to re-enter

LangGraph starts an interrupted node again when its thread resumes. RELKIT binds the reply to the
persisted waiting revision, admits it once, and fences competing workers, but it cannot make an
arbitrary database write, payment, email, or third-party request exactly once. Place the interrupt
before an irreversible effect, or make the effect idempotent with a durable business key or a
transaction that your application owns.

Every protected thread operation requires current resource authorization and verified ownership.
Knowing a thread, run, checkpoint, or operation ID grants nothing.

---

# Define a tool
Source: https://relkit.dev/docs/modules/ai/tools

A tool names an action an AI client can request, such as looking up an order or cancelling it. Use `defineTool` to name the action, explain when to use it, and point it at an existing function.

Function-backed tools use the lean app's `@relkit/app` authoring facades; they need no native
model SDK. Choose [native agent installation](/guides/ai/build-an-offline-agent) only for model execution,
or [MCP installation](/docs/modules/ai/mcp) only for that external protocol.

> **Before you begin**
>
> Use an existing application with a function to expose. [Create an
> application](/docs/learn/create-an-app) if you need one.

## Scaffold a function-backed tool

From an [installed minimal app](/docs/learn/create-an-app) with its `hello` service and function:

```sh
bun run relkit add tool greeting-lookup --service hello \
  --target hello --side-effect read --approval never
```

Creates `src/services/hello/tools/greeting-lookup.tool.ts` using the function's `.asTool()` method.
Select a callable function in the same service; the CLI accepts its ID, binding, or filename.
The default side-effect class is `read`, and approval defaults to `never`. Choose accurate policies
before exposing a real operation. The tool remains internal to the domain, and adding it does not
automatically add it to an existing agent.

To scaffold the function and tool together, use `--create-function` instead of `--target`:

```sh
bun run relkit add tool find-order --service hello --create-function find-order
```

This creates `src/services/hello/functions/find-order.function.ts` and `src/services/hello/tools/find-order.tool.ts`,
and exposes the new function through the service. Without either option, the interactive prompt
lists existing functions and offers **Create a new function**. When no functions exist, it asks
for a new function name directly.

For every tool scaffolding flag, see the [tool command reference](/docs/api/cli#relkit-add-tool-name).

1. ## Define the input and output

    Declare `input` and `output` on the function the tool will call:

    ```ts title="src/services/hello/functions/hello.function.ts"
    /** Returns a validated named greeting and logs each invocation through RELKIT's request context. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const hello = defineFunction({
      id: "hello.greet",

      input: z.object({ name: z.string().min(1).default("world") }),
      output: z.object({ message: z.string() }),

      /**
       * Logs the greeting invocation and returns the validated greeting response.
       * @param input - Validated name from the function schema.
       * @param context - RELKIT invocation context owning structured logging.
       * @returns Greeting response matching the output schema.
       */
      handler: async ({ name }, context) => {
        context.log.info("hello invoked", { name });

        return { message: `Hello, ${name}!` };
      },
    });

    export default hello;
    ```

    Here, the tool will accept `{ "name": "Ada" }` and return `{ "message": "Hello, Ada!" }`. Input defaults and validation come from the same function schemas.

2. ## Define the tool

    This tool calls the [greeting function](/docs/modules/ai/function-tools#define-the-function). Save it under your domain's `tools` directory:

    ```ts title="src/services/hello/tools/lookup.tool.ts"
    /** Checks lookup.tool.ts through the supported public RELKIT APIs. */
    import { defineTool } from "@relkit/app/tools";
    import hello from "@app/services/hello/functions/hello.function.js";

    export default defineTool({
      id: "hello.lookup",
      target: hello,
      description: "Read a greeting for a supplied name",

      sideEffect: "read",
      approval: "never",
      timeoutMs: 2_000,
    });
    ```

    `defineTool` has no separate `input` or `output` options: it inherits both from `target`. You do not repeat the schemas in the tool definition. To expose a different input or output, define a function with those schemas and use it as the target.

    Native LangChain `tool()` values can appear directly in an agent's `tools` array. Use `defineTool` or
    `.asTool()` when the action should run through a RELKIT function or needs RELKIT side-effect, approval,
    timeout, or MCP metadata. Do not wrap native tools in a public adapter. Use the
    [RELKIT tool reference](/docs/api/tools#definetool) for the supported policy fields.

    Give the tool a stable `id` and a specific `description`: explain what it does, when to use it, and what it returns. “Look up an order by ID” is more useful than “Handle orders.”

    If you prefer to start from the function, [`hello.asTool(...)`](/docs/modules/ai/function-tools) creates the same kind of tool. Choose one form for each tool.

## Describe the action accurately

| `sideEffect` | Use it for                                                 |
| ------------ | ---------------------------------------------------------- |
| `none`       | A calculation that does not read or change external state. |
| `read`       | Reading data without changing it.                          |
| `write`      | Changing application data.                                 |
| `external`   | An external action, such as sending a message.             |

`approval` is also required. Use `never` for an operation that may run without a separate decision, `on-write` to require approval for `write` and `external`, or `always` to require approval on every call. See [tool approvals](/docs/modules/ai/approvals) before exposing sensitive actions.

The `approval` option on `defineTool` is a policy string, not a function. For a custom decision, pass a synchronous or asynchronous callback to [`tool.invoke(input, { approval })`](/docs/modules/ai/approvals#use-an-approval-callback).

Set `timeoutMs` to limit how long the tool can run. It is optional in the tool API, but the current [MCP runtime requires an explicit value](/docs/modules/ai/mcp#choose-which-tools-to-expose). Check permissions inside the target function even for read-only tools.

## Make the tool available

Add the tool to an [agent's `tools` array](/docs/modules/ai/agents) to let that agent call it.

Tools are also available through [MCP](/docs/modules/ai/mcp) by default. Set `mcp: false` in the tool options to keep a tool out of MCP; it can still be used by your RELKIT agents.

---

# Authentication overview
Source: https://relkit.dev/docs/modules/auth

Authentication tells your application who is making a request. A session lets that caller make subsequent
requests without entering credentials again. Authorization decides what that identity may do: read an
order, join an organization, or change another user's settings. Signing in does not grant those permissions.

> **Start here**
>
> Start with [Add email and password sign-in](/guides/auth/email-password-sign-in) to register a
> user and verify a protected endpoint. Use the [Better Auth reference](/docs/api/better-auth) for
> the integration's exact options and types.

Keep these concepts separate from the authentication library you choose. An auth service owns identity
and session integration; business domains own permission checks and product behavior. Your routes and
clients connect those responsibilities without becoming a second authentication system.

## Pre-setup

For a new app, first complete [PostgreSQL in local Docker](/docs/modules/database/local-docker).
Authentication shares that database. If your app already uses another supported dialect,
keep it and pass the matching `--database-dialect` below.

1. **Scaffold the authentication service**

    Run once in the backend root when it has no auth service:

    ```sh title="Terminal — application root"
    bun run relkit add auth --adapter better-auth --database-dialect postgresql
    ```

    The command installs the selected packages, adds auth tables to the existing Drizzle schema,
    creates the auth service and `/api/auth` mount, and merges environment declarations. It does
    not generate a secret, apply migrations, or protect your business endpoints.

2. **Configure environment values**

    Keep these fields in `src/platform/env.ts` and its existing import in `relkit.config.ts`.
    This minimal inline configuration shows the required contract; merge rather than replacing
    your application's other fields and settings:

    ```ts title="relkit.config.ts — equivalent inline environment"
    /** Auth and Drizzle share one database; credentials remain in the backend environment. */
    import { defineApp, defineEnv, env } from "@relkit/app/config";

    export default defineApp({
      env: defineEnv({
        DATABASE_URL: env.secret(),
        BETTER_AUTH_URL: env.url(),
        BETTER_AUTH_SECRET: env.secret(),
      }),
    });
    ```

    Retain `DATABASE_URL` from the Docker setup. Generate a secret once:

    ```sh title="Terminal — application root"
    openssl rand -base64 32
    ```

    Add `BETTER_AUTH_URL=http://127.0.0.1:3000` and `BETTER_AUTH_SECRET=<generated value>` to your
    untracked `.env.local`, using your actual backend origin and generated secret. Keep the same
    secret across restarts. Better Auth reads it from the backend process environment; `defineEnv`
    validates it but does not inject parsed values into native auth options. Never expose it to the frontend.

3. **Apply auth tables and verify**

    ```sh title="Terminal — application root"
    bun run relkit env check
    bun --bun drizzle-kit generate --name=add-auth
    ```

    Review the generated changes, preserving existing tables and applied migrations. Then run:

    ```sh title="Terminal — application root"
    bun run relkit db migrate
    bun run check
    bun run typecheck
    bun run dev
    ```

    Continue with [Better Auth options](/docs/modules/auth/better-auth) and
    [protecting application routes](/docs/modules/auth/protect-routes). Verify sign-up and cookies
    using the [sign-in guide](/guides/auth/email-password-sign-in); its standalone SQLite sample is
    an alternative, so keep your PostgreSQL service and migrations when adapting its requests.

    Update application HTTP fixtures to use `@relkit/testing/better-auth`, including fixtures for
    public routes. Supply explicit test environment values and an isolated, migrated database;
    the harness does not inherit `.env.local`. See [testing authentication](/docs/modules/auth/testing).

## Organize authentication by responsibility

| What you need to add                          | Where it belongs                                                      | Continue with                                                                                               |
| --------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Sign-in methods, session policy, auth plugins | `src/services/auth/service.ts`, using the chosen integration          | [Better Auth service](/docs/modules/auth/better-auth)                                                       |
| Auth tables, connection, schema changes       | The existing database domain and migration tooling                    | [Database integration](/docs/modules/database/better-auth)                                                  |
| Public authentication endpoints               | A filesystem route under `src/routes/`                                | [Protect routes](/docs/modules/auth/protect-routes)                                                         |
| The current caller in a business operation    | The owning domain's function                                          | [Read sessions](/docs/modules/auth/sessions)                                                                |
| Ownership, roles, organization access         | The business operation that reads or changes the resource             | [Authorization boundaries](/docs/modules/auth/protect-routes#enforce-permissions-in-the-business-operation) |
| Sign-up forms and sign-in state               | Your frontend and auth client's public configuration                  | [Clients](/docs/modules/auth/clients)                                                                       |
| Background work on behalf of a user           | The owning job/function, with an explicit trusted identity and policy | [Sessions outside HTTP](/docs/modules/auth/sessions#work-without-an-http-request)                           |

This separation keeps identity plumbing out of every domain. Changing an auth provider's settings does
not require moving Orders functions; changing an Orders permission rule does not require rewriting the
login route. See [Service organization](/docs/modules/service/organization) for the wider application layout.

## Understand the request boundary

```text
Browser → auth endpoint → authentication service → persisted identity/session
Browser → application endpoint → session check → business function → permission check → data
```

The auth endpoint owns credential validation and session cookies. Application endpoints either allow
anonymous callers or require a session. A business function uses the verified identity to enforce its
own rules. Never treat an arbitrary input field, header, or client-side “logged in” flag as verified identity.

Public service functions can also be called outside HTTP. Protecting a route does not secure every job,
tool, or direct invocation of the same function. Put the permission decision at the operation boundary
and explicitly define which trusted non-HTTP callers may invoke it.

## Choose the current integration

[Better Auth](/docs/modules/auth/better-auth) is the supported auth service integration today. It uses the
application's [Drizzle service](/docs/modules/database/drizzle), mounts a native HTTP handler, and supplies
`context.auth.getSession()` to application functions. Other auth libraries do not gain this wiring just
because their file is named `service.ts`; these guides do not promise a universal provider API.

The getting-started concepts apply generally. Better Auth options, cookie behavior, plugins, and table
requirements belong to the integration guides. For a complete local flow, follow
[Your first auth flow](/guides/auth/email-password-sign-in).

After changing service or route registration, run from your app root:

```sh
bun run check
bun run typecheck
```

These check discovery and types, not real credentials, schema migrations, or browser cookie behavior.

## Find the guide for your task

**Configure the integration and secrets:**

[Better Auth service](/docs/modules/auth/better-auth).

**Read a nullable, request-bound identity:**

[Sessions](/docs/modules/auth/sessions).

**Require authentication and enforce permissions:**

[Protect routes](/docs/modules/auth/protect-routes).

**Build sign-up, sign-in, and sign-out flows:**

[Clients](/docs/modules/auth/clients).

**Add providers, plugins, fields, and production policy:**

[Customize authentication](/docs/modules/auth/customization).

**Verify sessions and failure cases:**

[Testing](/docs/modules/auth/testing).

**Add authentication to an existing app:**

[Your first auth flow](/guides/auth/email-password-sign-in).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/services` API](/docs/api/services)

- [`examples/auth-drizzle/src/services/auth/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/auth/service.ts)

---

# Better Auth service
Source: https://relkit.dev/docs/modules/auth/better-auth

Use `defineBetterAuthService` to add Better Auth credentials, accounts, and sessions to your application. RELKIT discovers it, activates
the application's Drizzle connection first, and passes that native client to Better Auth's Drizzle
adapter. Better Auth handles credentials, accounts, sessions, and its HTTP protocol.

The current integration requires exactly one Drizzle service, one Better Auth service, and one
filesystem `ALL` catch-all mount for that auth handler. Do not construct a second connection for auth
or register the descriptor as a member of an ordinary `defineService`.

## Pre-setup

Use [authentication setup](/docs/modules/auth#pre-setup) to start local Docker PostgreSQL,
declare the database/auth fields with `defineEnv`, and supply a stable secret before startup.
If you completed that scaffold, skip installation below and customize the existing files.
Existing SQLite/MySQL applications keep their dialect and applied migration history.

1. ## Install compatible packages

    Authentication is optional in a minimal app. Choose one setup path from the backend root.
    Keep existing database tables, patches and overrides when merging these fields.

    **CLI**

    ### Scaffold the auth baseline

    ```sh title="Terminal — application root"
    bun run relkit add auth --adapter better-auth --database-dialect postgresql
    ```

    This creates `src/services/auth/service.ts` and `src/routes/api/auth/[[...auth]]/route.ts`,
    merges auth environment declarations, and installs the selected adapter, native SDKs,
    declaration peers and repairs. It reuses the existing Drizzle service or creates one when absent.
    `--database-dialect` must match an existing database; when none exists, it chooses the new dialect.

    For an existing database, the scaffold adds `schema/auth.ts` and exports its tables from the
    schema index. Review those additions, preserving business tables and applied migrations.
    Existing auth table names cause a collision instead of being overwritten. The scaffold does not run migrations,
    generate a secret, or protect business routes. Configure those before accepting sign-ins.

    Run this once when the app has no auth service. If it already exists, edit its service and mount.
    With `--no-install`, run `bun install` and `bun run check` before continuing. See the
    [auth command reference](/docs/api/cli#relkit-add-auth) and
    [complete sign-in guide](/guides/auth/email-password-sign-in).

    **Manual**

    Install the following packages before creating the service and mount below:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    Before installing, merge these selected declaration repairs into the existing package manifest, preserving unrelated overrides:

    ```json
    {
      "overrides": {
        "@better-fetch/fetch": "1.3.2"
      },
      "pnpm": {
        "overrides": {
          "@better-fetch/fetch": "1.3.2"
        }
      }
    }
    ```

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/better-auth@0.8.4 @relkit/drizzle@0.8.3 better-auth@1.7.1 drizzle-orm@1.0.0-rc.5-169397b
    bun add --dev @cloudflare/workers-types@4.20250121.0 create-relkit@0.8.8 drizzle-kit@1.0.0-rc.5-ab785fc
    ```

    The selected Drizzle version also needs the release's declaration repair. The development-only `create-relkit` package supplies its exact asset; a dependency cannot register Bun patches for its consumer.

    ```sh
    mkdir -p patches
    cp node_modules/create-relkit/dist/patches/drizzle-orm.patch patches/drizzle-orm@1.0.0-rc.5-169397b.patch
    ```

    Merge this entry into the application's existing `patchedDependencies`, preserving other patches. Keep the asset in source control:

    ```json
    {
      "patchedDependencies": {
        "drizzle-orm@1.0.0-rc.5-169397b": "patches/drizzle-orm@1.0.0-rc.5-169397b.patch"
      }
    }
    ```

    Then apply the registered repair before check/typecheck:

    ```sh
    bun install
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    These are owner-specific compatible versions, not a claim about the latest upstream release.
    The default setup uses Docker PostgreSQL. The service API also supports the existing SQLite
    example; its database dialect, schema, and migrations must stay consistent. See
    [Database setup](/docs/modules/database/define).

    > **Before you begin**
    >
    > Before enabling authentication, follow [Integrate Better Auth](/docs/modules/database/better-auth)
    > to add its tables to the existing schema and generate/apply their migrations. Registering a
    > service does not create tables or migrate an existing database.

    The backend requires no React package. `@relkit/better-auth` contains lazy declarations and session
    types; generated servers select `@relkit/better-auth/drizzle` for native activation. Applications
    using the native Effect layers or `activateBetterAuthService` directly import them from that same
    `/drizzle` entrypoint. React belongs to `@relkit/better-auth/react` and is installed only for a
    selected React client. Better Auth and Drizzle remain application-owned SDK dependencies; their
    actual upstream dependencies are retained.

    The generated setup includes the Better Fetch declaration override and application-owned Drizzle
    patch. `relkit add auth` plans those selected fields automatically; manual consumers must merge them
    and reinstall. The Cloudflare package above supplies the
    real `D1Database` type imported by this SDK's declarations; it is a development requirement, not a
    Cloudflare runtime selection. These additions belong only to projects selecting authentication.

2. ## Define the service and environment

    Create `src/services/auth/service.ts`:

    ```ts title="src/services/auth/service.ts"
    /** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
    import { defineBetterAuthService } from "@relkit/better-auth";

    export default defineBetterAuthService({
      baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
      // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
      emailAndPassword: { enabled: true },
    });
    ```

    This enables email/password sign-in. The descriptor exposes a stable `handler`, not a native
    `betterAuth()` instance. It does not expose `auth.api`, an application-owned connection, or a login
    function to call through `context.services`.

    Add the environment fields to your existing configuration without replacing other settings:

    ```ts title="relkit.config.ts — equivalent inline environment"
    /** Auth and Drizzle share one database; credentials remain in the backend environment. */
    import { defineApp, defineEnv, env } from "@relkit/app/config";

    export default defineApp({
      env: defineEnv({
        DATABASE_URL: env.secret(),
        BETTER_AUTH_URL: env.url(),
        BETTER_AUTH_SECRET: env.secret(),
      }),
    });
    ```

    Better Auth reads `BETTER_AUTH_SECRET` from the server process environment when it activates. The
    example deliberately has no hard-coded secret or secret default. Keep the Docker setup's
    `DATABASE_URL` and the stable auth values in your backend's untracked `.env.local`. Generate a
    secret once if you have not completed the pre-setup:

    ```sh
    openssl rand -base64 32
    ```

    Set `BETTER_AUTH_SECRET` to that value and `BETTER_AUTH_URL` to your backend origin, locally
    `http://127.0.0.1:3000`. Keep these fields in the existing `src/platform/env.ts` when the app
    imports its environment instead of declaring it inline. SQLite apps retain `DATABASE_PATH`
    instead of the PostgreSQL `DATABASE_URL` field.

    Store a stable, strong secret in your deployment's secret manager; use the same value across replicas
    and restarts. Do not regenerate it on every startup. Never put it in a browser bundle, a public
    environment variable, source control, logs, or a copied example configuration.

    Auth options are a plain object, not an `({ env })` factory. Declaring a field in `defineEnv` validates
    the RELKIT environment; it does not inject parsed values into that object or replace `process.env`.
    The URL here is read during module evaluation, so supply it before loading the app. The secret uses
    Better Auth's native process-environment lookup. A test harness `env` override alone does not set that
    process value; see [Testing](/docs/modules/auth/testing).

3. ## Mount the native handler

    ```ts title="src/routes/api/auth/[[...auth]]/route.ts"
    /** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
    import { defineRoute } from "@relkit/app/routes";
    import auth from "@app/services/auth/service.js";

    export const ALL = defineRoute({
      handler: auth.handler,
      auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
    });
    ```

    RELKIT derives `/api/auth` from this route and preserves Better Auth's native responses, including
    cookies. The `auth.protected` paths are application paths that require a session, not endpoints created
    by Better Auth. See [Protect routes](/docs/modules/auth/protect-routes) for matching and authorization rules.

    Do not wrap `auth.handler` in a function or another handler. Mount the recognized handler directly so
    the compiler can associate the auth service and its base path. You do not manually call
    `activateBetterAuthService` in normal application startup. Calling the descriptor handler before
    activation returns HTTP `503`; importing the descriptor is not a standalone auth server.

## Use this auth service from the frontend

Once the service and `/api/auth` mount are running, use Better Auth's browser client for sign-in.
First complete the [frontend auth installation](/docs/modules/auth/clients#create-a-browser-auth-client):

```ts title="src/auth-client.ts — frontend"
import { createAuthClient } from "better-auth/client";

// Browser code: use the public backend origin, never the server secret or service.
export const authClient = createAuthClient({
  baseURL: "http://127.0.0.1:3000",
  basePath: "/api/auth",
  fetchOptions: { credentials: "include" },
});

export async function signIn(email: string, password: string) {
  const { data, error } = await authClient.signIn.email({ email, password });
  if (error !== null) throw new Error(error.message ?? "Sign-in failed");
  return data;
}
```

`emailAndPassword` on the service enables this `signIn.email` operation. Keep the public URL and
mount aligned with your backend, allow the browser to manage session cookies, and handle rejected
requests in the calling UI. These native auth endpoints are not RELKIT-generated RPC operations.
Never import the server service, database, or secret into the browser.

For application route hooks after sign-in, use
[`BetterAuthRelkitClientProvider`](/docs/api/better-auth#betterauthrelkitclientprovider) as shown in
[React authentication](/docs/modules/client/authentication). Follow the
[sign-in guide](/guides/auth/email-password-sign-in) for the complete flow.

## Know which settings RELKIT owns

| Setting                       | Owner and behavior                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `database`                    | Reserved: supplied from the single Drizzle service; cannot be passed here                         |
| `basePath`                    | Reserved: derived from the auth mount; cannot be passed here                                      |
| `baseURL`                     | Your public backend origin; configure it for each environment                                     |
| `secret`, native auth options | Better Auth settings; this example uses its environment lookup for the secret                     |
| `drizzle`                     | Optional adapter settings, including schema mapping; provider is derived from the service dialect |
| Connection disposal           | The Drizzle service's `dispose` callback                                                          |

Better Auth writes through the native adapter, bypassing RELKIT portable CRUD, generated Zod parsers,
and operation overrides. Do not use a table override as an auth policy or expose credential/session
tables through generic CRUD routes. See [Database integration](/docs/modules/database/better-auth).

Run `bun run check` and `bun run typecheck`, then verify a real sign-up and protected request using
[Your first auth flow](/guides/auth/email-password-sign-in). Continue with [Customization](/docs/modules/auth/customization)
before exposing a deployment to users.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/config` API](/docs/api/config)

- [`examples/auth-drizzle/src/services/auth/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/auth/service.ts)

---

# Clients and sign-in flows
Source: https://relkit.dev/docs/modules/auth/clients

Use Better Auth's browser client to sign users up, sign them in, and manage their sessions. Use the
[RELKIT generated client](/docs/modules/http/generated-clients) for your application's function-backed routes.
They serve different APIs; mounting auth does not generate typed RELKIT methods for its raw endpoints.

## Create a browser auth client

> **Before you begin**
>
> First complete the backend's [Better Auth setup](/docs/modules/auth/better-auth). In the separate
> frontend package, install the selected native client SDK and its declaration requirements; these
> commands do not install a backend or enable authentication by themselves.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

Before installing, merge these selected declaration repairs into the existing package manifest, preserving unrelated overrides:

```json
{
  "overrides": {
    "@better-fetch/fetch": "1.3.2"
  },
  "pnpm": {
    "overrides": {
      "@better-fetch/fetch": "1.3.2"
    }
  }
}
```

From this guide's application/package root, install only its selected requirements:

```sh
bun add better-auth@1.7.1
bun add --dev @cloudflare/workers-types@4.20250121.0
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

For RELKIT's React convenience leaf, use the separate [React authentication setup](/docs/modules/client/authentication).

That setup includes a copyable `AuthProvider` connecting the native session hook to RELKIT's
private query cache. Start with the [Frontend guide](/guides/frontend/connect-react) for the shared
contract and provider workflow; auth endpoints themselves use the native client below.

The framework-independent client and a sign-in action are:

```ts title="src/platform/auth-client.ts — browser code"
import { createAuthClient } from "better-auth/client";

// Browser code: use the public backend origin, never the server secret or service.
export const authClient = createAuthClient({
  baseURL: "http://127.0.0.1:3000",
  basePath: "/api/auth",
  fetchOptions: { credentials: "include" },
});

export async function signIn(email: string, password: string) {
  const { data, error } = await authClient.signIn.email({ email, password });
  if (error !== null) throw new Error(error.message ?? "Sign-in failed");
  return data;
}
```

Use your actual public backend origin instead of the loopback URL. `basePath` on this **client** must
match the filesystem auth mount; it is not the reserved server-service option. Do not import
`src/services/auth/service.ts`, database code, or server secrets into the browser. A public backend URL is
configuration, not a credential.

The action checks Better Auth's returned `error` before using `data`. Your UI should also handle
rejected requests, display an appropriate failure, and clear loading state after both success and
failure. Do not log passwords, cookies, or the complete auth response.

## Build the account flow

With email/password enabled, the native client maps these operations to the mounted API:

| User action             | Client method             | Native endpoint under `/api/auth` | Main input                  |
| ----------------------- | ------------------------- | --------------------------------- | --------------------------- |
| Create an account       | `authClient.signUp.email` | `POST /sign-up/email`             | `name`, `email`, `password` |
| Sign in                 | `authClient.signIn.email` | `POST /sign-in/email`             | `email`, `password`         |
| Read the native session | `authClient.getSession`   | `GET /get-session`                | No credentials in the body  |
| Sign out                | `authClient.signOut`      | `POST /sign-out`                  | No account password         |

The example enables automatic sign-in after a successful sign-up and does not require email
verification. If you change those policies, show the verification/sign-in step instead of assuming
every successful sign-up already has an active session. See [Customization](/docs/modules/auth/customization).

Let the browser store and send the session cookie. Do not copy the session token into local storage
or manually construct a `Cookie` header in browser JavaScript. Use Better Auth's sign-out endpoint to
invalidate the session; clearing a UI flag alone does not sign a user out on the server.

After sign-in, call your public `/session` operation or protected `/account/profile` route to verify
the application sees the same identity. `GET /session` is the example's small application response;
`GET /api/auth/get-session` is Better Auth's native session response. They are not interchangeable shapes.

## Keep cookies and origins aligned

The simplest local flow serves the page and API from `http://127.0.0.1:3000`. Use that hostname
consistently: switching between `localhost` and `127.0.0.1` changes the host to which cookies belong.

For a separate frontend origin, configure all three boundaries:

1. The client sends requests to the public backend URL with credentials included.
2. Better Auth's `trustedOrigins` allows the exact frontend origin for the auth flow.
3. The HTTP server or gateway supplies credentialed CORS for that origin, including preflight handling.

`trustedOrigins` is not CORS configuration, and CORS does not override cookie domain, `SameSite`, or
secure-cookie rules. Do not use a wildcard allowed origin with credentialed requests or disable
CSRF/origin checks to work around a configuration error. Test real browser requests over your intended
HTTPS domains; the in-process harness does not enforce browser cookie policy.

When using server-side rendering, forward only the current incoming request's relevant credentials
to the correct backend. A server-side fetch does not inherit the user's browser cookie jar. Likewise,
any auth response cookies must reach the browser through your framework's supported response handling.
Never share a mutable cookie/header object across users in a long-lived server client.

## Do not confuse bearer headers with authentication

After [installing the RELKIT client](/docs/modules/client), its transport can mutate request headers:

```ts title="src/platform/browser-client.ts — transport headers only"
import { createClient } from "@relkit/client";

export const bearerHeaders = new Headers();
export const client = createClient({ baseUrl: "http://127.0.0.1:3000", headers: bearerHeaders });

export function setBearerToken(token?: string): void {
  if (token === undefined) bearerHeaders.delete("authorization");
  else bearerHeaders.set("authorization", `Bearer ${token}`);
}
```

This example does **not** enable Better Auth bearer-token support. Adding an `Authorization` header
does not teach the server to validate it, and a Better Auth session is not automatically a JWT.
If you need non-cookie clients, configure and test the corresponding native auth capability on the
server and its client integration. Keep cookie authentication as the verified flow in this example.

For a framework-free browser demonstration, run `examples/auth-drizzle` using its README and open the
served page. The page uses the same native HTTP endpoints. For a reproducible command-line flow,
continue with [Your first auth flow](/guides/auth/email-password-sign-in).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/client` API](/docs/api/client)

- [`examples/auth-drizzle/src/platform/auth-client.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/platform/auth-client.ts)
- [`examples/auth-drizzle/public/index.html`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/public/index.html)

---

# Customize authentication
Source: https://relkit.dev/docs/modules/auth/customization

Configure sign-in providers, plugins, and session policy on your existing authentication service. Except for RELKIT's reserved `database` and `basePath`, the options follow
the installed Better Auth API. The `drizzle` option configures its adapter separately.

> **Before you begin**
>
> Before using this guide, complete [Better Auth installation and
> configuration](/docs/modules/auth/better-auth) and apply the database migrations. The minimal app
> does not include the optional auth SDK.

The executable example starts with email/password only:

```ts title="src/services/auth/service.ts"
/** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
import { defineBetterAuthService } from "@relkit/better-auth";

export default defineBetterAuthService({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
  // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
  emailAndPassword: { enabled: true },
});
```

This page identifies the configuration points and work each change requires. The example does not
pretend to configure an email provider, OAuth credentials, organization management, or an admin system.
Typecheck against your installed Better Auth version and test each enabled flow before publishing it.

## Configure sign-in and email delivery

| Requirement                         | Better Auth option                               | Additional work                                                                                 |
| ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Enable email/password               | `emailAndPassword.enabled`                       | Sign-up/sign-in UI, password policy, abuse protection                                           |
| Require verified email              | `emailAndPassword.requireEmailVerification`      | Verification delivery, callback page, expired-link handling                                     |
| Send verification messages          | `emailVerification.sendVerificationEmail`        | Implement the async delivery callback using its supplied user and verification URL              |
| Choose verification delivery timing | `emailVerification.sendOnSignUp`, `sendOnSignIn` | Ensure the UI explains the resulting flow                                                       |
| Send password reset messages        | `emailAndPassword.sendResetPassword`             | Implement delivery and a reset page; test token expiry and reuse                                |
| Social sign-in                      | `socialProviders`                                | Server-only provider credentials, registered callback URLs, client flow, account-linking policy |
| Extend authentication behavior      | `plugins`                                        | Required tables/migrations, plugin options, and any matching client plugin                      |

Enabling verified-email sign-in without delivering verification messages can lock users out. These
callbacks are native Better Auth callbacks, not RELKIT function handlers: they do not receive a RELKIT
invocation context or automatically inherit declared job/resource dependencies. Keep delivery failure
handling explicit. Do not log verification/reset URLs or tokens as a substitute for sending them.

For social providers, register the callback URL for the actual public base URL and mounted auth path,
using the provider's required endpoint. An email match alone should not become an improvised
account-linking rule in application code. Keep provider/client secrets on the server and test cancelled,
denied, and failed callbacks as well as successful sign-in.

## Customize the persisted data model

The example's auth tables are ordinary Drizzle definitions owned by the database domain:

```ts title="src/services/database/schema/index.ts"
/** Declares native Better Auth SQLite user/session/account/verification tables, retaining timestamp modes and account uniqueness. */
import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";

const timestamps = {
  createdAt: integer({ mode: "timestamp" }).notNull(),
  updatedAt: integer({ mode: "timestamp" }).notNull(),
};

export const user = sqliteTable("user", {
  id: text().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  emailVerified: integer({ mode: "boolean" }).notNull(),
  image: text(),
  ...timestamps,
});

export const session = sqliteTable("session", {
  id: text().primaryKey(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
  token: text().notNull().unique(),
  ipAddress: text(),
  userAgent: text(),
  userId: text().notNull(),
  ...timestamps,
});

export const account = sqliteTable(
  "account",
  {
    id: text().primaryKey(),
    accountId: text().notNull(),
    issuer: text().notNull(),
    providerId: text().notNull(),
    userId: text().notNull(),
    accessToken: text(),
    refreshToken: text(),
    idToken: text(),
    accessTokenExpiresAt: integer({ mode: "timestamp" }),
    refreshTokenExpiresAt: integer({ mode: "timestamp" }),
    scope: text(),
    password: text(),
    ...timestamps,
  },
  (table) => [uniqueIndex("account_issuer_account_id").on(table.issuer, table.accountId)],
);

export const verification = sqliteTable("verification", {
  id: text().primaryKey(),
  identifier: text().notNull(),
  value: text().notNull(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
  ...timestamps,
});
```

For additional stored user/session fields, coordinate three changes: Better Auth's model
`additionalFields` configuration, matching Drizzle columns, and a reviewed migration. Configure the
field's type, required/default behavior, and whether clients may supply it using the native field
options. Privileged fields such as roles must not be writable through public sign-up/profile input;
use server-controlled assignment and verify it with a negative test.

For renamed models or fields, align native `modelName`/`fields` settings with the adapter's schema
mapping. `drizzle.schema` changes the tables seen by the adapter, not the tables registered by the
database service or migrated by Kit. Preserve the auth model's required fields and constraints.

In the existing repository example, choose the database and generate a change after editing the schema:

```sh
export DATABASE_PATH=./auth.sqlite
bun run db:generate --name=auth-fields
```

Review the generated migration, test it on isolated data, and apply it with `bun run db:migrate`
before deploying code that relies on those fields. Other apps can use the underlying
[Drizzle Kit commands](/docs/modules/database/migrations). Adding options does not migrate a database.

Plugin requirements are additional to the four core tables. Use the plugin's installed types and
schema requirements rather than guessing columns. Better Auth's own schema generator expects native
configuration; the RELKIT service descriptor is not its activated `betterAuth()` instance. See
[Database integration](/docs/modules/database/better-auth) before choosing a schema-generation workflow.

Application profiles can instead live in a separate domain table referencing the auth user ID. That
keeps product-specific fields out of credential storage. Add the foreign keys and deletion policy your
model needs: the example's `userId` columns alone do not declare foreign-key constraints.

## Set session and revocation policy deliberately

Native `session.expiresIn` and `session.updateAge` are measured in seconds. Choose a session lifetime
and refresh policy appropriate to your application, and test them through the native session flow.
They are not the same as RELKIT's request-scoped memoization of `getSession()`.

Changing `session.cookieCache`, secondary storage, or session persistence can affect how quickly
revocation and user changes become visible. Do not enable a cache and assume the uncached example's
sign-out/revocation assertions still prove your chosen policy. Test old cookies, multiple sessions,
and privileged changes under the actual configuration.

Use auth-supported password, account, and session operations for lifecycle changes. Directly updating
an account's password column or deleting arbitrary auth rows bypasses the auth system's expected
hashing, linking, and cleanup behavior. RELKIT CRUD schemas and overrides do not enforce that behavior.

## Review deployment security

Before serving real users:

- Supply a stable server secret and the actual public HTTPS `baseURL`; restrict `trustedOrigins` to
  origins you control. Configure proxy trust only for your deployment's trusted proxy path.
- Preserve secure-cookie and CSRF/origin protections. Verify browser cookie scope, credentialed CORS,
  and callback destinations with the deployed hostnames.
- Configure Better Auth's `rateLimit` and any upstream limits deliberately. The native limiter defaults
  to production-only behavior; development tests do not establish production abuse protection. Choose
  shared limiting/storage when requests can reach multiple replicas.
- Keep authorization in business functions. An auth plugin's role model is not automatic authorization
  for your Orders or Billing APIs.
- Migrate first, use durable database storage, back up auth data securely, and test restores and upgrades.
  A container's disposable SQLite file is not a persistent account store.
- Keep credentials, reset links, session tokens, and provider tokens out of logs and generic CRUD APIs.
  Do not bundle the server auth descriptor into a client application.

See [Auth testing](/docs/modules/auth/testing) for the checks the repository actually runs and the deployment
cases you must add for your own policies.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/auth-drizzle/src/services/auth/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/auth/service.ts)
- [`examples/auth-drizzle/src/services/database/schema/index.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/database/schema/index.ts)

---

# Protect routes
Source: https://relkit.dev/docs/modules/auth/protect-routes

Require a session on selected application paths after mounting Better Auth. This HTTP admission
check answers “is the caller signed in?” It does not answer “may this caller access this order?”

> **Before you begin**
>
> Before using this guide, complete [Better Auth installation and
> configuration](/docs/modules/auth/better-auth) and apply the database migrations. The minimal app
> does not include the optional auth SDK.

## Mount the API and select protected paths

```ts title="src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "@app/services/auth/service.js";

export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
});
```

The optional catch-all owns `/api/auth` and nested auth endpoints. The named export must be `ALL`, and
the handler must be the registered service's `auth.handler`. It is a [raw handler](/docs/modules/http/raw-handlers),
not a typed function route. Native auth requests and responses do not become RELKIT OpenAPI/client
operations, and raw routes do not accept the function-route `request`, `responses`, or `rateLimit` options.

The `auth` option is accepted only for a recognized Better Auth handler. It cannot attach session
authentication to an arbitrary raw integration. Ordinary application routes continue to target
their owning service functions.

## Match exact paths and subtrees

Use absolute pathnames, without a query string or fragment:

| Protected pattern | Matches                                              | Does not match                                |
| ----------------- | ---------------------------------------------------- | --------------------------------------------- |
| `/account/*`      | `/account`, `/account/profile`, nested account paths | `/accounting`, `/session`                     |
| `/mcp`            | Exactly `/mcp`                                       | `/mcp/`, `/mcp/anything`                      |
| `/*`              | Application paths generally                          | The mounted authentication API remains public |

Use exact paths or a trailing `/*` for a subtree; this is not a general regular-expression language.
Patterns apply across HTTP methods. Duplicate patterns are normalized. If `protected` is omitted or
empty, the integration does not require sessions on other application paths. Unlisted paths remain
public unless another policy protects them.

`/orders/*` in the example does not create an Orders route. Likewise, protecting `/mcp` controls HTTP
admission to that path; it does not change [which tools MCP exposes](/docs/modules/ai/mcp).

The mounted auth base path and its descendants remain reachable even with `protected: ["/*"]`, so
callers can sign in. This exception is only the auth mount, not a configurable list of other public
paths. With broad protection, do not assume a custom `/sign-in` page or health endpoint is exempt;
choose explicit protected subtrees when those application paths need to stay public.

## Handle an unauthenticated request

The example protects this ordinary function route:

```ts title="src/routes/account/profile/route.ts"
/** Maps protected profile GET requests to the account service's native session observation. */
import { defineRoute } from "@relkit/app/routes";
import account from "@app/services/account/service.js";

export const GET = defineRoute({ target: account.session });
```

A request without a valid session receives HTTP `401`:

```json
{ "error": { "id": "UNAUTHORIZED", "message": "Authentication required" } }
```

RELKIT does not redirect the browser to a login page. Your frontend handles the response and offers a
sign-in flow. Preserve a safe, validated return destination if you redirect after authentication;
do not turn arbitrary input into an open redirect.

With the example running, verify admission from another terminal:

```sh
curl -i http://127.0.0.1:3000/account/profile
curl -i http://127.0.0.1:3000/session
```

Expect `401` for the protected profile and `200` with `authenticated: false` for the public session
operation. Then follow [Your first auth flow](/guides/auth/email-password-sign-in) to repeat the protected request
with a valid cookie.

## Enforce permissions in the business operation

Inside the function, read the verified identity with [session lookup](/docs/modules/auth/sessions), reject a
missing session if the operation requires one, and check the resource's owner, organization membership,
or applicable role before accessing it. Derive the caller's identity from the session, not from an
input such as `userId`, `organizationId`, or `role`.

For example, a request for another user's order still needs an ownership or membership check even
when both users are signed in. Use a constrained query or transaction appropriate to the operation,
and return an intentional declared error for denied access. Keep privileged role assignment server-owned.

Route protection applies to HTTP requests, not every direct invocation of its target. Jobs, tools,
agents, and other services can reach business operations through other entry points. A generated
database client is not row-level authorization, and a service export is not an access-control rule.
Do not publish an operation on another transport until its identity and permission boundary is defined.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/auth-drizzle/src/routes/api/auth/[[...auth]]/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/routes/api/auth/[[...auth]]/route.ts)

---

# Read sessions
Source: https://relkit.dev/docs/modules/auth/sessions

Read the current caller's session inside a function with `await context.auth.getSession()`. It returns the Better Auth session result or `null`. The result contains both the session record and
the user; the verified user ID is `session.user.id`, not a user-supplied request field.

> **Before you begin**
>
> Before using this guide, complete [Better Auth installation and
> configuration](/docs/modules/auth/better-auth) and apply the database migrations. The minimal app
> does not include the optional auth SDK.

## Read an optional session

The example's account operation supports anonymous and authenticated requests:

```ts title="src/services/account/functions/session.function.ts"
/** Reads the invocation's native session and returns validated authentication and user identity fields. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({}),
  output: z.object({ authenticated: z.boolean(), userId: z.string().optional() }),
  handler: async (_input, context) => {
    const session = await context.auth.getSession();
    return session === null
      ? { authenticated: false }
      : { authenticated: true, userId: session.user.id };
  },
});
```

Its output deliberately returns only an authentication flag and user ID. Do not return the complete
session object simply because it is available: auth records can contain tokens, IP addresses, and
other private data. Define the response your caller needs.

The compiler generates auth context types from the registered service's handler. Functions do not add
a `dependencies.auth` entry, import a global auth instance, or open a database connection. Run
`bun run check` after changing registration or type-affecting auth options, then `bun run typecheck`.
Inspect `.relkit/generated/context-registry.d.ts` if the expected auth type is missing; do not edit it.

## Choose public or authenticated access

The operation is registered by an ordinary domain service:

```ts title="src/services/account/service.ts"
/** Exposes native session observation as the account boundary used by profile and session routes. */
import { defineService } from "@relkit/app/services";
import session from "./functions/session.function.js";

export default defineService({ functions: { session } });
```

Its public route is:

```ts title="src/routes/session/route.ts"
/** Maps session GET requests to account session observation, including the explicit anonymous result. */
import { defineRoute } from "@relkit/app/routes";
import account from "@app/services/account/service.js";

export const GET = defineRoute({ target: account.session });
```

`GET /session` returns HTTP `200` with `{ "authenticated": false }` when signed out. The same function
is also mounted at `/account/profile`, which the auth mount protects; there, an anonymous request
receives `401` before the function runs. See [Protect routes](/docs/modules/auth/protect-routes).

Even behind a protected route, keep function behavior safe for a missing session. That function may
later have another caller or transport. For operations that require identity, reject a missing
session using an application [declared error](/docs/learn/concepts/errors), then verify permission before
reading or modifying protected records. A non-null session is not a role or ownership check.

## Understand request-scoped lookup

Session resolution uses the incoming request headers. It is lazy: a public operation that never
calls `getSession()` does not need that lookup. The HTTP runtime memoizes the lookup promise for the
request, including the lookup used by route protection. Concurrent reads within that request share
the result; this is not an application-wide identity cache.

Do not save the session in module state or reuse it for another request. A lookup already completed
in a request is not a fresh authorization check after revocation or account changes within that same
request. Use separate requests to verify lifecycle changes such as sign-out.

`context.auth.getSession()` returns data, not a native HTTP `Response`. Do not assume it forwards
Better Auth's `Set-Cookie` headers to the browser. Use the native [auth endpoints and client](/docs/modules/auth/clients)
for sign-in, sign-out, and session lifecycle flows.

## Work without an HTTP request

Jobs and direct invocations do not acquire a browser session merely because an auth service exists.
Without an active HTTP auth context, session lookup resolves to `null`. The Inspector is not a way
to impersonate a signed-in browser by supplying a `userId` input.

For deferred work, authorize the enqueue operation, record the relevant actor/resource identifiers
in the job's validated input, and define which permissions must be rechecked at execution time.
Do not put cookies, passwords, or session tokens in queued payloads. A client-supplied actor ID is
untrusted until the authenticated entry point validates it.

For unit tests, inject an explicit auth context; for request behavior, use the real HTTP harness in
[Auth testing](/docs/modules/auth/testing). Neither approach requires reading a developer's browser cookies.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/auth-drizzle/src/services/account/functions/session.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/account/functions/session.function.ts)

---

# Test authentication
Source: https://relkit.dev/docs/modules/auth/testing

Test sign-in and protected requests with an isolated database and the real authentication handler. A mocked
session is useful for a business permission test, but it does not prove sign-in, cookies, migrations,
or route protection work together.

> **Before you begin**
>
> Before using this guide, complete [Better Auth installation and
> configuration](/docs/modules/auth/better-auth) and apply the database migrations. The minimal app
> does not include the optional auth SDK.

## Test the complete local flow

The executable test migrates a temporary SQLite file before starting the application. It supplies
both RELKIT's parsed environment and Better Auth's process environment, then restores process values
and removes only its temporary directory after closing the application:

[Complete auth integration test](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/tests/auth.test.ts)

Import `createTestApplication` from `@relkit/testing/better-auth` for this database-backed auth
application. A database-only application uses `@relkit/testing/drizzle`; the general
`@relkit/testing` harness does not install either SDK. Keep the selected integration and native SDK
packages in the application's dependencies, as shown in [Better Auth setup](/docs/modules/auth/better-auth).

Run from the repository's `examples/auth-drizzle` directory:

```sh
bun test tests/auth.test.ts
```

The assertions cover:

- Applying the checked-in migration and safely applying it again.
- Anonymous access to public `/session` and rejection at protected `/account/profile`.
- Email/password sign-up, the resulting cookie, and authenticated application/native session reads.
- Sign-out followed by rejection of the old session cookie on a new request.
- Rejection of a wrong password and successful subsequent sign-in.

The HTTP harness does not store browser cookies automatically; the test forwards the returned cookie
explicitly. It does not read the developer's cookie jar or mutate `./auth.sqlite`.

## Keep test state isolated

Create the environment before loading the auth service: its `baseURL` option is evaluated when the
module loads, while the omitted secret uses Better Auth's process-environment lookup at activation.
Passing only `createTestApplication(..., { env: ... })` does not update that native process environment.

The selected test harness acquires isolated database and auth owners for each application and closes
them independently. It leaves the lazy descriptor's shared handler target untouched. Explicit
`activateBetterAuthService` calls outside this harness share the first activation by default; use
its isolated option when independently owning a borrowed database. Do not run process-environment
mutations concurrently within the same process.

The harness clock is not a promise that native Better Auth time or browser expiry is simulated. For
expiry/refresh policy tests, use a controlled configuration and time strategy appropriate to the native
library, then check the resulting HTTP behavior.

## Test business permissions separately

For a domain function, use [function testing](/docs/modules/operations/testing) with an explicit
`context.auth.getSession` result. Test at least an anonymous caller, the resource owner, and another
authenticated caller. Assert that denied requests do not read or mutate protected data.

Do not let a fake “authenticated” result bypass ownership or membership checks. If the operation is
reachable through jobs, tools, or direct invocation, test that transport's identity contract as well;
HTTP route protection is not the only entry point.

## Verify browser and deployment behavior

The native library relaxes origin checks in its test environment, and this harness is not a browser.
A passing Bun test does not prove production origin validation, HTTPS cookies, CORS, or OAuth redirects.
Run the application and exercise sign-up, sign-in, sign-out, and protected access in a real browser.

For your deployment, add checks for hostile origins, expired/revoked sessions, stable secrets across
replicas, password-reset and verification links, rate limits, and any enabled providers/plugins.
Run migration tests against the production dialect and an isolated database. Never point these tests
at live customer accounts.

## Diagnose common failures

| Symptom                                    | Check first                                                                                    |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Compiler rejects auth registration         | One Drizzle service, one auth service, and one recognized `ALL` catch-all mount                |
| Auth tables are missing                    | Same database path/schema for app and migrations; migration ran before startup                 |
| Service handler returns `503`              | Use runtime activation through the app, not the descriptor as a standalone server              |
| Sign-in succeeds but profile returns `401` | Cookie sent on the next request, consistent hostname, correct public URL and cookie policy     |
| Auth callback/origin is rejected           | Actual `baseURL`, mounted path, exact trusted origins, and provider callback registration      |
| `/session` reports signed out              | This is a public optional-session function; inspect whether the request carries a valid cookie |
| Session type is missing                    | Run `bun run check`, inspect the generated registry, then typecheck                            |
| A signed-in user sees another user's data  | Add/test business authorization; route protection only checks authentication                   |

Use status codes and redacted diagnostics during investigation. Do not print passwords, auth tokens,
or entire request headers to troubleshoot a cookie problem.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/testing` API](/docs/api/testing)
- [`@relkit/better-auth` API](/docs/api/better-auth)

- [`examples/auth-drizzle/tests/auth.test.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/tests/auth.test.ts)

---

# Caching overview
Source: https://relkit.dev/docs/modules/caching

A cache temporarily stores a value so later requests can reuse it without repeating the original work. Product prices, search results, and calculated summaries are common examples. Keep the original data in your database or another source you can read again.

Use caching when a lookup is expensive and a slightly older result is acceptable. Skip it when every request must see the latest value.

> **Start here**
>
> Start with [Cache product prices](/guides/caching/cache-product-prices) for installation, a
> working lookup, and verification. Use [Define a cache](/docs/modules/caching/define) for
> configuration and the [Cache reference](/docs/api/cache) for exact contracts.

## Pre-setup

Use Redis in local Docker. Start from an existing RELKIT app and a running Docker daemon.

1. **Install Redis and Docker support**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the requests profile**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Local Redis supplies the connection for the requests cache profile. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { redis } from "@relkit/redis";

    export default defineApp({
      env: defineEnv({}),
      cache: { requests: docker(redis()) },
      defaults: { cache: "requests" },
    });
    ```

    The examples use `profile: "requests"`. Docker supplies the Redis connection; this path adds
    no `defineEnv` fields. If a scaffold used a different profile, align its `profile` with this
    configuration. [Connected Redis](/docs/modules/caching/define) uses an explicit secret binding.

3. **Check and start after defining the cache**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

## The Caching API

Usually, caching means connecting a Redis client, choosing keys, serializing values, and checking for missing entries. With RELKIT, define the key and value shapes, give your function access, and use `getOrSet()` to load missing values.

| API                                          | What you use it for                                    |
| -------------------------------------------- | ------------------------------------------------------ |
| [`defineCache`](/docs/api/cache#definecache) | Define the cache's keys, values, and expiration time.  |
| `dependencies.cache`                         | Give a function access to a cache.                     |
| `context.cache.prices.getOrSet(key, load)`   | Reuse a saved value or load and save it when missing.  |
| `context.cache.prices.set(key, value)`       | Save or replace a value.                               |
| `context.cache.prices.delete(key)`           | Remove a value so the next lookup can load fresh data. |

You can use caches in event functions too, and in ordinary functions called by jobs and tools.

## Try it in your app

Follow the [cached-price example](/guides/caching/cache-product-prices) for the first working cache. It runs
with Docker Redis and no cloud credentials. Use [Define a cache](/docs/modules/caching/define) when you need
to choose keys, values, and expiration for your own data.

After the separate [Inspector setup](/docs/modules/operations/inspector), open **Cache** and select your cache
to see keys and their remaining lifetime. Choose **View value** to inspect a saved value.

---

# Define a cache
Source: https://relkit.dev/docs/modules/caching/define

Define a cache to name a stored value, describe its schema, and set how long it remains valid.

> **Before you begin**
>
> Start with an [existing application](/docs/learn/create-an-app). The cache definition uses the
> base app package; the provider configuration below adds the storage integration.

## Pre-setup

Complete [local Docker Redis setup](/docs/modules/caching#pre-setup) before using a cache.
It installs the provider and configures `cache.requests` and `defaults.cache` in `defineApp`.
Docker supplies its connection values; no new `defineEnv` fields are needed for that path.
Keep the definition's profile aligned with the configured one.

## Scaffold a cache

From the application root, with an existing `orders` service:

```sh
bun run relkit add cache Prices --service orders --provider redis --source docker
```

Creates `src/services/orders/cache/prices.cache.ts` and configures Docker Redis. Without provider flags,
a default/unique compatible cache profile is reused; otherwise Docker Redis is the fallback.

Edit the generated key/value schemas and lifetime for your data. Keep its generated `id` and
`profile`; the complete manual example below uses a different profile named `requests`.
For the full application workflow, follow [Cache product prices](/guides/caching/cache-product-prices).

**Choose a different cache provider**

Choose one configuration form when running the command:

| Selection                                  | Command options                               |
| ------------------------------------------ | --------------------------------------------- |
| Existing profile                           | `--profile requests`                          |
| Docker Redis                               | `--provider redis --source docker`            |
| Connected Redis                            | `--provider redis --source connected`         |
| Redis on an existing AWS/Pulumi deployment | `--provider redis --source aws`               |
| Connected Cloudflare KV                    | `--provider cloudflare-kv --source connected` |

Do not combine `--profile` with `--provider` or `--source`. AWS requires an already configured
AWS/Pulumi deployment; scaffolding does not provision it. Connected profiles add named environment
references and blank examples, not credentials. Docker startup is a separate
[post-add confirmation](/docs/modules/cli/add-artifacts#start-local-resources).
Declare the cache as a function dependency before using it.

For every cache scaffolding flag, see the [cache command reference](/docs/api/cli#relkit-add-cache-name).

The scaffold normally installs the selected owners and checks the app. With `--no-install`, run
`bun install` and `bun run check` before continuing. For manual descriptor/configuration setup,
complete [the selected adapter installation](/guides/caching/cache-product-prices#configure-caching) first;
connected Cloudflare uses [its own package](/docs/modules/integrations) instead of Docker Redis.

## Define the cache

Use `defineCache` in your app's domain directory. Edit the scaffolded file, or create
`src/services/orders/cache/prices.cache.ts` manually. This source shows the complete manual example:

```ts title="src/services/orders/cache/prices.cache.ts"
/** Declares integer SKU prices in the requests cache profile with a one-minute default and five-minute maximum TTL. */
import { defineCache } from "@relkit/app/cache";
import { z } from "@relkit/app/schema";

const prices = defineCache({
  id: "orders.prices",
  profile: "requests",
  key: z.object({ sku: z.string() }),
  value: z.number().int().nonnegative(),

  defaultTtlMs: 60_000,
  maxTtlMs: 300_000,
});

export default prices;
```

- `id` is the cache's stable, unique name.
- `key` describes how to identify a value. Here, `{ sku: "book" }` identifies one product's price.
- `value` describes what to store: a non-negative integer price in cents.
- `defaultTtlMs` is the lifetime in milliseconds when a write does not specify one. `60_000` means one minute.
- `maxTtlMs` is the longest allowed lifetime. Requests above this limit are rejected, not shortened.
- `profile` selects a physical cache configuration in `relkit.config.ts`. This example uses `"requests"`.

Both lifetime settings are optional. Set a default when data should expire; setting only `maxTtlMs` does not choose a lifetime for every write.

## Check your cache

Make sure the descriptor's `profile` matches its cache profile in `relkit.config.ts`. Keep the
scaffolded profile, or use `requests` for the manual example. The
[tutorial's configuration step](/guides/caching/cache-product-prices#configure-caching) shows that setup.

From your app's root, run:

```sh
bun run check
```

Next, [read and write values from a function](/docs/modules/caching/read-write).

---

# Expiration and invalidation
Source: https://relkit.dev/docs/modules/caching/expiration

Choose how long a cached value can be reused, and remove it when a relevant application change makes it stale.

> **Before you begin**
>
> Complete the [cache installation and
> binding](/guides/caching/cache-product-prices#configure-caching) first. The minimal app does not
> select a Redis runtime merely because a cache descriptor exists.

## Set a lifetime

A time to live (**TTL**) is how long a cached value can be reused. The prices cache uses one minute by default:

```ts title="src/services/orders/cache/prices.cache.ts"
/** Declares integer SKU prices in the requests cache profile with a one-minute default and five-minute maximum TTL. */
import { defineCache } from "@relkit/app/cache";
import { z } from "@relkit/app/schema";

const prices = defineCache({
  id: "orders.prices",
  profile: "requests",
  key: z.object({ sku: z.string() }),
  value: z.number().int().nonnegative(),

  defaultTtlMs: 60_000,
  maxTtlMs: 300_000,
});

export default prices;
```

To use a shorter lifetime for one write, call `await context.cache.prices.set({ sku: "book" }, 1200, { ttlMs: 10_000 })`. `getOrSet()` accepts the same options as its third argument when saving a newly loaded value.

TTL values must be positive integers in milliseconds. Here, a value above `300_000` is rejected. Reading a cached value does not restart its lifetime, and `getOrSet()` does not change an existing entry's TTL on a hit.

## Remove stale values after a change

When a product price changes, save the new price to your database first. Then call `await context.cache.prices.delete({ sku: "book" })`. The next `getOrSet()` call loads the new price.

This is **invalidation**: removing a cached copy because you know it may be outdated. It complements TTL; you do not have to wait for expiration after a known change. An event function can invalidate the cache after a product-update event too.

If results depend on a user, tenant, currency, or permissions, include those details in your key. Otherwise, one request can reuse another request's data.

## Test freshness

Test a missing entry, a hit, expiration, and deletion. Use a controllable clock in tests instead of waiting for a real minute.

After adding those tests, run from your app's root:

```sh
bun run test
```

Keep your database as the source of truth. A cache error is not a cache miss: decide whether your app should fail the request or read the original data when caching is unavailable.

---

# Read and write values
Source: https://relkit.dev/docs/modules/caching/read-write

Read a cached value, load it when missing, and write or remove entries through a function's declared cache client.

> **Before you begin**
>
> Complete the [cache installation and
> binding](/guides/caching/cache-product-prices#configure-caching) first. The minimal app does not
> select a Redis runtime merely because a cache descriptor exists.

## Load on a cache miss

Import your [cache](/docs/modules/caching/define) and add it to `dependencies.cache`. The name `prices` makes it available as `context.cache.prices`.

```ts title="src/services/orders/functions/get-price.function.ts"
/** Exercises the real prices dependency with a logged cache-miss producer and validated SKU/price results. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import prices from "@app/services/orders/cache/prices.cache.js";

const getPrice = defineFunction({
  id: "orders.get-price",

  input: z.object({ sku: z.string().min(1) }),
  output: z.object({ sku: z.string(), unitPriceCents: z.number().int().nonnegative() }),

  dependencies: { cache: { prices } },

  handler: async ({ sku }, context) => {
    const unitPriceCents = await context.cache.prices.getOrSet({ sku }, async () => {
      // Runs on a cache miss. Replace the demo price with your database lookup.
      context.log.info("price.loaded", { sku });
      return 1_000;
    });

    return { sku, unitPriceCents };
  },
});

export default getPrice;
```

`getOrSet()` returns the saved price when it exists—a **cache hit**. Otherwise, it runs the callback, saves the result, and returns it—a **cache miss**. In a real app, replace the demo's `1_000` with a database or API lookup.

Keep the callback safe to repeat. Do not use it to charge a customer or send an email; concurrent requests on different app instances may run it more than once.

## Read or write directly

Inside a handler with the same cache dependency, await the operation you need:

| Call                                              | Result                                                   |
| ------------------------------------------------- | -------------------------------------------------------- |
| `context.cache.prices.get({ sku: "book" })`       | The saved price, or `undefined` when missing or expired. |
| `context.cache.prices.has({ sku: "book" })`       | Whether an unexpired value exists.                       |
| `context.cache.prices.set({ sku: "book" }, 1200)` | Saves or replaces the price. Returns no value.           |
| `context.cache.prices.delete({ sku: "book" })`    | Removes the saved price. Returns no value.               |

Check for `undefined`, not truthiness: `0` can be a valid cached price. Keys and values must match your schemas.

## Use a numeric counter

A cache with a numeric value schema also exposes `increment(key, delta, options)`. The default increment is `1`. Use a separate cache for counters rather than changing product prices this way.

For limiting HTTP requests, use RELKIT's [route rate limits](/docs/modules/http/rate-limits). Keep the cache shared across app instances when a limit must apply to all of them.

---

# CLI
Source: https://relkit.dev/docs/modules/cli

> **Start here**
>
> The RELKIT CLI creates projects, adds application files, validates their connections, and runs
> your backend. Start with **[Create and build an API](/guides/cli/create-and-build-an-api)** to add
> an endpoint, call it, and run the production build.

## Pre-setup

Use Bun 1.3.10 or later and install your application's dependencies before running its local CLI.
Keep `relkit.config.ts` and the environment contract it passes to `defineApp`. New provider-backed
modules start with [local Docker setup](/docs/modules/integrations#pre-setup); the CLI itself
needs no extra `defineEnv` field. `relkit add` scaffolds selected configuration, but it does not
apply database migrations or supply secrets on your behalf.

## Run commands in the right place

Use `bunx create-relkit@latest` in the parent directory when creating a project. Inside an installed application, use its local CLI through `bun run relkit`; no global installation is required.

```sh title="Terminal — application root"
bun run relkit --help
bun run relkit add route --help
```

The first command lists available commands. The second shows the arguments and flags for adding a route without writing files. In an interactive terminal, `bun run relkit` opens an action menu; with redirected input it prints help. Supply explicit values for automation.

## Follow the application lifecycle

The generated project includes package scripts for common commands. Run these from the application root:

| Stage              | Command              | What happens                                                      | Continue with                                                                |
| ------------------ | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Add a capability   | `bun run relkit add` | Choose files, their owning service, and any required packages.    | [Add application files](/docs/modules/cli/add-artifacts)                     |
| Validate structure | `bun run check`      | Check application descriptors and their relationships.            | [`relkit check`](/docs/api/cli#relkit-check)                                 |
| Check TypeScript   | `bun run typecheck`  | Check source and generated types with TypeScript.                 | [CLI walkthrough](/guides/cli/create-and-build-an-api#check-the-application) |
| Test behavior      | `bun run test`       | Run the application's tests.                                      | [Testing](/docs/modules/operations/testing)                                  |
| Develop            | `bun run dev`        | Prepare the application, start the server, and watch for changes. | [`relkit dev`](/docs/api/cli#relkit-dev)                                     |
| Build              | `bun run build`      | Write the production output into `.relkit/build`.                 | [`relkit build`](/docs/api/cli#relkit-build)                                 |
| Run the build      | `bun run start`      | Start the built server.                                           | [`relkit start`](/docs/api/cli#relkit-start)                                 |

`check` validates structure; `typecheck` checks types; tests verify behavior. Run all three when changing application code. Build before starting production output, and stop the development server before starting another server on the same port.

## Choose a practical task

**Create, add a route, and build:**

follow the [CLI walkthrough](/guides/cli/create-and-build-an-api).

**Control project creation:**

choose [installation and Git options](/docs/modules/cli/create-an-app).

**Add services, functions, or resources:**

use [application scaffolding](/docs/modules/cli/add-artifacts).

**Start Redis or MinIO:**

follow [Local Docker](/docs/modules/integrations/local-docker); these commands manage declared
local resources separately from the backend.

**Apply database migrations:**

follow [Migrations](/docs/modules/database/migrations).

**Generate a frontend client:**

follow [Generated clients](/docs/modules/http/generated-clients).

**Prepare a deployment:**

follow [Deployment](/docs/modules/deployment), starting with local Docker and the supported
provider paths.

**Build an editor integration:**

use the [programmatic tooling APIs](/docs/modules/cli/automation).

For the longer Orders application, continue through [Learn](/docs/learn). For flags and exact syntax, use the **[command reference](/docs/api/cli)**. The separate [CLI automation API reference](/docs/api/cli-api) documents JavaScript imports used by tool authors.

---

# Add application files
Source: https://relkit.dev/docs/modules/cli/add-artifacts

Use `relkit add` to create application files and connect them to an existing or new service. In a terminal, omit a kind or required
value to choose from discovered services, public members, events, tools, prompts, and compatible provider
profiles. In CI or redirected execution, provide the documented flags; ambiguous input exits with usage code
`2` instead of prompting.

## Run the installed CLI

Run commands from an installed application's root. `bun run relkit` uses its local CLI binary;
`relkit` is equivalent when that binary is already on your `PATH`. No global installation is required.

```sh title="Terminal — application root"
bun run relkit
bun run relkit add
bun run relkit add agent --help
```

The first command opens the context-aware action menu in a TTY; the second opens the add-kind menu.
Bare `relkit` prints help in CI, redirected execution, or JSON mode. Add `--help` to any command
for its arguments and options. Start a new app with
[`bunx create-relkit` or `relkit create`](/docs/learn/create-an-app) before adding artifacts.

## Commands by artifact type

The minimal app stays lean until you select a feature. An add plan includes the selected adapter,
native SDKs/tooling, manifest sections and required repairs; it normally installs them and runs
`relkit check`. A source-only/manual workflow must follow that capability's installation guide.
With `--no-install`, complete the printed `bun install` and check steps before running the feature.
Adding an agent or resource never installs or starts the separate [Inspector tool](/docs/modules/operations/inspector).

Each linked guide explains a runnable command and the files it creates. The [command reference](/docs/api/cli) lists every option. For a first hands-on example, [add and call a new endpoint](/guides/cli/create-and-build-an-api#add-an-endpoint).

| Command                            | Detailed guide                                                                    |
| ---------------------------------- | --------------------------------------------------------------------------------- |
| `relkit add service [name]`        | [Services](/docs/modules/service/define#scaffold-a-service)                       |
| `relkit add function [name]`       | [Functions](/docs/learn/concepts/functions#scaffold-a-callable-function)          |
| `relkit add error [name]`          | [Typed errors](/docs/learn/concepts/errors#scaffold-a-typed-error)                |
| `relkit add event [name]`          | [Event contracts](/docs/modules/events/define#scaffold-an-event-contract)         |
| `relkit add event-function [name]` | [Event consumers](/docs/modules/events/consume#scaffold-an-event-only-function)   |
| `relkit add task [name]`           | [Tasks](/docs/modules/jobs/tasks#scaffold-a-task)                                 |
| `relkit add job [name]`            | [Jobs](/docs/modules/jobs/quickstart)                                             |
| `relkit add cache [name]`          | [Caches and profiles](/docs/modules/caching/define#scaffold-a-cache)              |
| `relkit add bucket [name]`         | [Buckets and profiles](/docs/modules/storage/define#scaffold-a-bucket)            |
| `relkit add tool [name]`           | [Tools](/docs/modules/ai/tools#scaffold-a-function-backed-tool)                   |
| `relkit add prompt [name]`         | [Prompts](/docs/modules/ai/agents#scaffold-a-reusable-prompt)                     |
| `relkit add agent [name]`          | [Agents and models](/docs/modules/ai/agents#scaffold-an-agent)                    |
| `relkit add constants [name]`      | [Domain constants](/docs/modules/service/context-values#scaffold-shared-values)   |
| `relkit add route [path]`          | [Routes and method mappings](/docs/modules/http/define#scaffold-a-route)          |
| `relkit add middleware [name]`     | [HTTP middleware](/docs/modules/http/middleware#scaffold-middleware)              |
| `relkit add transform [name]`      | [Request transforms](/docs/modules/http/requests#scaffold-a-request-transform)    |
| `relkit add database`              | [Drizzle databases](/docs/modules/database/define#scaffold-the-database-baseline) |
| `relkit add auth`                  | [Better Auth](/docs/modules/auth/better-auth#scaffold-the-auth-baseline)          |
| `relkit add inspector`             | [Inspector](/docs/modules/operations/inspector#add-the-inspector)                 |

Square brackets in usage mean the value can be prompted for, not that names are unnecessary in CI.
Database, auth and inspector take no name argument.

## Add a domain

The smallest service includes a public example function:

```sh title="Terminal — application root"
bun run relkit add service Billing
```

Choose a custom bundle with repeatable `--include`, or create every domain artifact with one command:

```sh title="Terminal — application root"
bun run relkit add service Billing --full
```

The full bundle wires a public function and event, an event consumer, error, job, cache, bucket, tool,
prompt, agent, constants, and `GET /billing` route. Missing event and job profiles use file-backed local
providers; cache and bucket use Docker Redis and MinIO. Agent projects use native LangChain/LangGraph
dependencies and keep deterministic tests offline; production model packages and credentials remain an
explicit application choice. The CLI never generates secrets, calls models, runs migrations, or provisions
cloud resources. Docker startup requires the separate approval below.

Friendly names are normalized before mutation. For example, `Send Receipt` previews
`send-receipt.function.ts`, the `sendReceipt` binding, and its domain-qualified descriptor ID.

## Add to an existing service

Explicit flags make a command deterministic for scripts:

```sh title="Terminal — application root"
bun run relkit add function send-receipt --service billing
bun run relkit add prompt receipt-policy --service billing \
  --text "Summarize the receipt."
bun run relkit add tool send-receipt --service billing \
  --target billing.send-receipt --side-effect external --approval on-write
```

Use `--create-service orders` instead of `--service orders` when the domain does not exist. Generic service
selection excludes the singleton auth and database services. Functions and events are public by default;
pass `--internal` to keep one out of `defineService`.

## Add routes

Route paths are converted with the compiler's inverse convention:

```sh title="Terminal — application root"
bun run relkit add route /users/:id/details \
  --mode service-route --service users --map GET=details
```

This creates `src/routes/users/[id]/details/route.ts`. `*parts` and `*parts?` become `[...parts]` and
`[[...parts]]`. Repeat `--map METHOD=member` for more methods. A standalone `--mode route` creates a raw
`GET` handler returning `{ ok: true }`; service routes support `GET`, `POST`, `PUT`, `PATCH`, `DELETE`,
`HEAD`, and `OPTIONS`. Both appear in OpenAPI/Scalar; only function-backed routes infer function schemas.

## Shared options and automation

| Option                       | Behavior                                                                   |
| ---------------------------- | -------------------------------------------------------------------------- |
| `--project-root <directory>` | Inspect and modify this app instead of the current directory.              |
| `--service <domain>`         | Choose an existing generic service for a domain artifact or service route. |
| `--create-service <domain>`  | Create the owning service instead; exclusive with `--service`.             |
| `--no-install`               | Skip dependency installation; report any skipped verification.             |
| `--json`                     | Disable prompts and emit one machine-readable result on stdout.            |
| `--help`, `-h`               | Show command-specific usage without scaffolding.                           |
| `--version`, `-v`            | Print the installed CLI version.                                           |
| `--completions <shell>`      | Print a completion script for `bash`, `zsh`, `fish`, or `sh`.              |

The service-selection flags do not relocate singleton database/auth services, standalone routes,
middleware, or transforms. Headless domain selection uses the only generic service when unambiguous;
otherwise supply `--service` or `--create-service`. Provider selection reuses compatible defaults or
unique profiles where possible, then documented scaffold defaults. Required unresolved targets are
usage errors, not guesses.

For deterministic automation, create first and chain add commands. From an installed application:

```sh
bun run relkit --json add service Billing
bun run relkit --json add function send-receipt --service billing
bun run relkit --json add route /receipts --mode service-route --service billing \
  --map GET=sendReceipt
```

JSON results include `createdFiles`, `updatedFiles`, `installedPackages`, structured `warnings`,
`verification`, and `nextSteps`. Usage exits `2`, operational failures exit `1`, and interrupt
cancellation exits `130`. Inspect verification and warnings even when scaffolding succeeds.

## Start local resources

After a successfully checked add that needs Docker, an interactive terminal asks whether to run
`relkit local up --detach`. Accepting starts this project's declared local services; the Docker warning
is removed only if startup succeeds. Declining, cancelling this post-add prompt, running headlessly,
or skipping verification leaves the warning and next step. Cancelling here does not undo an already
completed scaffold. A failed Docker start also leaves the saved files and reports how to retry.

```sh title="Terminal — application root, Docker running"
bun run relkit local up --detach
bun run relkit local status
```

File-backed local events and jobs need no Docker. Connected resources need their configured environment
values. Never copy a new `.env.example` over an existing `.env`; merge only the required missing values.

## Review and apply safely

Human output previews created and updated files, dependencies, profiles, and actionable warnings before
mutation. Fully explicit commands proceed immediately; a prompted command asks for confirmation. Each add is
one transaction: files and `bun.lock` are restored if installation or `relkit check` fails, while unrelated
dirty files remain untouched.

Use `--no-install` when another process owns installation. If a newly required package is unavailable, the
result skips validation and prints the exact install and check commands. `--json` disables prompts, color,
spinners, and progress, and writes one result object to standard output.

All supported kinds and headless flags are listed in the [CLI reference](/docs/api/cli).

Scaffolding understands canonical static service/app/env object literals, including imported env
definitions. Collisions and ambiguous dynamic source forms are rejected without overwriting files.
A passing `check` verifies the graph, not live credentials or business behavior. Run `bun run typecheck`
and your own tests after specializing the generated examples; the CLI generates no test files.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/routes` API](/docs/api/routes)

- [`templates/default/v1/api/src/services/orders/service.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/services/orders/service.ts)

---

# Automate project tooling
Source: https://relkit.dev/docs/modules/cli/automation

Use the CLI commands for everyday development. Use the programmatic APIs when an editor,
test harness, or other tool needs to inspect or drive the same behavior.

## Preview a new application

Install `create-relkit` and `@relkit/cli` as development dependencies in your tooling package.
Call `previewOrders` with an existing parent directory that does not contain `relkit-orders`:

```ts title="preview-orders.ts"
/** Uses the generator's read-only planning API and the CLI's native command model. */
import { findCliHelp } from "@relkit/cli/help";
import { normalizeCreateOptions, planCreate } from "create-relkit";

/** Reads a minimal application's planned files without creating or installing a project.
 * @param cwd - Parent directory in which a future project would be created.
 * @returns Validated file/dependency preview; no project files are written. */
export async function previewOrders(cwd: string) {
  const options = normalizeCreateOptions([
    "relkit-orders",
    "--template",
    "minimal",
    "--no-install",
    "--no-git",
  ]);
  return planCreate(options, { cwd });
}

export const checkHelp = findCliHelp(["check"]);
```

The preview contains the destination, planned files, and dependency versions. It does not
create the application, install packages, or initialize Git. `normalizeCreateOptions`
validates the same explicit template/cloud/deployment choices as the command line.
`findCliHelp` returns the command model used by terminal help and the
[CLI reference](/docs/api/cli).

## Choose the package and operation

| Package            | Use it for                                                                          | Reference                                                   |
| ------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `create-relkit`    | Normalize creation options, preview a project, or explicitly generate it            | [Generator APIs](/docs/api/create-relkit#all-exported-apis) |
| `@relkit/cli`      | Invoke commands with controlled I/O/cancellation, run development, or add artifacts | [CLI automation APIs](/docs/api/cli-api#all-exported-apis)  |
| `@relkit/cli/help` | Read command descriptions, arguments, flags, and examples                           | [Help model](/docs/api/cli-api#public-imports)              |
| `relkit`           | Resolve and launch the CLI installed in the target project                          | [Launcher APIs](/docs/api/relkit#all-exported-apis)         |

Creation and scaffold execution write files; preview operations return plans. Keep the
preview and execution boundaries explicit in your own tool. A development handle owns
processes and watchers: await its stop operation when your tool is finished.

Follow [Create an application](/docs/learn/create-an-app) for the complete user workflow,
or [Add application files](/docs/modules/cli/add-artifacts) for an existing project.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/cli` API](/docs/api/cli-api)
- [`create-relkit` API](/docs/api/create-relkit)
- [`relkit` API](/docs/api/relkit)

- [`apps/docs/examples/public-api/tooling.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/tooling.ts)

---

# Creation options
Source: https://relkit.dev/docs/modules/cli/create-an-app

The [quickstart](/docs/learn/create-an-app) uses the default minimal starter. Use these options when another tool owns installation or repository initialization.

## Supported choices

The packaged capability table currently offers the certified `minimal` template with examples, no jobs service, no cloud, and no deployment adapter. Interactive and headless creation use the same table. Explicit unsupported combinations fail before staging or installation.

Interactive creation asks for a missing project name and confirms the destination before writing. Git initializes by default; pass `--no-git` to disable it.

Add capabilities later with [application scaffolding](/docs/modules/cli/add-artifacts). See the [CLI reference](/docs/api/cli) for every creation option.

## Install dependencies separately

Pass `--no-install` when another tool owns installation. Then run the workflow printed by the generator from the new project directory:

```sh title="Terminal — generated project"
bun install
bunx --no-install relkit dev --prepare
```

Preparation validates the installed project, writes a development snapshot, and exits without opening backend or Inspector ports. On the next `bun run dev`, RELKIT verifies that snapshot against the current source, dependencies, toolchain, and runtime environment before starting.

## Add only the capabilities you use

The starter installs the application facade, CLI, and generic test tooling. Database and authentication adapters, agent engines, provider SDKs, exporters, optional HTTP protocols, and the Inspector are selected later.

`relkit add` normally installs the requirements it selects. When copying example files manually, complete the module's installation and configuration steps first. Keep application-owned overrides and patches supplied by those instructions.

---

# Typed Client
Source: https://relkit.dev/docs/modules/client

Use the generated client to call your backend with typed inputs, results, and application errors.

> **Start here**
>
> Follow [Call your API from React](/guides/frontend/connect-react) for a complete frontend
> workflow. Use [TypeScript clients and transports](/docs/modules/client/transports) for a caller
> without React. The [Client reference](/docs/api/client) lists exact helpers, hooks, and their
> import paths.

## Pre-setup

Run the [backend locally](/docs/modules/http#pre-setup) and complete the setup for each
capability you expose. Docker belongs to those backend providers; the typed client itself
needs no `defineApp` or `defineEnv` entry. Keep backend secrets and descriptors out of the frontend.
Choose the [Vite or Next.js proxy and build setup](/docs/modules/client/build-integration)
and use the public backend origin when pulling its contract. The steps below install the
frontend packages and connect that contract.

1. ## Install the selected frontend packages

    > **Before you begin**
    >
    > Start with a running RELKIT backend and a separate React app. Run the following in the **frontend
    > package root**, not the backend root. A TypeScript React app also keeps its framework's TypeScript
    > and React declarations (`@types/react`) as development tooling. The React leaf selects React/query
    > peers and the required OpenTelemetry API; a framework-independent client does not need those
    > React/query peers.

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @opentelemetry/api@1.9.1 @orpc/tanstack-query@2.0.0-beta.31 @relkit/client@0.8.4 '@tanstack/query-core@>=5.80.2' '@tanstack/react-query@>=5.80.2' 'react@>=18.0.0'
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The displayed React/query ranges are the owner's supported peer ranges. Preserve already compatible
    framework versions and commit the resolved lockfile; this is not an instruction to upgrade every
    frontend dependency. Install the CLI as development tooling for contract pull/check:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add --dev @relkit/cli@0.8.8
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    These frontend commands do not install the backend, database integrations or native agent engine.
    For a framework-independent caller, use [the base client installation](/docs/modules/http/generated-clients#install-the-caller)
    instead of the React recipe.

2. ## Pull the public contract

    From the frontend root, pull the running server's public contract into a frontend-owned directory:

    ```sh title="Terminal — frontend root"
    bun run relkit client pull http://127.0.0.1:3000 --out .relkit/generated
    ```

    This writes `contract.ts`, `client.ts`, `client-registry.d.ts`, and `client-manifest.json`. Include
    `.relkit/generated/**/*.ts` in the TypeScript project that checks your frontend source, as shown
    in the [Frontend guide](/guides/frontend/connect-react#2-pull-the-backend-contract), and regenerate them when the public API
    changes. The backend must be reachable while you pull; do not import backend source into a
    browser bundle.

    The recipe explicitly declares `@opentelemetry/api`, the required oRPC peer, so setup does not depend
    on whether a package manager automatically installs required peers.

3. ## Install the provider

    Wrap your React tree in [`RelkitClientProvider`](/docs/api/client#relkitclientprovider). This small
    example calls the minimal starter's Hello route through the
    [same-origin development proxy](/guides/frontend/connect-react#3-connect-the-local-frontend).
    For a separate backend origin, set `baseUrl` on the provider and configure its cookie/CORS boundary.

    ```tsx title="src/App.tsx"
    "use client";

    /** Renders the minimal backend's greeting through the pulled registry and a same-origin client provider. */
    import { RelkitClientProvider, useRelkitClient, useRoute } from "@relkit/client/react";

    /** Displays the typed Hello result after the provider resolves backend identity.
     * @returns Loading, connection failure, request failure, or the successful greeting. */
    export function Greeting() {
      const { status } = useRelkitClient();
      const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

      if (status === "application-updated") {
        return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
      }
      if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
      if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
      if (greeting.isPending) return <p role="status">Loading greeting…</p>;
      return <h1>{greeting.data.message}</h1>;
    }

    /** Supplies the shared query cache and identity handshake to the frontend tree.
     * @returns The greeting inside a same-origin RELKIT provider. */
    export default function App() {
      return (
        <RelkitClientProvider>
          <Greeting />
        </RelkitClientProvider>
      );
    }
    ```

4. ## Enforce compatibility

    The provider defaults to the same-origin backend, credentialed requests, a 30-second finite request
    timeout, and a 10-second stream-establishment timeout. An established healthy stream is not capped by
    the finite timeout. From the frontend root, check the pulled contract against the running
    backend before shipping:

    ```sh title="Terminal — frontend root"
    bun run relkit client check http://127.0.0.1:3000 --out .relkit/generated
    ```

    For Next.js or Vite, [configure `withRelkit()` or `relkit()`](/docs/modules/client/build-integration)
    to embed the public fingerprint at build time. Both read `.relkit/generated/client-manifest.json`
    from the frontend root; `client pull` is what writes it and the declarations.

    The compiled public-contract fingerprint must match the backend. A mismatch enters `application-updated` and blocks
    new typed work until frontend and backend are coordinated; unresolved mutation or control metadata is
    preserved rather than retried.

    Job hooks use the same provider and identity handshake. `useJobTrigger` retains the accepted `runId`, while
    `useJobRun` observes that run without starting a subscription during server rendering. Unknown submission
    outcomes remain visible for same-key recovery instead of becoming an automatic replay queue.

## Find the right client API

| Task                                          | API                                                         | Example                                                              |
| --------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| Call without React                            | `createClient`, `createWebSocketClient`, `createAutoClient` | [Transports](/docs/modules/client/transports)                        |
| Provide clients and inspect connection status | `RelkitClientProvider`, `useRelkitClient`                   | Provider and `Greeting` above                                        |
| Read a route                                  | `useRoute`, `useSuspenseRoute`, `useInfiniteRoute`          | [Route queries](/docs/modules/client/routes)                         |
| Submit a change                               | `useRouteMutation`, `useRouteUtils`                         | [Mutations](/docs/modules/client/mutations)                          |
| Observe a response stream                     | `useStream`                                                 | [HTTP streaming](/docs/modules/http/streaming#use-from-the-frontend) |
| Run or observe an agent                       | `useAgent`                                                  | [Agent streaming](/docs/modules/ai/streaming#use-from-the-frontend)  |
| Trigger, observe, or control a job            | `useJobRun`, `useJobTrigger`, `useJobCancel`, `useJobRetry` | [Job clients](/docs/modules/jobs/clients#use-from-react)             |
| Render on the server                          | `createServerClient`, `createRelkitServerContext`           | [Server rendering](/docs/modules/client/ssr)                         |
| Subscribe to channels                         | `useRealtime`, `useChannel`                                 | [Realtime React clients](/docs/modules/realtime/react)               |
| Embed the public fingerprint                  | `withRelkit`, `relkit`                                      | [Build integration](/docs/modules/client/build-integration)          |

[`useRelkitClient`](/docs/api/client#userelkitclient) must run inside the provider. It exposes
the client runtime and a `status` of `loading`, `ready`, `error`, or `application-updated`.
The [client export index](/docs/api/client#all-exported-apis) lists every import path and companion type.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/app.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx)

---

# Authentication and identity
Source: https://relkit.dev/docs/modules/client/authentication

Connect the frontend client's identity to your application's authenticated session.

> **Before you begin**
>
> Complete [React client setup](/docs/modules/client) in the frontend and [Better Auth
> setup](/docs/modules/auth/better-auth) in the backend first. The React convenience provider uses
> the separate `@relkit/better-auth/react` leaf. Add only its selected frontend owner/peers:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @opentelemetry/api@1.9.1 @relkit/better-auth@0.8.4 @relkit/client@0.8.4 'react@>=18.0.0'
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This convenience leaf keeps backend database configuration out of the browser. The example below
also uses Better Auth's native React `createAuthClient` and `useSession` hook, so install its
browser SDK requirements:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

Before installing, merge these selected declaration repairs into the existing package manifest, preserving unrelated overrides:

```json
{
  "overrides": {
    "@better-fetch/fetch": "1.3.2"
  },
  "pnpm": {
    "overrides": {
      "@better-fetch/fetch": "1.3.2"
    }
  }
}
```

From this guide's application/package root, install only its selected requirements:

```sh
bun add better-auth@1.7.1
bun add --dev @cloudflare/workers-types@4.20250121.0
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The [auth module](/docs/modules/auth/clients) owns sign-up, sign-in, and session operations.

## Bootstrap identity

`GET /_relkit/v1/client/identity` is private and non-cacheable. It returns opaque identity scope,
session epoch, application ID, and public fingerprint. Scope or epoch changes abort in-flight work,
clear private RELKIT stores, grants, and presence, and reject late callbacks.

## Connect a provider

Use `BetterAuthRelkitClientProvider` from `@relkit/better-auth/react` for cookie sessions. A manual
`identityKey` adds a tenant/application partition but never grants authority. Cross-origin cookies
still require exact credentialed CORS, suitable cookie `SameSite` policy, CSRF protection, and an
allowed Origin.

```tsx title="src/AuthProvider.tsx"
"use client";

/** Connects the native browser session hook to RELKIT's identity-scoped client cache. */
import { BetterAuthRelkitClientProvider } from "@relkit/better-auth/react";
import { createAuthClient } from "better-auth/react";
import type { ReactNode } from "react";

export const authClient = createAuthClient({ basePath: "/api/auth" });

/** Remounts private client state when the browser's authenticated session changes.
 * @param props - Frontend content that consumes RELKIT hooks.
 * @returns A same-origin provider whose auth endpoints use the native Better Auth client. */
export function AuthProvider({ children }: { readonly children: ReactNode }) {
  return (
    <BetterAuthRelkitClientProvider authClient={authClient}>
      {children}
    </BetterAuthRelkitClientProvider>
  );
}
```

Wrap the part of your app that calls RELKIT hooks in `AuthProvider`. For a same-origin proxy,
forward the backend's `/api/auth` mount as well as `/rpc` and `/_relkit`, and configure Better Auth's
trusted origins for the frontend. Do not nest a second generic provider around private queries.
The wrapper responds to native session changes; it does not replace the server's authorization.

Reference: [`BetterAuthRelkitClientProvider`](/docs/api/better-auth#betterauthrelkitclientprovider).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/auth-provider.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/auth-provider.tsx)

---

# Build integration and contract updates
Source: https://relkit.dev/docs/modules/client/build-integration

The [Frontend guide](/guides/frontend/connect-react) establishes installation, contract pull, and
the first request. Use this page to connect that contract to your frontend build.
The [Typed Client module](/docs/modules/client) owns shared installation and provider setup.

## Generate before building

From the frontend package root, while the backend is running:

```sh title="Terminal — frontend root"
bun run relkit client pull http://127.0.0.1:3000 --out .relkit/generated
bun run relkit client check http://127.0.0.1:3000 --out .relkit/generated
```

Both build helpers read `.relkit/generated/client-manifest.json` relative to the frontend project
root. Pulling to another directory does not change that lookup. The optional `root` option selects
a project root, not an arbitrary manifest filename. Keep the declarations in the frontend's TypeScript
`include` list; the build plugin embeds the fingerprint but does not load declarations or pull them.

## Select your framework

**Vite**

Merge `relkit()` into your existing plugins. This example also adds the development proxy used by
the Frontend guide; the plugin itself does not configure routing:

```ts title="vite.config.ts"
/** Adds the pulled fingerprint and a local same-origin proxy to an existing Vite React project. */
import { relkit } from "@relkit/client/build/vite";

export default {
  plugins: [relkit()],
  server: {
    host: "127.0.0.1",
    port: 5173,
    strictPort: true,
    proxy: {
      "/rpc": { target: "http://127.0.0.1:3000", ws: true },
      "/_relkit": { target: "http://127.0.0.1:3000" },
    },
  },
};
```

Reference: [`relkit`](/docs/api/client#relkit).

**Next.js**

Wrap your existing configuration with `withRelkit`. Keep its routes, rewrites, and other options
inside that configuration. This example also forwards RPC and identity requests to the local backend;
the helper itself only embeds the fingerprint and supports workspace-linked client resolution:

```ts title="next.config.ts"
/** Embeds the pulled fingerprint and forwards local browser requests to the backend. */
import { withRelkit } from "@relkit/client/build/next";

export default withRelkit({
  /** Keeps RPC and identity requests on the frontend origin.
   * @returns Local forwarding rules; replace their destinations for production. */
  async rewrites() {
    return [
      { source: "/rpc/:path*", destination: "http://127.0.0.1:3000/rpc/:path*" },
      { source: "/_relkit/:path*", destination: "http://127.0.0.1:3000/_relkit/:path*" },
    ];
  },
});
```

Follow the Next.js tabs in the [Frontend guide](/guides/frontend/connect-react) for TypeScript setup,
the Client Component, and verification. Replace the local rewrite destinations with your backend's
server URL for production. Rewrites require a Next.js server; static exports need gateway routing or
a public backend URL with [credentialed CORS](/docs/modules/client/authentication).
Reference: [`withRelkit`](/docs/api/client#withrelkit).

## Coordinate updates

After changing backend routes or public resource policies, regenerate the backend, pull its current
contract into the frontend, and typecheck the caller. Restart the frontend dev server after a pull;
build plugins read the fingerprint when configuration loads.

The React provider compares that compiled fingerprint with the server identity response. A mismatch
produces `application-updated` and blocks new typed work. Update the deployed frontend and backend
together. Do not clear pending-operation metadata or replay writes to get past a mismatch.

Use [`client check`](/docs/api/cli#relkit-client-check-baseurl---out-directory) before the frontend's production build.
It checks compatibility without replacing the files. Production routing, credential handling, and
stream proxy timeouts still belong to your host or gateway.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/vite.config.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/vite.config.ts)

---

# Mutations
Source: https://relkit.dev/docs/modules/client/mutations

Use a mutation for a request that changes application state, and track whether the server accepted it.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Submit once

`useRouteMutation` never runs on mount and defaults to no retry. Known-offline work fails as
`not-sent`; after a request is handed to `fetch`, timeout or disconnect is conservatively `unknown`.
RELKIT stores only scoped reconciliation metadata in `sessionStorage`, never variables or retry
payloads. Application mutations need an application-owned status endpoint to reconcile an unknown
outcome.

Every managed write carries the rendered identity scope and session epoch as a precondition. The
server authenticates independently and compares them before application code runs.

## Call a defined route

The backend's [Echo `defineRoute`](/docs/modules/http/define#expose-one-public-function) generates
`POST /echo`. Render this component under the provider after pulling that backend's contract:

```tsx title="src/EchoButton.tsx"
"use client";

/** Calls the documented POST /echo function route after an explicit user action. */
import { useRelkitClient, useRouteMutation } from "@relkit/client/react";

/** Sends domain input and renders the validated output; the hook owns mutation state.
 * @returns An Echo button with pending, failure, and success feedback. */
export function EchoButton() {
  const { status } = useRelkitClient();
  const echo = useRouteMutation("POST /echo");

  return (
    <section>
      <button
        disabled={status !== "ready" || echo.isPending}
        onClick={() => echo.mutate({ message: "Hello from the frontend" })}
      >
        Send message
      </button>
      {echo.isPending && <p role="status">Sending…</p>}
      {echo.isError && <p role="alert">{String(echo.error)}</p>}
      {echo.isSuccess && <p>{echo.data.message}</p>}
    </section>
  );
}
```

The hook infers `{ message }` input and `data.message` from the target function. For a real write,
refresh the affected [`useRoute` query](/docs/modules/client/routes) in `onSuccess`. Reconcile an
uncertain result before retrying a non-idempotent operation. See
[`useRouteMutation`](/docs/api/client#useroutemutation) for all options and
[offline writes](/docs/modules/client/offline) for recovery.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/echo.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/echo.tsx)

---

# Offline writes and uncertain outcomes
Source: https://relkit.dev/docs/modules/client/offline

Handle a lost connection according to what you know about the request's outcome.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Classify the outcome

RELKIT has no implicit offline write queue. A known-offline write is `not-sent`; a lost response after
transmission is `unknown`. Agent runs, controls, and continuations use scoped operation IDs and durable
receipt lookup after refresh. Arbitrary mutations remain unknown unless the application supplies a
reconciliation endpoint. Do not resubmit an uncertain external effect automatically.

Job submissions additionally retain the original operation ID, idempotency key, request digest, and any
provider-certified recovery window. A recovered job must use the same request; a discarded `runId` is not a
safe recovery strategy.

## Choose recovery from the outcome

The public `isJobUnknownOutcome` guard tells you whether a caught value includes a job
recovery action. Show that action to the user or use it in an explicit reconciliation flow:

```ts title="Handle an uncertain job outcome"
import { isJobUnknownOutcome } from "@relkit/client/react";

export function recoveryAction(error: unknown): string {
  if (!isJobUnknownOutcome(error)) return "Handle the ordinary request error.";
  switch (error.recovery.action) {
    case "retry-with-same-key":
      return `Inspect the receipt for ${error.operationId}; retry only with the same key and request.`;
    case "inspect-native":
      return `Inspect provider state for ${error.operationId} before taking action.`;
    case "unavailable":
      return `Outcome ${error.operationId} is unknown; reconcile manually.`;
  }
}
```

For ordinary route mutations, use an application-owned status endpoint before resubmitting.
The client cannot infer whether a disconnected write reached your backend. For jobs, keep the
original operation ID and request digest and follow the provider-certified recovery action.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/jobs/reconcile-unknown.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/reconcile-unknown.ts)

---

# Queries and cache utilities
Source: https://relkit.dev/docs/modules/client/routes

Call a backend operation from React using the contract generated from your application's routes.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Query finite routes

`useRoute`, `useInfiniteRoute`, `useSuspenseRoute`, and `useRouteUtils` accept only finite exposed
routes. Inputs, outputs, errors, selection, page parameters, signals, and query options are inferred
from generated declarations.

The [Hello route](/docs/modules/service/routes#when-to-use-defineroute) generates `GET /hello`.
Import `useRoute` and `useRelkitClient` from `@relkit/client/react`, then render this component
under the provider from the [Frontend guide](/guides/frontend/connect-react):

```tsx title="src/Greeting.tsx — component body"
/** Displays the typed Hello result after the provider resolves backend identity.
 * @returns Loading, connection failure, request failure, or the successful greeting. */
export function Greeting() {
  const { status } = useRelkitClient();
  const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

  if (status === "application-updated") {
    return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
  }
  if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
  if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
  if (greeting.isPending) return <p role="status">Loading greeting…</p>;
  return <h1>{greeting.data.message}</h1>;
}
```

The input and `data.message` follow the backend's schemas. An invalid selector or input fails
typechecking after the generated declarations are included. `GET /hello` is the procedure selector;
the client still uses RPC rather than constructing a REST request.

## Choose query helpers

| API                                                              | Use it when                                                                                                                                         |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`useRoute`](/docs/api/client#useroute)                          | The component renders loading, error, and success states.                                                                                           |
| [`useSuspenseRoute`](/docs/api/client#usesuspenseroute)          | A ready provider and your Suspense/error boundaries own loading and failure. It throws while the provider is not ready.                             |
| [`useInfiniteRoute`](/docs/api/client#useinfiniteroute)          | The backend already accepts pagination input; supply `initialPageParam`, `input(page)`, and `getNextPageParam`. It does not add backend pagination. |
| [`useRouteUtils`](/docs/api/client#userouteutils)                | You need the selected procedure's underlying query/mutation option builders.                                                                        |
| [`createTanstackQueryUtils`](/docs/api/client#all-exported-apis) | An application outside the RELKIT React hooks owns its QueryClient and identity lifecycle. Import it from `@relkit/client/tanstack-query`.          |

For the standalone query adapter, install its selected peers in the caller package:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @opentelemetry/api@1.9.1 @orpc/tanstack-query@2.0.0-beta.31 @relkit/client@0.8.4 '@tanstack/query-core@>=5.80.2'
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The React installation already includes these peers. Its managed hooks use identity-scoped
[`relkitKey`](/docs/api/client#relkitkey) keys. The underlying option builders do not automatically
produce those keys: use a managed query's `refetch()` for a simple refresh, or preserve the full
provider scope when interacting with its cache. See [server rendering](/docs/modules/client/ssr)
for the same requirement when prefetching.

## Keep streams separate

Routes with streaming output are deliberately absent from these selectors. Use `useStream` instead.
Routes marked `client: false` have neither a route-ID RPC procedure nor a URL alias.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/app.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx)

---

# Server calls and rendering
Source: https://relkit.dev/docs/modules/client/ssr

Fetch backend data during server rendering, then hydrate the matching frontend client.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Select the server entry point

[`createClient`](/docs/api/client#createclient) from `@relkit/client` works in a server runtime with
`fetch`. For Bun servers, [`createServerClient`](/docs/api/client#createserverclient) from
`@relkit/client/server` adds operation-time trace propagation, and
[`createRelkitServerContext`](/docs/api/client#createrelkitservercontext) from
`@relkit/client/server/tanstack-query` prepares identity-bound query hydration. The two `/server`
leaves are Bun-only package exports; a Node-based Next.js server should use the base client.

Create clients and caches per incoming request when forwarding user credentials. A browser cookie
jar is not inherited by server-side fetch, and one user's headers must not be shared with another.
`createServerClient` adds tracing, while `createRelkitServerContext` also loads identity. With the
base client or tracing-only client, [load identity and supply its headers](/docs/modules/client/transports)
before a mutation, forwarding the incoming credentials to both requests.

## Create request scope

In a Bun server, prefetch the same `GET /hello` selector and input used by the
[React example](/guides/frontend/connect-react). The query key includes the server-derived identity
scope so it matches the managed hook during hydration:

This example assumes the incoming request already carries the backend's session or anonymous
identity cookie. For a first visit without that cookie, let the browser provider establish identity
before loading private data. The server context does not forward new `Set-Cookie` headers to your
framework's response; custom server-side identity bootstrapping must handle that separately.

```ts title="server/prefetch-greeting.ts — Bun only"
/** Prefetches Hello for one Bun-rendered request using the same identity-scoped key as the React hook. */
import { createRelkitServerContext } from "@relkit/client/server/tanstack-query";
import { relkitKey } from "@relkit/client/react";
import { QueryClient } from "@tanstack/query-core";

/** Prepares a private hydration snapshot without sharing credentials or cache across requests.
 * @param request - Current incoming request whose credentials may be forwarded.
 * @param baseUrl - The same public backend origin configured on the browser provider.
 * @returns Identity-bound state for RelkitClientProvider's hydratedState prop. */
export async function prefetchGreeting(request: Request, baseUrl: string) {
  const queryClient = new QueryClient();
  try {
    const server = await createRelkitServerContext({ baseUrl, request, queryClient });
    const input = { name: "RELKIT" };
    const scope = server.dehydrate().scope;
    await queryClient.prefetchQuery({
      queryKey: relkitKey(scope, "query", "GET /hello", input),
      queryFn: () => server.client["route.get.hello"](input),
      staleTime: 30_000,
    });
    return server.dehydrate();
  } finally {
    queryClient.clear();
  }
}
```

Pass the returned state to `RelkitClientProvider` through its `hydratedState` prop, using the same
`baseUrl` and any `identityKey` partition on both sides. Give the browser's Hello query a matching
`staleTime: 30_000` when you want to reuse this prefetched value for 30 seconds.
Hydration installs only when backend, opaque identity scope, session epoch, public fingerprint,
operation, and canonical key match. A fresh hydrated query avoids unintended duplicate requests
within its configured `staleTime`; stale-query revalidation remains intentional.

The generated client supplies the typed query function; `relkitKey` adds the managed hook's cache
identity. Using an unrelated query key can make a successful prefetch invisible to the browser
hook. Keep framework serialization and response-cookie handling in the server layer.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/ssr.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/ssr.ts)

---

# Stream hooks
Source: https://relkit.dev/docs/modules/client/streams

Use a stream hook to receive a sequence of updates and cancel it when the reader no longer needs them.

> **Before you begin**
>
> Complete [frontend installation and contract pull](/docs/modules/client) before using this guide.
> Keep its selected React/query peers and generated declarations in the frontend package.

## Start a stream

`useStream` exposes `start`, `cancel`, and `reset`. Query-classified streams may opt into `autoStart`;
mutation streams always require an explicit start. Classification controls start/retry policy only.
It does not make a stream a finite cache query.

The low-level client returns a single-consumer `AsyncIterable`. Work starts on the first `next()`, and
breaking iteration cancels upstream work and releases its pinned invocation generation.

## Use the typed hook

```tsx title="src/Report.tsx"
"use client";

/** Consumes the commerce report route as a cancellable typed stream inside the client provider. */
import { useRelkitClient, useStream } from "@relkit/client/react";

/** Starts one report explicitly and displays its validated progress items.
 * @returns Start/cancel controls and visible progress or stream failure. */
export function Report() {
  const { status } = useRelkitClient();
  const report = useStream("GET /reports/:reportId");

  return (
    <section>
      <button
        disabled={status !== "ready"}
        onClick={() => void report.start({ reportId: "daily" })}
      >
        Run report
      </button>
      <button onClick={() => report.cancel()}>Cancel report</button>
      <p role="status">Completed: {report.items.map((item) => item.completed).join(", ")}</p>
      {report.error && <p role="alert">{String(report.error)}</p>}
    </section>
  );
}
```

This selector belongs to the commerce [streaming route](/docs/modules/http/streaming). Its
`streamOf` item schema determines `report.items`, so do not copy a stream selector into an app
that has not declared that route and pulled its contract.

Use [`useAgent`](/docs/modules/ai/streaming#use-from-the-frontend) for durable agent threads,
[`useJobRun`](/docs/modules/jobs/clients#use-from-react) for accepted jobs, and
[`useChannel`](/docs/modules/realtime/react) for shared application updates. Those have separate
identity and recovery contracts. Reference: [`useStream`](/docs/api/client#usestream).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/report.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/report.tsx)

---

# TypeScript clients and transports
Source: https://relkit.dev/docs/modules/client/transports

Use `@relkit/client` when a browser, script, or application already owns its request lifecycle.
The client returns typed results and rejects on failures. React applications can use the
[provider and hooks](/docs/modules/client) to manage loading, caching, and identity state.

## Install and load your contract

In the caller package:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @opentelemetry/api@1.9.1 @relkit/client@0.8.4
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

Use the [Frontend guide](/guides/frontend/connect-react#2-pull-the-backend-contract) to install the
development CLI and pull the public contract. Include `contract.ts` and `client-registry.d.ts` in the
caller's TypeScript program. The generated `client.ts` also imports its contract; installing the
package alone cannot infer the backend's operations.

## Call a function-backed route

With the [Echo route](/docs/modules/http/define#expose-one-public-function) on the backend and its
contract pulled into the caller, this function sends domain input and returns `{ message: string }`:

```ts title="src/echo-client.ts"
/** Calls the Echo contract from a TypeScript browser frontend without React or backend source imports. */
import { createClient } from "@relkit/client";

/** Sends one message over RPC using types from the caller's pulled contract.
 * @param baseUrl - Public backend origin, or the frontend origin when proxying RPC.
 * @param message - Nonempty message accepted by the Echo function.
 * @returns The validated message output; transport and application failures reject. */
export async function echoMessage(baseUrl: string, message: string) {
  const response = await fetch(new URL("/_relkit/v1/client/identity", baseUrl), {
    credentials: "include",
    cache: "no-store",
  });
  if (!response.ok) throw new Error(`Identity request failed (${response.status})`);
  const identity = await response.json();
  if (
    !identity ||
    typeof identity.identityScope !== "string" ||
    typeof identity.sessionEpoch !== "string"
  ) {
    throw new Error("The backend returned an invalid client identity");
  }
  const client = createClient({
    baseUrl,
    headers: {
      "x-relkit-identity-scope": identity.identityScope,
      "x-relkit-session-epoch": identity.sessionEpoch,
    },
  });
  return client["route.post.echo"]({ message });
}
```

Call `echoMessage(window.location.origin, "Hello from the frontend")` behind a same-origin proxy,
or pass your configured backend origin. Handle the returned Promise's rejection in your UI.
The pulled contract exposes `client["route.post.echo"]`. React hooks also accept the `POST /echo`
selector through their generated registry. The call uses `/rpc` and returns the function output;
it does not return an HTTP `Response`.

`createClient` configures transport; it does not perform the identity handshake. This example first
loads the current browser identity, validates its scope and session epoch, and sends them with the
mutation. The React provider manages that handshake for hooks. Server callers must forward the same
request credentials to both requests; [Bun's server context](/docs/modules/client/ssr) does this for you.
If the identity changes between requests, surface the rejection and reconcile the outcome before
submitting again. Do not bypass the identity headers or automatically retry a write.

## Choose a transport

All three factories are exported from `@relkit/client` and use the same generated contract:

| Factory                                                           | Use it for                                   | Configuration and behavior                                                                                         |
| ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [`createClient`](/docs/api/client#createclient)                   | Finite HTTP calls and supported HTTP streams | `baseUrl`, request-time `headers`, `credentials`, and an optional `fetch`.                                         |
| [`createWebSocketClient`](/docs/api/client#createwebsocketclient) | A backend with WebSocket RPC enabled         | `baseUrl`, an optional WebSocket constructor, and `establishmentTimeoutMs`. Connection establishment is lazy.      |
| [`createAutoClient`](/docs/api/client#createautoclient)           | WebSocket preference with HTTP fallback      | Combines the transport options. Fallback applies to connection establishment, not replay of an accepted operation. |

Pass the backend origin without appending `/rpc`. A custom transport still needs the backend's
matching configuration and authentication. Use [HTTP streaming](/docs/modules/http/streaming) for
stream contracts, and [client stream hooks](/docs/modules/client/streams) when React owns them.

`headers` may be a header collection or an asynchronous provider evaluated for future requests.
Use request-scoped credentials for server callers. Browser requests include credentials by default;
separate origins need [matching cookie and CORS configuration](/docs/modules/auth/clients#keep-cookies-and-origins-aligned).

## Add query utilities or server tracing

| Entry point                            | API                                                                                                | Owner                                                                                   |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `@relkit/client/tanstack-query`        | [`createTanstackQueryUtils`](/docs/api/client#all-exported-apis)                                   | [Query options and cache integration](/docs/modules/client/routes#choose-query-helpers) |
| `@relkit/client/server`                | [`createServerClient`](/docs/api/client#createserverclient)                                        | [Bun server calls and tracing](/docs/modules/client/ssr)                                |
| `@relkit/client/server/tanstack-query` | [`createRelkitServerContext`](/docs/api/client#createrelkitservercontext)                          | [Request-scoped hydration](/docs/modules/client/ssr)                                    |
| `@relkit/client/jobs`                  | [`watchJobRun`](/docs/api/client#watchjobrun), [`watchJobStream`](/docs/api/client#watchjobstream) | [Accepted job runs](/docs/modules/jobs/clients)                                         |

The server leaves are Bun-only exports. Use the base `createClient` in other server runtimes.
Query integration is opt-in and has its own [peer installation](/docs/modules/client/routes#choose-query-helpers).

## Handle errors and resource lifetimes

Catch [`ORPCError`](/docs/api/client#all-exported-apis) for RPC failures and inspect its code and data.
Do not treat a missing response to a write as proof that the write failed. Follow
[uncertain-outcome recovery](/docs/modules/client/offline) before resubmitting.

Pass cancellation signals to calls that need them, finish or cancel stream iteration, and dispose
job watchers when their owner closes. A reconnect resumes observation; it is not permission to
repeat a mutation. [Generated clients](/docs/modules/http/generated-clients) explains how route
policy, REST mapping, and RPC input differ.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`apps/docs/examples/frontend/rpc.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/rpc.ts)

---

# Database overview
Source: https://relkit.dev/docs/modules/database

A database keeps application records, such as accounts and orders, after a request or process ends. A database service owns how the application connects
to that data and exposes data operations to business domains. It is not the business domain itself.

> **Start here**
>
> Start with [PostgreSQL in local Docker](/docs/modules/database/local-docker). The [Orders
> tutorial](/docs/learn/save-orders) is a complete SQLite alternative. The [Drizzle
> reference](/docs/api/drizzle) lists the exact service, model, and query contracts.

Start with the data your product needs, then choose the database and integration that fit it. The
architecture below applies whether your model uses relational tables or documents; the concrete schema,
query, and migration APIs belong to the chosen integration.

## Pre-setup

For a new database service, use [PostgreSQL in local Docker](/docs/modules/database/local-docker).
That walkthrough covers the Compose file, persistent volume, CLI scaffold, credentials,
environment validation, and migration. Complete it before adding queries or auth tables.

1. **Start the database and scaffold its service**

    Follow the [Docker setup](/docs/modules/database/local-docker), then run
    `bun run relkit add database --orm drizzle --dialect postgresql` once in an app with no database
    service. The CLI installs the integration and creates the service, schema, and migration config.

2. **Connect defineEnv to defineApp**

    The CLI merges `DATABASE_URL` into `src/platform/env.ts`. Keep that contract imported by
    `relkit.config.ts`. This minimal inline example shows their relationship:

    ```ts title="relkit.config.ts — equivalent inline environment"
    /** Validate the database connection before activating the Drizzle service. */
    import { defineApp, defineEnv, env } from "@relkit/app/config";

    export default defineApp({
      env: defineEnv({ DATABASE_URL: env.secret() }),
    });
    ```

    Keep the actual URL in the backend's untracked `.env.local`. The Drizzle service opens it
    inside `client({ env })`; no database provider profile belongs in `defineApp`.

3. **Migrate and verify**

    Use the [migration steps](/docs/modules/database/local-docker#pre-setup) to generate, review,
    and apply your schema, then run `bun run check`, `bun run typecheck`, and `bun run dev`.
    Existing SQLite/MySQL apps keep their dialect and history; the [SQLite tutorial](/docs/learn/save-orders)
    is an explicit alternative, not a conversion step.

## Keep the responsibilities separate

| Responsibility      | What belongs here                                                          | Typical location                                                   |
| ------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Database service    | Connection configuration, lifecycle, and integration-specific registration | `src/services/database/service.ts`                                 |
| Data model          | Stored record shapes, identities, relationships, and constraints           | `src/services/database/schema/` in the current Drizzle integration |
| Data operations     | Reusable queries and persistence-specific customization                    | `src/services/database/models/` for Drizzle custom methods         |
| Business domain     | Validation, authorization, and workflows such as registering a member      | `src/services/users/functions/` or another owning domain           |
| Operational tooling | Schema migrations, backfills, backups, and recovery                        | Application-root tooling, outside business handlers                |
| HTTP interface      | Which business operations callers can invoke                               | `src/routes/`                                                      |

A Users function decides whether someone may join an organization. The database stores the user and
membership and enforces the configured constraints. A route exposes that workflow only when the product
needs an HTTP endpoint. Keeping these responsibilities separate lets you change a query without moving
routes, and evolve storage without duplicating business rules across transports.

The database is a specialized [service](/docs/modules/service). It does not replace domain services, and table
access alone never grants permission to a caller. See [Service organization](/docs/modules/service/organization)
for where functions, tools, agents, jobs, and other domain members belong.

## Choose an integration

[Drizzle](/docs/modules/database/drizzle) is the database service integration available today. It supports
relational table definitions and adds typed CRUD operations, generated validation schemas, custom
models, and transactions.

MongoDB and Prisma integrations are planned, not available APIs in this release. Their guides will
describe their own APIs as they are introduced; Drizzle's method names are not a universal contract
for future integrations. Database concepts stay separate from the currently implemented Drizzle workflow.

For the Drizzle path, follow [Save and retrieve orders](/docs/learn/save-orders) for a complete
SQLite example, then use [connection setup](/docs/modules/database/define) for other databases. Other database clients should remain behind your
domain's own operations until a supported integration is available; they are not automatically
registered by naming a file `service.ts`.

## Follow data through the application

```text
Route, job, tool, or other entry point
  → owning domain's business function
  → database service's data operations
  → database

Schema changes → migration tooling → database
```

The current Drizzle integration makes its typed client available through `context.database`.
Business functions do not open a new connection for each call or declare `dependencies.database`.
This injection and its exact types are documented in the [Drizzle service guide](/docs/modules/database/drizzle).

From an existing app's root, check service discovery and generated context types after changing registration:

```sh
bun run check
bun run typecheck
```

These commands check application structure and types; they do not provision a database or migrate it.

## Find the guide for your task

The following implementation guides use the current Drizzle integration:

**Understand what the integration generates:**

[Drizzle database service](/docs/modules/database/drizzle).

**Connect and configure lifecycle:**

[Define a Drizzle service](/docs/modules/database/define).

**Define tables, keys, and relationships:**

[Define the schema](/docs/modules/database/schema).

**Reuse and customize generated validation:**

[Generated CRUD and schemas](/docs/modules/database/generated-schemas).

**Read and change records:**

[Query data](/docs/modules/database/queries).

**Add a named query:**

[Custom models](/docs/modules/database/models).

**Change a built-in operation:**

[Override operations](/docs/modules/database/overrides).

**Commit related writes together:**

[Transactions](/docs/modules/database/transactions).

**Evolve persistent data:**

[Migrations](/docs/modules/database/migrations).

**Share the database with authentication:**

[Integrate Better Auth](/docs/modules/database/better-auth).

**Verify behavior safely:**

[Testing](/docs/modules/database/testing).

**Follow the complete application workflow:**

[Your first database](/guides/database/register-users-in-a-transaction).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)

- [`examples/data-model/src/services/users/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/users/service.ts)

---

# Integrate Better Auth
Source: https://relkit.dev/docs/modules/database/better-auth

Store authentication tables alongside your application's tables using its existing Drizzle database service. Keep database connectivity and table definitions in the database domain, authentication configuration
in the auth domain, and business operations in their owning services. Do not open a second connection
or build a second database service just for authentication.

This guide covers the database side of integration and the minimum route/session wiring needed to
verify it. Continue with [Auth getting started](/docs/modules/auth) for the architecture,
[Better Auth setup](/docs/modules/auth/better-auth) for service configuration, and
[Clients](/docs/modules/auth/clients) for sign-up, sign-in, and sign-out.

## Install before extending the schema

> **Before you begin**
>
> Complete [database setup](/docs/modules/database/define) first. The auth scaffold installs its
> selected requirements automatically; for the manual path, merge the following into that same
> backend. Keep the existing database service, table exports and applied migration history.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

Before installing, merge these selected declaration repairs into the existing package manifest, preserving unrelated overrides:

```json
{
  "overrides": {
    "@better-fetch/fetch": "1.3.2"
  },
  "pnpm": {
    "overrides": {
      "@better-fetch/fetch": "1.3.2"
    }
  }
}
```

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/better-auth@0.8.4 @relkit/drizzle@0.8.3 better-auth@1.7.1 drizzle-orm@1.0.0-rc.5-169397b
bun add --dev @cloudflare/workers-types@4.20250121.0 create-relkit@0.8.8 drizzle-kit@1.0.0-rc.5-ab785fc
```

The selected Drizzle version also needs the release's declaration repair. The development-only `create-relkit` package supplies its exact asset; a dependency cannot register Bun patches for its consumer.

```sh
mkdir -p patches
cp node_modules/create-relkit/dist/patches/drizzle-orm.patch patches/drizzle-orm@1.0.0-rc.5-169397b.patch
```

Merge this entry into the application's existing `patchedDependencies`, preserving other patches. Keep the asset in source control:

```json
{
  "patchedDependencies": {
    "drizzle-orm@1.0.0-rc.5-169397b": "patches/drizzle-orm@1.0.0-rc.5-169397b.patch"
  }
}
```

Then apply the registered repair before check/typecheck:

```sh
bun install
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

## Understand the shared connection

```text
src/services/database/service.ts → activated native Drizzle client
  ├─ RELKIT table clients → business functions via context.database
  └─ Better Auth Drizzle adapter → auth handler and session lookup

src/routes/api/auth/[[...auth]]/route.ts → auth.handler at /api/auth
```

RELKIT activates Drizzle before Better Auth and supplies the native client to Better Auth's Drizzle
adapter. The adapter uses the database service's schema by default and derives its provider from the
service dialect. You do not call `drizzleAdapter()` yourself in a RELKIT auth service.

The current integration requires one Drizzle service, one Better Auth service, and one filesystem
`ALL` route mounting the auth handler. It does not support selecting a second database for auth.

## Add the authentication tables

The executable `examples/auth-drizzle` application uses Better Auth `1.7.1` and the repository's pinned
Drizzle version. Its table definitions are:

```ts title="src/services/database/schema/index.ts"
/** Declares native Better Auth SQLite user/session/account/verification tables, retaining timestamp modes and account uniqueness. */
import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";

const timestamps = {
  createdAt: integer({ mode: "timestamp" }).notNull(),
  updatedAt: integer({ mode: "timestamp" }).notNull(),
};

export const user = sqliteTable("user", {
  id: text().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  emailVerified: integer({ mode: "boolean" }).notNull(),
  image: text(),
  ...timestamps,
});

export const session = sqliteTable("session", {
  id: text().primaryKey(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
  token: text().notNull().unique(),
  ipAddress: text(),
  userAgent: text(),
  userId: text().notNull(),
  ...timestamps,
});

export const account = sqliteTable(
  "account",
  {
    id: text().primaryKey(),
    accountId: text().notNull(),
    issuer: text().notNull(),
    providerId: text().notNull(),
    userId: text().notNull(),
    accessToken: text(),
    refreshToken: text(),
    idToken: text(),
    accessTokenExpiresAt: integer({ mode: "timestamp" }),
    refreshTokenExpiresAt: integer({ mode: "timestamp" }),
    scope: text(),
    password: text(),
    ...timestamps,
  },
  (table) => [uniqueIndex("account_issuer_account_id").on(table.issuer, table.accountId)],
);

export const verification = sqliteTable("verification", {
  id: text().primaryKey(),
  identifier: text().notNull(),
  value: text().notNull(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
  ...timestamps,
});
```

The singular export keys `user`, `session`, `account`, and `verification` match the adapter's default
model names. Preserve required fields, nullability, key types, and timestamp/boolean mappings for your
installed Better Auth version. This version's account model includes `issuer` and the compound
`issuer`/`accountId` identity; do not substitute an older four-table example without comparing it.

Add these table exports to the schema map already passed to `defineDrizzleService`. If you split them
into `src/services/database/schema/auth.ts`, re-export them from the schema entry point used by both the service
and Drizzle Kit. Do not replace existing business table exports or nest the auth tables under an `auth`
property: the service needs direct table exports.

The Users tutorial's `users` table is not Better Auth's `user` model. Its numeric ID and fields are
different. Decide whether you are adding separate domain profiles referencing auth user IDs or migrating
an existing identity model. Do not silently repurpose existing user records or their foreign keys.

## Generate and apply the schema changes

Use the same [Drizzle Kit workflow](/docs/modules/database/migrations) as the rest of the database. With the
configuration from that guide and an explicitly selected database, run from your app root:

```sh
export DATABASE_PATH=./data-model.sqlite
bun --bun drizzle-kit generate --name=better-auth
```

Review and test the generated change, then run `bun run relkit db migrate` before enabling the auth
service. A table export registers a model; it does not create or update the physical table. Adding
Better Auth does not cause RELKIT to generate or apply migrations automatically.
Keep auth and business-table SQL/metadata together in the database service's tracked migration history.

Auth plugins and additional fields can require further tables, columns, and indexes. Keep the Better
Auth configuration, Drizzle definitions, and migrations aligned. If you use Better Auth's own schema
generator, its input must be a native Better Auth configuration supported by that tool: a RELKIT
service descriptor is not the activated `betterAuth()` instance. Do not point an unrelated CLI at the
descriptor and assume it can discover this integration.

## Define the auth service

After the installation and migrations above, the local showcase enables email/password authentication:

Backend activation uses `@relkit/better-auth/drizzle`; React is optional and belongs only to the
`/react` entrypoint. Native Drizzle drivers stay selected by the application's database setup.

```ts title="src/services/auth/service.ts — local demonstration"
/** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
import { defineBetterAuthService } from "@relkit/better-auth";

export default defineBetterAuthService({
  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
  // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
  emailAndPassword: { enabled: true },
});
```

The service uses Better Auth's native `BETTER_AUTH_SECRET` process-environment lookup and has no
hard-coded secret. Supply a strong, stable server secret before startup; configure `BETTER_AUTH_URL`
and trusted origins for the real application. The loopback URL is a local default only. The integration
does not accept an `({ env })` factory for auth options, and merely declaring a field in `defineEnv`
does not inject it into native options or populate the process environment. See
[Auth environment setup](/docs/modules/auth/better-auth#define-the-service-and-environment).

Do not set `database` or `basePath` on `defineBetterAuthService`: both are reserved. RELKIT supplies the
database and derives the base path from the mounting route. Optional `drizzle` adapter settings can
customize behavior such as schema mapping; `provider` remains derived from the database dialect.

If you use custom model/field names, align Better Auth's naming configuration with the adapter's schema
mapping. An optional `drizzle.schema` map changes what the adapter sees, not what the database service
registers or what Kit migrates. Keep those definitions and table identities consistent.

## Mount the API and read the session

Create the filesystem catch-all route:

```ts title="src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "@app/services/auth/service.js";

export const ALL = defineRoute({
  handler: auth.handler,
  auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
});
```

This mounts the API at `/api/auth` and protects the listed application paths. Authentication endpoints
must remain reachable so a caller can sign in. Use the registered raw handler rather than wrapping it
in a JSON business function; auth owns its response headers and cookies. See
[Raw HTTP handlers](/docs/modules/http/raw-handlers) for mounting rules.
See [Protect routes](/docs/modules/auth/protect-routes) for path matching, public auth endpoints, and permission checks.

A business function can read the request's session:

```ts title="src/services/account/functions/session.function.ts"
/** Reads the invocation's native session and returns validated authentication and user identity fields. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({}),
  output: z.object({ authenticated: z.boolean(), userId: z.string().optional() }),
  handler: async (_input, context) => {
    const session = await context.auth.getSession();
    return session === null
      ? { authenticated: false }
      : { authenticated: true, userId: session.user.id };
  },
});
```

Matching a protected route requires authentication, not permission to every row. Enforce ownership,
organization membership, and roles in the business operation. Work without an HTTP request, such as
a job, must not assume there is a caller cookie session.

## Keep auth writes inside the auth system

Better Auth talks to the native Drizzle client. Its writes do not pass through RELKIT's portable CRUD
methods, generated Zod parsers, or operation overrides. A `users.findOne` override cannot enforce
Better Auth's account policy or session behavior.

Conversely, generated CRUD access to auth tables does not make it safe to expose them. Let Better Auth
own password hashing, account linking, token/session lifecycle, and authentication-specific updates.
Do not publish generic read/write routes for account, session, or verification records; their rows
can contain credentials and tokens. A `context.database.transaction` callback also does not automatically
enlist a separate Better Auth API call in its transaction.

## Verify before adding clients

From the repository's `examples/auth-drizzle` directory:

```sh
bun run check
bun run typecheck
bun test tests/auth.test.ts
```

The showcase test migrates a temporary database and checks public/protected requests, sign-up, session
lookup, sign-out and old-cookie rejection, invalid credentials, and sign-in. Follow [Auth testing](/docs/modules/auth/testing)
for the executable test and environment setup. It is a local wiring/migration check, not proof that
your custom fields/plugins, browser cookies, production dialect, or deployment policy are correct.

For setup failures, first check that the auth tables are in the service's schema map, the migration
and app use the same database, and the catch-all route mounts the registered `auth.handler` exactly once.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/auth-drizzle/src/services/auth/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/auth/service.ts)
- [`examples/auth-drizzle/src/services/database/schema/index.ts`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/src/services/database/schema/index.ts)

---

# Define a Drizzle service
Source: https://relkit.dev/docs/modules/database/define

Register your database connection and tables with `defineDrizzleService` in `src/services/database/service.ts`. Use `defineDrizzleService`
from `@relkit/drizzle` in `src/services/database/service.ts`. Do not wrap it in an
ordinary `defineService`, add a `database` member to another service, or add a database provider profile
to `relkit.config.ts`. The specialized service is the registration.

## Pre-setup

For a new database, complete [PostgreSQL in local Docker](/docs/modules/database/local-docker)
before configuring the service. It supplies the running database, `DATABASE_URL` contract,
and migration steps. The detailed manual example below uses SQLite; keep your existing
dialect and migrations when following it, and use the corresponding native driver.

1. ## Install compatible packages

    The minimal app does not install the optional database integration. Choose one setup path from
    the application root, then continue with the connection and schema below.

    **CLI**

    ### Scaffold the database baseline

    ```sh title="Terminal — application root"
    bun run relkit add database --orm drizzle --dialect postgresql
    ```

    This creates `src/services/database/service.ts`, an `items` placeholder in
    `src/services/database/schema/index.ts`, and `drizzle.config.ts`. It merges the environment
    contract and examples, installs the selected packages and declaration repair, and checks the app.
    Replace the placeholder schema with your tables. The command does not apply migrations.

    Use this once when the application has no database service. For an existing service, edit its
    configuration and preserve its schema and migration history. Use `--dialect sqlite` for the
    manual file-backed example below, or `--dialect mysql` with a running MySQL database.

    With `--no-install`, run `bun install` and `bun run check` before continuing. See the
    [database command reference](/docs/api/cli#relkit-add-database) and
    [complete SQLite guide](/guides/database/register-users-in-a-transaction).

    **Manual**

    Install the compatible owner-specific cohort before creating the files below. RELKIT packages
    have independent versions; keep existing manifest settings when merging the repair.

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/drizzle@0.8.3 drizzle-orm@1.0.0-rc.5-169397b
    bun add --dev create-relkit@0.8.8 drizzle-kit@1.0.0-rc.5-ab785fc
    ```

    The selected Drizzle version also needs the release's declaration repair. The development-only `create-relkit` package supplies its exact asset; a dependency cannot register Bun patches for its consumer.

    ```sh
    mkdir -p patches
    cp node_modules/create-relkit/dist/patches/drizzle-orm.patch patches/drizzle-orm@1.0.0-rc.5-169397b.patch
    ```

    Merge this entry into the application's existing `patchedDependencies`, preserving other patches. Keep the asset in source control:

    ```json
    {
      "patchedDependencies": {
        "drizzle-orm@1.0.0-rc.5-169397b": "patches/drizzle-orm@1.0.0-rc.5-169397b.patch"
      }
    }
    ```

    Then apply the registered repair before check/typecheck:

    ```sh
    bun install
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    Bun includes the SQLite driver used here. The scaffold's PostgreSQL/MySQL clients use `bun:sql`;
    other native Drizzle clients need their own selected driver and a running database. The
    [MySQL model entrypoint](/docs/modules/database/models) also requires its declaration peer. Do not mix
    older Drizzle APIs with this release candidate without checking types.

2. ## Configure environment and client creation

    The data-model example uses this environment contract:

    ```ts title="src/platform/env.ts"
    import { defineEnv, env } from "@relkit/app/config";

    export default defineEnv({ DATABASE_PATH: env.string().default("./data-model.sqlite") });
    ```

    Merge `DATABASE_PATH` into your existing `defineEnv()` and keep that descriptor in `defineApp({ env })`.
    The example defaults to `./data-model.sqlite`; ensure its parent directory exists and is writable.
    Use the same path for the app and [migration tooling](/docs/modules/database/migrations). A test may explicitly
    use `:memory:`, which is isolated to a connection and disappears when it closes.

    The complete service includes optional models and overrides:

    ```ts title="src/services/database/service.ts"
    /** Owns lazy SQLite registration and disposal, supplying users-model extensions and an inactive-user lookup override. */
    import { Database } from "bun:sqlite";
    import { defineDrizzleService } from "@relkit/drizzle";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import * as schema from "./schema/index.js";
    import usersModel from "./models/users.model.js";

    export default defineDrizzleService({
      schema,
      client: ({ env }) => drizzle({ client: new Database(env.DATABASE_PATH) }),
      models: { users: usersModel },
      overrides: {
        users: {
          findOne: async ({ args, base }) => {
            const user = await base(args);
            return user?.active === false ? null : user;
          },
        },
      },
      dispose: (database) => database.$client.close(),
    });
    ```

    `schema` is the flat map of table exports. `client({ env })` returns the actual Drizzle database, or a
    promise for it. Open the connection inside this factory, not at module top level. Descriptor discovery
    inspects the schema without activating the factory; the generated server activates it during startup.

    There are no table-creation statements to write here. The client factory only opens the connection.
    Define the model in [Drizzle tables](/docs/modules/database/schema), then use
    [Drizzle Kit](/docs/modules/database/migrations) to generate and apply its migrations before starting the app.

    `models` and `overrides` are optional; omit both for base CRUD. `dispose(database)` closes the underlying
    driver or pool. RELKIT calls it during normal runtime shutdown. A process crash still requires normal
    database recovery; shutdown hooks are not backup or durability guarantees.

3. ## Choose and customize the driver

    | Dialect    | What changes                                                            | Important integration limit                                                                                                                       |
    | ---------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
    | SQLite     | SQLite tables, Bun SQLite client, file path or memory database          | The portable transaction helper shares a connection; review its [concurrency limits](/docs/modules/database/transactions).                        |
    | PostgreSQL | PostgreSQL table definitions and a compatible async Drizzle client/pool | Portable transactions delegate to the client's transaction implementation.                                                                        |
    | MySQL      | MySQL tables and a compatible async Drizzle client/pool                 | Returned mutation rows need a recoverable primary/unique key; see [queries](/docs/modules/database/queries#understand-dialect-and-upsert-limits). |

    Driver construction remains native Drizzle configuration. Configure TLS, connection limits, query
    timeouts, logging, and pool disposal there as appropriate for that driver. RELKIT does not add these as
    service options or translate tables between dialects. The executable guides here verify Bun SQLite;
    test other drivers against their actual database before deploying.

    Use secret environment fields for credentials or a credential-bearing connection URL. Do not log them or
    hard-code production values. `RELKIT_ENV=test` does not replace this custom client factory with an
    in-memory database: set a safe test database value explicitly.

4. ## Generate the typed application context

    From the app root:

    ```sh
    bun run check
    bun run typecheck
    ```

    The compiler emits `.relkit/generated/context-registry.d.ts`, which supplies `context.database` and
    typed application environment fields. Keep the generated declaration included by your TypeScript
    configuration, as generated projects do. Do not hand-edit it or add a competing global declaration.

    If the database or a model method is missing from editor types, check table exports and model registration,
    rerun the compiler, then confirm the declaration is included. The service has an inferred identity from
    its domain; an explicit `id` is optional and must follow the same domain identity rules.

## Understand activation ownership

Activation is cached by descriptor object within a process. Repeated activation shares the original
client and environment; it is not a per-request or per-tenant connection factory. `close()` is idempotent,
but currently does not evict that cached activation, so activating the same closed descriptor does not
reopen it. Use fresh service objects or isolated processes for independent test lifetimes.

The service is not a managed database provisioning request. Arrange durable storage or a database server,
backups, credentials, network access, and migrations separately. For Better Auth, keep the auth tables
in this same Drizzle schema and follow [Integrate Better Auth](/docs/modules/database/better-auth).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/config` API](/docs/api/config)

- [`examples/data-model/src/services/database/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/service.ts)

---

# Drizzle database service
Source: https://relkit.dev/docs/modules/database/drizzle

Use the Drizzle integration for relational tables and Drizzle's TypeScript query builder. Use `@relkit/drizzle` when you want relational tables and Drizzle's TypeScript query builder.
This page describes that integration's behavior; return to [Database](/docs/modules/database) for the
adapter-neutral architecture.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## Define once and reuse throughout the app

Export `defineDrizzleService(...)` from `src/services/database/service.ts`:

```ts title="src/services/database/service.ts"
/** Owns lazy SQLite registration and disposal, supplying users-model extensions and an inactive-user lookup override. */
import { Database } from "bun:sqlite";
import { defineDrizzleService } from "@relkit/drizzle";
import { drizzle } from "drizzle-orm/bun-sqlite";
import * as schema from "./schema/index.js";
import usersModel from "./models/users.model.js";

export default defineDrizzleService({
  schema,
  client: ({ env }) => drizzle({ client: new Database(env.DATABASE_PATH) }),
  models: { users: usersModel },
  overrides: {
    users: {
      findOne: async ({ args, base }) => {
        const user = await base(args);
        return user?.active === false ? null : user;
      },
    },
  },
  dispose: (database) => database.$client.close(),
});
```

The factory connects to the database. It does not require handwritten table-creation statements.
Define the tables in TypeScript and apply their changes through [Drizzle Kit migrations](/docs/modules/database/migrations)
before starting the application.

The optional `models` and `overrides` in this example customize behavior. Remove those two options and
the model import if you only need the generated base operations.

## Understand what is automatic

For every table exported through `schema`, RELKIT provides:

| Generated surface                                | Example                                        | Purpose                                                      |
| ------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------ |
| Six typed CRUD methods                           | `context.database.users.insert({ data })`      | Read and mutate records without writing a repository wrapper |
| Select, insert, and update Zod schemas           | `context.database.zodSchemas.users.insert`     | Validate data against the table shape when explicitly called |
| Model extension methods                          | `context.database.users.byEmailDomain(domain)` | Expose the custom methods you register                       |
| Transaction-bound context                        | `context.database.transaction(callback)`       | Compose related database operations                          |
| Compiler context declarations and graph metadata | `.relkit/generated/context-registry.d.ts`      | Give application code typed access to the discovered service |

Base CRUD and schemas exist even for a table with no custom model file. Changing a table updates the
derived TypeScript types and validation schemas; regenerate context declarations when registration
changes, and migrate the physical database separately. See [Generated CRUD and schemas](/docs/modules/database/generated-schemas)
for the exact data shapes, customization, and validation boundaries.

This does not generate HTTP CRUD endpoints, public function contracts, authorization rules, seed data,
or database migrations. Add [business functions](/docs/learn/concepts/functions) and
[routes](/docs/modules/http) deliberately.

## Follow discovery and activation

The compiler discovers the service, inspects its table metadata, and generates application context types.
The runtime then invokes `client({ env })` during startup and injects the resulting database context
into business functions. Normal shutdown calls `dispose`.

There is no `dependencies.database` entry and no database provider profile to add to
`relkit.config.ts`. Do not wrap this descriptor in `defineService`. The database service supplies
persistence; the [Users service](/docs/modules/service/define) still owns its business operations.

Only one Drizzle service is currently supported per application. Its schema must contain at least one
table and use one dialect: SQLite, PostgreSQL, or MySQL. These are current integration constraints,
not promises about future MongoDB or Prisma integrations.

## Choose the customization point

Use [schema definitions](/docs/modules/database/schema) for stored shapes and constraints,
[custom models](/docs/modules/database/models) for named Drizzle queries, and
[overrides](/docs/modules/database/overrides) to change an existing CRUD method. Keep caller permissions and
public input/output in the owning business function.

Continue to [Define a Drizzle service](/docs/modules/database/define) for dependencies, environment, driver setup,
and lifecycle. Exact signatures live in the [Drizzle API reference](/docs/api/drizzle).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/services` API](/docs/api/services)

- [`examples/data-model/src/services/database/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/service.ts)

---

# Generated CRUD and schemas
Source: https://relkit.dev/docs/modules/database/generated-schemas

RELKIT derives a typed CRUD client and validation schemas from each table registered with `defineDrizzleService`. `defineDrizzleService` inspects each table in its `schema` map and derives both a typed CRUD client
and Zod schemas. This also works for tables without a `defineModel` extension.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## One table, several generated contracts

The example's Users table is the source:

```ts title="src/services/database/schema/index.ts — users"
export const users = sqliteTable("users", {
  id: integer().primaryKey({ autoIncrement: true }),
  email: text().notNull().unique(),
  active: integer({ mode: "boolean" }).notNull().default(true),
});
```

The schema export key `users` determines both `context.database.users` and
`context.database.zodSchemas.users`. Each has a different job:

| Surface                                                             | Shape for this table                                                    | When to use it                               |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
| `users.findOne`, `findMany`, `insert`, `update`, `upsert`, `delete` | Typed arguments and row results derived from the table                  | [Query data](/docs/modules/database/queries) |
| `zodSchemas.users.select`                                           | `{ id: number, email: string, active: boolean }`                        | Validate a complete selected row             |
| `zodSchemas.users.insert`                                           | Required `email`; optional `id` and `active` because they have defaults | Validate the `data` of an insert             |
| `zodSchemas.users.update`                                           | Optional fields for a partial update                                    | Validate the `data` of an update             |

RELKIT uses Drizzle's `createSelectSchema`, `createInsertSchema`, and `createUpdateSchema`
from `drizzle-orm/zod`. The schemas describe row data, not the complete CRUD argument wrapper.
Parse the data object, then pass it as `{ data }`; do not parse `{ where, data }` with an update schema.

A default makes a field optional on insert; it does not make the selected field optional. Here the
database supplies the ID and active flag when omitted. Parsing the insert does not allocate an ID
or insert a row. Nullable columns remain nullable according to their table definition, and a unique
column is not checked for existing duplicates by Zod.

## Use the generated insert schema in a workflow

The member-registration function first validates its business input, then validates the row it builds:

```ts title="src/services/users/functions/register-member.function.ts"
/** Validates native user data and creates the user/membership in one borrowed database transaction, retaining rollback failures. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({ email: z.string().email(), organizationId: z.string().min(1) }),
  output: z.object({ userId: z.number(), membershipId: z.number() }),
  handler: async ({ email, organizationId }, context) => {
    const data = context.database.zodSchemas.users.insert.parse({ email });
    return context.database.transaction(async (tx) => {
      const user = await tx.users.insert({ data });
      const membership = await tx.memberships.insert({
        data: { organizationId, userId: user.id, role: "member" },
      });
      return { userId: user.id, membershipId: membership.id };
    });
  },
});
```

The function's input requires an email address and an organization identifier. It does not let a caller
supply a user ID, membership role, or active flag. The generated insert schema checks the persistence
shape; the transaction creates both records. Read [Transactions](/docs/modules/database/transactions) for
the commit and rollback behavior.

This is a data-workflow example for trusted internal callers, not an authorization implementation.
Verify the caller's permission to add members before exposing it through HTTP, tools, or other clients.

## Validate updates and selected rows

```ts title="src/services/users/functions/update-user-email.function.ts"
/** Validates native update/select data and returns the changed user's email or null when its row is unavailable. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({ userId: z.number().int().positive(), email: z.string().email() }),
  output: z.object({ userId: z.number(), email: z.string() }).nullable(),
  handler: async ({ userId, email }, context) => {
    const data = context.database.zodSchemas.users.update.parse({ email });
    const row = await context.database.users.update({ where: { id: userId }, data });
    if (row === null) return null;
    const user = context.database.zodSchemas.users.select.parse(row);
    return { userId: user.id, email: user.email };
  },
});
```

The update schema accepts a partial data object. The unique selector stays in `where`, and the
operation may return `null` for a missing user. Only after checking that result does the function
parse a full selected row. Its public output deliberately returns just the identifier and email.

An update schema is not an allowlist for editable fields and does not enforce a nonempty patch.
Construct data from approved fields, require the desired fields in the public input, and check
authorization independently. These example write functions are registered on the service but are
not mounted as public write routes.

## Customize validation at the right boundary

The generated schemas capture database types, nullability, and defaults; they do not infer product rules
from column names. A text column called `email` accepts strings, not necessarily email addresses.
The examples add `z.string().email()` to the function input for that reason.

Use `.parse()` to throw on invalid data or `.safeParse()` to handle a validation result explicitly.
You can apply `.refine()` to a generated schema for an additional runtime rule. There is no
`zodSchemas` override option on `defineDrizzleService`; do not mutate the generated schema registry.

The context exposes these values as typed `ZodType` instances, not a public `ZodObject` API.
Do not assume object-specific methods such as `.pick()`, `.omit()`, or `.extend()` are available
on their declared type. For a separately customized table-derived object schema, use the pinned
Drizzle version's `createInsertSchema(table)` (or select/update counterpart) in the database domain.
Keep public function contracts explicit rather than importing another domain's private table files.
See [Schemas](/docs/learn/concepts/schemas) for declaring those contracts.

## Know what validation does not do

The base CRUD layer does not automatically run these Zod schemas for every operation. TypeScript types
help during development, but untrusted runtime input still needs explicit validation. Functions validate
their declared input/output through RELKIT; that is separate from database schema parsing.

Generated schemas do not enforce row ownership, tenant access, referential integrity, database
uniqueness, or transaction isolation. Keep durable constraints in the database and business rules in
functions. Custom models and overrides must preserve the checks their behavior requires.

When the schema changes, update public contracts as needed, regenerate application types, generate and
apply a migration, and verify both accepted and rejected input. None of these steps automatically
replaces the others.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/schema` API](/docs/api/schema)

- [`examples/data-model/src/services/users/functions/register-member.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/users/functions/register-member.function.ts)

---

# Set up PostgreSQL in Docker
Source: https://relkit.dev/docs/modules/database/local-docker

Connect an existing RELKIT app to PostgreSQL running in local Docker. This is the default
database setup for a new module. The [Orders tutorial](/docs/learn/save-orders) remains a
separate SQLite walkthrough; keep its database and migration history when continuing that app.

## Pre-setup

You need a working minimal app, Bun, and Docker with Compose. Run these commands in the
backend root. This walkthrough adds a database only when the app has no database service.
For an existing service, retain its dialect, tables, credentials, and applied migrations.

1. **Start PostgreSQL**

    Check the daemon, then create one local password:

    ```sh title="Terminal — application root"
    docker version
    openssl rand -hex 24
    ```

    Add the following values to your untracked `.env.local`, replacing both placeholders with
    the same generated password. Preserve other entries. Port `5433` must be free; if you change
    it, change both the connection URL and Compose port mapping.

    ```dotenv title=".env.local"
    RELKIT_LOCAL_DATABASE_PASSWORD=PASTE_GENERATED_HEX
    DATABASE_URL=postgres://relkit:PASTE_GENERATED_HEX@127.0.0.1:5433/relkit
    ```

    Create `compose.local.yaml`, or merge this service and volume into your existing Compose file:

    ```yaml title="compose.local.yaml"
    services:
      database:
        image: postgres:16-alpine@sha256:cf78e76683b9ca8c5733cbbdce6c9262b45b6767934dd0a95e671f9a0fc20685
        environment:
          POSTGRES_DB: relkit
          POSTGRES_USER: relkit
          POSTGRES_PASSWORD: ${RELKIT_LOCAL_DATABASE_PASSWORD:?Set a local database password}
        ports:
          - "127.0.0.1:5433:5432"
        volumes:
          - database:/var/lib/postgresql/data
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U relkit -d relkit"]
          interval: 2s
          timeout: 3s
          retries: 30
    volumes:
      database:
    ```

    This pins the same PostgreSQL image used by RELKIT's local job infrastructure. The named volume
    keeps data across stops; the published port accepts only loopback connections. Start it:

    ```sh title="Terminal — application root"
    docker compose --env-file .env.local -f compose.local.yaml up -d --wait database
    docker compose --env-file .env.local -f compose.local.yaml exec database pg_isready -U relkit -d relkit
    ```

    Expect `accepting connections`. RELKIT has no `docker(postgresql())` integration; Compose owns
    this database lifecycle. Changing `POSTGRES_PASSWORD` does not rotate an initialized volume's
    password. Keep the original value across restarts.

2. **Scaffold the database service**

    ```sh title="Terminal — application root"
    bun run relkit add database --orm drizzle --dialect postgresql
    ```

    The command installs the selected Drizzle packages and declaration repair, creates
    `src/services/database/service.ts`, adds an `items` table in its schema directory, and creates
    `drizzle.config.ts`. It also merges the database environment declaration. It does not start
    PostgreSQL or apply migrations. See the [command reference](/docs/api/cli#relkit-add-database).

3. **Check the environment contract**

    Keep `DATABASE_URL: env.secret()` in the generated `src/platform/env.ts` and pass that
    environment descriptor to `defineApp({ env })` in `relkit.config.ts`. The same configuration
    can be expressed inline as this complete minimal example:

    ```ts title="relkit.config.ts — equivalent inline environment"
    /** Validate the database connection before activating the Drizzle service. */
    import { defineApp, defineEnv, env } from "@relkit/app/config";

    export default defineApp({
      env: defineEnv({ DATABASE_URL: env.secret() }),
    });
    ```

    Merge the field into your app's existing contract; retain its ID and other settings. The
    generated Drizzle client reads `context.env.DATABASE_URL` through its `client({ env })` factory.
    There is no `database` profile to add to `defineApp`: the specialized service registers it.
    `RELKIT_LOCAL_DATABASE_PASSWORD` belongs to Compose and need not be exposed to application functions.

    ```sh title="Terminal — application root"
    bun run relkit env check
    ```

    Bun loads `.env.local`; `.env.example` is only a template. Drizzle Kit and the app must use
    the same `DATABASE_URL`. Keep production credentials out of this local file and browser bundles.

4. **Generate and apply a migration**

    Review the scaffolded table, then generate the initial migration:

    ```sh title="Terminal — application root"
    bun --bun drizzle-kit generate --name=initial
    ```

    Review the SQL and snapshots in `src/services/database/migrations`. Apply the reviewed history
    to the local database and start the app:

    ```sh title="Terminal — application root"
    bun run relkit db migrate
    bun run check
    bun run typecheck
    bun run dev
    ```

    Expect successful migration, checks, and server readiness. In another terminal, verify that
    the scaffolded table exists:

    ```sh title="Second terminal — application root"
    docker compose --env-file .env.local -f compose.local.yaml exec database psql -U relkit -d relkit -c '\dt'
    ```

    Expect `items` in the table list. If you renamed the schema table, check its new name instead.
    `check`, `build`, and `dev` never apply migrations for you.

    Before running application tests, update existing HTTP fixtures to import
    `createTestApplication` from `@relkit/testing/drizzle` and supply an explicit test environment.
    The harness does not inherit `.env.local`. Use a separate test database and apply its migrations;
    follow [database testing](/docs/modules/database/testing) before changing the fixtures.

## Stop and resume without resetting data

Stop the application with Ctrl+C, then stop its database:

```sh title="Terminal — application root"
docker compose --env-file .env.local -f compose.local.yaml stop database
```

Run the earlier `up -d --wait` command to resume with the same volume and password. Keep
your schema, migration history, and volume; do not remove volumes to resolve a migration error.

Continue with [Drizzle services](/docs/modules/database/drizzle),
[schema definitions](/docs/modules/database/schema), or [authentication setup](/docs/modules/auth#pre-setup).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/config` API](/docs/api/config)
- [`@relkit/app` API](/docs/api/app)

- [`apps/docs/examples/setup/postgresql.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/postgresql.ts)
- [`apps/docs/examples/setup/compose.yaml`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/compose.yaml)

---

# Migrations
Source: https://relkit.dev/docs/modules/database/migrations

A migration applies a reviewed schema change to a database. With Drizzle, generate migrations from your TypeScript tables using Drizzle Kit. You do not write table-creation statements in `defineDrizzleService`
or maintain a second handwritten copy of your schema.

RELKIT's `check`, `build`, and `dev` commands do not apply migrations. Migrate the database before
starting code that depends on its new shape.

1. ## Configure Drizzle Kit

    > **Before you begin**
    >
    > Complete [database installation](/docs/modules/database/define#install-compatible-packages) first.
    > That setup selects the compatible ORM, development-only Drizzle Kit and application-owned
    > declaration repair; the database scaffold installs them automatically. Keep that cohort and
    > lockfile together instead of installing an arbitrary Kit version separately.

    Add this application-root configuration, adjusting the schema path for your app:

    ```ts title="drizzle.config.ts"
    /** Points native Drizzle tooling at grouped model tables and rejects empty or in-memory migration targets. */
    import { defineConfig } from "drizzle-kit";

    const path = process.env.DATABASE_PATH;
    if (path === undefined || path.trim() === "" || path === ":memory:") {
      throw new Error("Set DATABASE_PATH to the persistent SQLite file you intend to migrate");
    }

    export default defineConfig({
      schema: "./src/services/database/schema/index.ts",
      dialect: "sqlite",
      out: "./src/services/database/migrations",
      dbCredentials: { url: path },
    });
    ```

    `schema` points to the same table exports used by the service. `dialect` describes the database,
    `out` owns the generated migration history, and `dbCredentials` selects the migration target.
    The configuration deliberately requires an explicit persistent file path. A separate process cannot
    migrate the in-memory connection later opened by your application.

    The example's package scripts use `bun --bun drizzle-kit generate` and
    `relkit db migrate`. Shared migration execution lives in installed RELKIT tooling;
    SQLite uses the Bun-native driver without a copied runner. PostgreSQL/MySQL
    delegate to the application's installed Drizzle Kit under Bun.

    Keep SQL and required metadata tracked in `src/services/database/migrations`, beside
    the owning service and schema. Auth and business tables share this one ordered
    history; `.relkit/` contains ignored runtime/build output, not migration source.

2. ## Generate, review, and apply

    For a new app and a new local file, run these commands from the application root:

    ```sh
    export DATABASE_PATH=./data-model.sqlite
    bun --bun drizzle-kit generate --name=initial
    bun run db:migrate
    bun run check
    bun run typecheck
    bun run dev
    ```

    If you are running the repository example, its initial migration is already generated and checked in;
    start with `bun run db:migrate` after setting `DATABASE_PATH`. Use the same path for the migration
    command and the running server. Run from the application root containing package.json
    and relkit.config.ts. Select another config with `bun run relkit db migrate --config
    configs/database.ts`; the default is root `drizzle.config.ts`. Its connection, output
    and supported log settings are authoritative. Relative database/output paths still
    use the application root even for nested or absolute config selections.

    Bun loads the application's normal dotenv files, with inherited variables taking
    precedence; `.env.example` is never loaded. Keep PostgreSQL/MySQL configuration
    deterministic because delegated Kit loads it again. Missing tooling is an explicit
    installation error; the migration command never downloads packages implicitly.

    `generate` compares TypeScript schema definitions with migration snapshots and creates migration
    artifacts; it does not modify your database. Review the generated changes before applying them.
    `migrate` applies pending migrations and records their history. See the official
    [Drizzle Kit generate guide](https://orm.drizzle.team/docs/drizzle-kit-generate) and
    [migrate guide](https://orm.drizzle.team/docs/drizzle-kit-migrate) for the tooling contract.

    Commit the generated migration directory, including snapshots, alongside the schema change. Let Kit
    own the output layout. Do not hand-edit generated snapshots or rewrite migrations already applied to
    shared environments. Native statements and advanced manual migrations belong in the
    [Drizzle documentation](https://orm.drizzle.team/docs/sql), not the normal service setup.

## Change an existing model

Edit the relevant Drizzle table, then generate a new named migration:

```sh
export DATABASE_PATH=./data-model.sqlite
bun --bun drizzle-kit generate --name=users-change
```

Review the diff and test it on an isolated copy of the old schema with representative data. After
verification, apply the pending migrations to the intended target with `bun run db:migrate`
(or `bun run relkit db migrate` if you have not added the script).

Keep model changes, generated artifacts, and affected application contracts in the same change.
Renames need particular attention so they are not mistaken for deleting and recreating data.

A database created by older demo bootstrap code or by another tool has no matching Drizzle migration
history. Do not blindly apply the initial migration to it. Establish a baseline using a workflow
appropriate to your existing database and Drizzle version before continuing. Do not use a reset or
force flag to make an existing database fit the tutorial.

## Deploy without racing application replicas

Run migrations as one coordinated deployment step, with deliberate credentials and the required
Drizzle tooling/configuration/artifacts available. Do not run schema changes in a request handler
or have every server replica migrate at startup.

For changes used by running versions, prefer an additive field or table, a controlled backfill,
a compatible application rollout, and only then removal of the old shape. Non-null fields may need
defaults or a backfill; unique constraints may fail on existing duplicates.

Before destructive changes, verify backups, restoration, the exact database target, and lock/downtime
expectations. A rollback cannot necessarily recover discarded data. Keep seeding separate from
migrations and normal server startup.

For PostgreSQL or MySQL, use matching table definitions, Kit dialect/connection settings, and the
appropriate driver. This executable workflow verifies Bun SQLite; it is not a test of other dialects.

## Verify migrations separately from queries

From the data-model example root:

```sh
bun test tests/migrations.test.ts
bun test tests/data-model.test.ts
bun run check
bun run typecheck
```

The migration test invokes shared RELKIT tooling against a temporary file, writes data through Drizzle, and
runs migrations again to verify that the data survives. Application tests apply the generated
migration to their own isolated connection. As history grows, add upgrade tests from deployed
versions, not just tests of an empty database.

`relkit db migrate --json` emits one secret-safe result after cleanup: success
identifies command, dialect and config/history paths, without inventing an applied
count. Usage/configuration errors exit 2, operational failures 1, interruption 130,
and success 0. Missing, empty or incompatible history fails before opening the
target database and points to generation/compatibility checks. Failed SQL is not
automatically retried; partial DDL rollback is not guaranteed.

See [Testing](/docs/modules/database/testing) for the executable tests and
[Better Auth](/docs/modules/database/better-auth) before adding authentication tables.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/data-model/drizzle.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/drizzle.config.ts)

---

# Custom models
Source: https://relkit.dev/docs/modules/database/models

Add a model when a table needs a named operation beyond the built-in CRUD methods. A model extends the table client with
named functions; it does not create a new table, require a class, or replace the owning business service.
If the six base methods are sufficient, do not create an empty model file.

> **Before you begin**
>
> Complete [database installation](/docs/modules/database/define) before importing the model API.
> Select the native model entrypoint for your dialect: `@relkit/drizzle/sqlite`,
> `@relkit/drizzle/pg`, or `@relkit/drizzle/mysql`. Each keeps the real native query-builder types
> in that selected declaration graph. The general root supports portable service operations and
> table-only model extensions; it does not implicitly select every dialect's native database type.
> Install your chosen Drizzle driver explicitly. In particular, the pinned MySQL declaration graph
> requires `mysql2`; a SQLite application does not need that driver.

Only when selecting the MySQL model entrypoint, add its declaration requirement:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add --dev 'mysql2@>=2.0.0'
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

1. ## Define an extension beside the schema

    ```ts title="src/services/database/models/users.model.ts"
    /** Extends the native users model with email-domain selection and an update that conceals missing or inactive rows. */
    import { defineModel, type UpdateArgs } from "@relkit/drizzle/sqlite";
    import { eq, like } from "drizzle-orm";
    import { users } from "../schema/index.js";

    export default defineModel({
      table: users,
      extend: {
        byEmailDomain: ({ table, database }, domain: string) =>
          database
            .select()
            .from(table)
            .where(like(table.email, `%@${domain}`)),
        findOneAndUpdate: async ({ table, database }, args: UpdateArgs<typeof users>) => {
          const id = args.where.id;
          if (id === undefined) return null;
          const [existing] = await database.select().from(table).where(eq(table.id, id));
          if (existing === undefined || existing.active === false) return null;
          const [updated] = await database
            .update(table)
            .set(args.data)
            .where(eq(table.id, id))
            .returning();
          return updated ?? null;
        },
      },
    });
    ```

    `table` must be the exact table object exported by the service's schema. `extend` must contain at least
    one function. Names such as `byEmailDomain` and `findOneAndUpdate` become methods on the Users table client.

    The first extension argument is injected: `{ table, database }`. Additional arguments form the consumer
    API, and return types are preserved. Use this parameter instead of class state such as `this.drizzle`
    or `this.table`.

2. ## Register and call the model

    Import the model into `src/services/database/service.ts` and add `models: { users: usersModel }` to
    `defineDrizzleService`. The registration key must match the schema export key, and the model must use
    that same table object. A file under `models/` is not automatically registered just because it exists.

    After `bun run check` refreshes context types, functions call the method without supplying the injected
    first argument:

    ```ts title="src/services/users/functions/list-users.function.ts"
    /** Lists validated user fields through the database model's email-domain extension. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      input: z.object({ domain: z.string() }),
      output: z.array(z.object({ id: z.number(), email: z.string(), active: z.boolean() })),
      handler: ({ domain }, context) => context.database.users.byEmailDomain(domain),
    });
    ```

    Keep business entry points in their owning domains and expose them through [Service](/docs/modules/service).
    Do not make routes or other domains import private table files just to construct a query.

## Use native Drizzle where it helps

The injected `database` provides the dialect's query builder for joins, aggregations, projections, and
native mutations. It is not the portable `context.database`, so do not expect `database.users.findOne`
inside the extension. The public extension type intentionally omits Drizzle's relational `query` API;
use the supported query-builder surface rather than assuming relation-loading types are present.

An extension called through the context supplied by `transaction` receives the transaction-bound client.
Use that injected client, not a separately imported connection. See [Transactions](/docs/modules/database/transactions).

## Make custom behavior explicit

Custom methods bypass the portable CRUD implementation and its operation overrides. Add the validation,
tenant restrictions, limits, and result checks the query needs. You cannot use an extension named
`findOne`, `findMany`, `insert`, `update`, `upsert`, or `delete`; use
[operation overrides](/docs/modules/database/overrides) to customize those names.

The sample `byEmailDomain` uses Drizzle's `like()` expression: values are parameterized, but `%` and `_`
in the supplied domain still act as pattern wildcards. It also has no pagination. Validate or escape
patterns and add an explicit limit before using it as a public search feature. For native statements
beyond the query builder, refer to [Drizzle's documentation](https://orm.drizzle.team/docs/sql).

Likewise, `findOneAndUpdate` performs a read followed by an update; its name does not make the sequence
atomic. Protect concurrent state changes with an appropriate database operation and test it. The
[model test](/docs/modules/database/testing) verifies the demonstration behavior without implying stronger guarantees.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/data-model/src/services/database/models/users.model.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/models/users.model.ts)

---

# Override operations
Source: https://relkit.dev/docs/modules/database/overrides

Use an override when an existing CRUD operation needs different behavior. Use [models](/docs/modules/database/models) when adding a new named operation instead. Overrides are registered
by schema table key, then by one of the six reserved CRUD names.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## Wrap the base behavior

The data-model example hides inactive users from `findOne`:

```ts title="src/services/database/service.ts — overrides"
overrides: {
  users: {
    findOne: async ({ args, base }) => {
      const user = await base(args);
      return user?.active === false ? null : user;
    },
  },
},
```

The callback receives `{ args, base }`. `args` has that operation's argument shape. `base(args)` runs
the original implementation directly, without calling the same override again. You may transform the
arguments, inspect the result, or return a replacement result that respects the operation's contract.

For example, `findOne` returns a row or `null`, while `findMany` returns an array. Do not change the
return shape to an HTTP response or an unrelated DTO. Put that mapping in a public business function.

## Know the scope of an override

This override affects calls to `users.findOne`. It does not automatically filter `findMany`, mutations,
custom model methods, or the internal helper reads used by other base operations such as `upsert`.
An inactive user is hidden by `findOne` but is still returned by an explicit `findMany` query. This is a
read-convenience example, not a complete soft-delete or access-control policy.

If you need soft deletion, decide how every read, write, custom query, unique constraint, and restoration
path behaves. If you need tenant isolation, enforce it at the business boundary and/or database layer;
do not assume one filter override secures the whole table client.

## Work within the callback contract

Overrides receive neither request context nor the injected native client that model extensions receive.
Do not store a current user or request-specific state in a module-level variable used by a shared service.
Pass validated business facts through a suitable function or named operation instead.

For advanced Drizzle queries, prefer a custom method using its injected client. Capturing an unrelated global
client inside an override can escape the active transaction. Calling `base` uses the current binding.
Keyless tables require replacements for `findOne`, `update`, `upsert`, and `delete`; delegating unchanged
arguments to `base` does not remove its unique-selector requirement.

## Verify the changed contract

Test both the overridden operation and the paths it does not cover. Include missing rows, invalid input,
and transaction behavior. Overrides bypass base checks when they do not call `base`, so replacement
implementations own the equivalent validation and safety checks.

From the data-model example root, run:

```sh
bun test tests/data-model.test.ts
bun run typecheck
```

Use [Testing](/docs/modules/database/testing) for safe database lifetimes and
[Transactions](/docs/modules/database/transactions) before composing multiple writes.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/data-model/src/services/database/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/service.ts)

---

# Query data
Source: https://relkit.dev/docs/modules/database/queries

Read and change records from a function through `context.database.<table>`. This context is not a raw
Drizzle client: it exposes a deliberately small API whose return values are consistent across supported
dialects. For more advanced Drizzle queries, add a [custom model method](/docs/modules/database/models).

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## Choose an operation

| Method     | Arguments                                                   | Result                  |
| ---------- | ----------------------------------------------------------- | ----------------------- |
| `findOne`  | `{ where }` with a complete unique selector                 | Row or `null`           |
| `findMany` | Optional `{ where, orderBy, limit, offset }`                | Array of rows           |
| `insert`   | `{ data }`                                                  | Inserted row            |
| `update`   | `{ where, data }` with a complete unique selector           | Updated row or `null`   |
| `upsert`   | `{ where, create, update }` with a complete unique selector | Inserted or updated row |
| `delete`   | `{ where }` with a complete unique selector                 | Deleted row or `null`   |

Mutations accept one record, not a bulk array. Handle a missing row explicitly in your business function;
the database operation does not turn `null` into an HTTP `404`. Use a [declared error](/docs/learn/concepts/errors)
when that is part of your public contract.

For example, this Users operation changes an email address, handles a missing row, and returns an
explicit public shape. The generated update schema validates row data; the function contract validates
the caller's input:

```ts title="src/services/users/functions/update-user-email.function.ts"
/** Validates native update/select data and returns the changed user's email or null when its row is unavailable. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({ userId: z.number().int().positive(), email: z.string().email() }),
  output: z.object({ userId: z.number(), email: z.string() }).nullable(),
  handler: async ({ userId, email }, context) => {
    const data = context.database.zodSchemas.users.update.parse({ email });
    const row = await context.database.users.update({ where: { id: userId }, data });
    if (row === null) return null;
    const user = context.database.zodSchemas.users.select.parse(row);
    return { userId: user.id, email: user.email };
  },
});
```

This internal example is not mounted as an HTTP write endpoint. Check the caller's permission to edit
the selected user before exposing it. See [Generated CRUD and schemas](/docs/modules/database/generated-schemas)
for what the validators generate and what they do not enforce.

## Use complete selectors for single rows

The `where` type is a partial row, but runtime validation requires a complete detected primary or unique
key for `findOne`, `update`, `upsert`, and `delete`. Additional equality fields are allowed; all supplied
fields participate in the filter. Unknown columns and null/undefined selector values are rejected.

For the example's membership table, use `memberships.findOne({ where: { organizationId, userId } })`:
both fields form the unique identity. An organization-only selector fails instead of selecting or
mutating an arbitrary member. Use `findMany` when multiple matches are intentional.

## Filter and paginate lists

Portable `where` combines equality comparisons: all supplied fields must match. In `findMany`, `null` matches null values and
`undefined` is invalid. Omit a filter field instead of passing `undefined`. An omitted or empty `where`
allows all rows, subject to pagination.

`findMany` defaults to `limit: 100` and `offset: 0`. Limits are integers from zero through 1,000; offsets
are nonnegative integers. `orderBy` accepts one column and `"asc"` or `"desc"`. Specify a stable ordering
for pagination rather than relying on the database's incidental row order.

Alternative-match filters, ranges, pattern matching, joins, cursors, bulk writes, counts, and selected-column projections are not
portable options. Implement the needed query in a model, with its own input validation and result limits.
Keep queries parameterized through Drizzle's query builder. For native statements, see the
[Drizzle documentation](https://orm.drizzle.team/docs/sql).

## Understand dialect and upsert limits

The current portable `upsert` reads first, then inserts or updates. It is not a native atomic conflict
statement. Concurrent writers can race; keep a unique database constraint and use a dialect-specific
atomic operation or a tested concurrency strategy when required. Ensure `create` identifies the same
logical row as `where`.

SQLite and PostgreSQL normally return mutation rows using `returning()`. For MySQL, the integration wraps
mutations in a transaction and reads back the row using a recoverable unique key. An insert that supplies
only an unknown database-generated ID and no other unique value needs an override. Driver differences
and isolation behavior still need real-database tests.

Model calls are not function invocations of their own. They do not automatically receive function
retry policy, a per-query abort signal, or declared-error normalization. Configure driver timeouts and
translate expected database failures at the business boundary without exposing database internals or credentials.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/data-model/src/services/users/functions/update-user-email.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/users/functions/update-user-email.function.ts)

---

# Define the schema
Source: https://relkit.dev/docs/modules/database/schema

Define your tables in `src/services/database/schema/` and export them from that directory's `index.ts`. The service's
`schema` map determines which tables appear on `context.database`. You do not need a custom model file
for every table: base operations are provided automatically.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## Model columns and defaults

```ts title="src/services/database/schema/index.ts — users"
export const users = sqliteTable("users", {
  id: integer().primaryKey({ autoIncrement: true }),
  email: text().notNull().unique(),
  active: integer({ mode: "boolean" }).notNull().default(true),
});
```

The exported key `users` becomes `context.database.users`; `sqliteTable("users", ...)` names the stored
table. Column object keys are the names you use in filters and data, even if you explicitly choose
different database column names.

Here, `id` is an auto-incrementing primary key, `email` is non-null and unique, and `active` is a boolean
mapped to SQLite's integer storage with a default of `true`. Defaults allow those values to be omitted
from inserts. Nullable columns and optional insert fields are different concepts; review both the
selected row type and insert type after changing a column.

Use one dialect throughout the service. Its schema export map must contain the table objects directly,
not nested namespace objects. Non-table exports do not become portable table clients.

## Define identities the portable API can use

Single-row operations require a complete primary or unique selector. The example's membership identity
is a pair, not just an organization ID:

```ts title="src/services/database/schema/index.ts — memberships"
export const memberships = sqliteTable(
  "memberships",
  {
    id: integer().primaryKey({ autoIncrement: true }),
    organizationId: text().notNull(),
    userId: integer().notNull(),
    role: text().notNull(),
  },
  (table) => [uniqueIndex("membership_identity").on(table.organizationId, table.userId)],
);
```

You can select a membership by its `id`, or by both `organizationId` and `userId`. A non-unique index
helps query performance but does not make a safe single-row selector. Nullable key values are rejected
by the portable selector check even when the database column allows null.

A keyless table requires explicit overrides for `findOne`, `update`, `upsert`, and `delete` before the
service can be defined. Prefer a real row identity when possible. Partial or expression indexes require
care: do not assume their uniqueness can be represented by the portable selector metadata. Inspect the
checked service and use a dedicated operation when necessary.

## Model relationships and constraints explicitly

A field named `userId` is not automatically a foreign key. The membership example declares uniqueness
but no foreign-key constraint. Add native Drizzle references, indexes, checks, and delete/update policies
for your actual model, then apply matching migrations. With SQLite, also configure and test foreign-key
enforcement on the connection; a relationship type alone is not enforcement.

The portable client does not provide relation loading, joins, projections, or aggregation options.
Use [custom models](/docs/modules/database/models) with Drizzle's query builder for those queries. Keep database
constraints for durable integrity and function validation for actionable caller errors; neither replaces
authorization or tenant scoping.

## Use generated validation deliberately

The service creates `context.database.zodSchemas.<table>.select`, `.insert`, and `.update` from Drizzle's
table definitions. Use `.parse()` or `.safeParse()` explicitly where needed. The base operation layer
does not automatically run these Zod schemas around every read or write.

A text column named `email` produces string validation, not an email-address business rule. Define
the public function's input with the required business validation, and expose only the output fields
callers should receive. Do not accept an entire insert shape from an untrusted caller if it includes
server-owned IDs, roles, tenant IDs, or account flags.

Continue with [Generated CRUD and schemas](/docs/modules/database/generated-schemas) for the complete
select/insert/update shapes, runtime parsing, and customization examples. Apply table changes through
[Drizzle Kit migrations](/docs/modules/database/migrations); changing this file alone does not alter stored data.

The public utility types include `Row`, `InsertArgs`, `Update`, `UpdateArgs`, and `DatabaseContext`.
Use the [Drizzle API reference](/docs/api/drizzle) for their exact shapes and
[Schemas](/docs/learn/concepts/schemas) for function contracts.

## Apply a schema change in both places

Edit the table source, generate and review the Drizzle Kit migration, apply it to an isolated database, and rerun
the application checks and focused tests. Adding a column in TypeScript does not alter an existing
table, and `bun run check` does not run migrations. Continue with [Migrations](/docs/modules/database/migrations).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/schema` API](/docs/api/schema)

- [`examples/data-model/src/services/database/schema/index.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/database/schema/index.ts)

---

# Testing
Source: https://relkit.dev/docs/modules/database/testing

Verify queries, constraints, and rollback against an isolated database with your actual schema. Portable method mocks are useful
for narrow business tests, but they do not prove constraints, query semantics, rollback, or driver behavior.
Never point a test at a production connection or an existing developer database by default.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

For application HTTP fixtures, use `createTestApplication` from `@relkit/testing/drizzle` after
adding a database. Update existing fixtures too, including tests of routes that do not query data:
the fixture loads the whole application's services. When the app also declares Better Auth, use
`@relkit/testing/better-auth` instead. The generic `@relkit/testing` application helper deliberately
does not acquire either native integration. See [the updated Hello fixture](/docs/learn/save-orders#keep-existing-http-tests-compatible).

## Activate and close a service explicitly

`activateDrizzleService(service, env)` returns `{ client, context, close }`. `client` is the native Drizzle
client, `context` is the portable database API, and `close()` invokes the service's disposal hook.
Direct activation takes resolved environment values; it does not parse your environment contract for you.

The executable data-model test uses SQLite in memory and applies the generated Drizzle migration to
that same connection before making queries. The application service does not create tables:

[Complete data-model test](https://github.com/rel-kit/relkit/blob/main/examples/data-model/tests/data-model.test.ts)

Run it from the example or application root:

```sh
bun test tests/data-model.test.ts
```

It checks generated validation, all six CRUD operations, custom methods, override scope, composite
selectors, pagination limits, and rollback. It also invokes the actual member-registration and email-change
functions with an injected database context, testing both their generated schemas and public input
validation. `finally` closes the database even when an assertion fails.

## Isolate activation lifetimes

Repeated activation of the same descriptor object shares one cached activation. Changing the environment
on a later call does not create a different database, and closing it does not currently remove the cache.
Use one shared lifetime deliberately, a fresh descriptor for each independent test, or process isolation.
Do not close the shared descriptor after one test and expect a second activation to reopen it.

An in-memory SQLite database belongs to its connection, not to the whole test suite or development server.
A test that inserts a row does not seed a separately running application. For persistence and restart
tests, use an explicit temporary file and close all connections before cleaning up that test-owned path.

## Test migrations separately

The migration regression test launches Drizzle Kit twice against a temporary file and inserts rows
through Drizzle between runs. A successful repeat verifies that the initial migration is not applied
again and that the existing rows remain:

```ts title="tests/migrations.test.ts"
/** Runs native Drizzle migrations in an owned SQLite fixture, checking invalid targets and row preservation across repeat migration. */
import { expect, test } from "bun:test";
import { Database } from "bun:sqlite";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { drizzle } from "drizzle-orm/bun-sqlite";
import { users, memberships } from "@app/services/database/schema/index.js";

test("rejects empty and in-memory migration targets", async () => {
  for (const path of ["", ":memory:"]) {
    const child = Bun.spawn([process.execPath, "drizzle.config.ts"], {
      cwd: resolve(import.meta.dir, ".."),
      env: { ...process.env, DATABASE_PATH: path },
      stdout: "pipe",
      stderr: "pipe",
    });
    const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()]);
    expect(code).not.toBe(0);
    expect(stderr).toContain("Set DATABASE_PATH to the persistent SQLite file");
  }
});

// The finite harness allowance includes two native Drizzle CLI cold starts.
test("applies the initial migration once and keeps rows on a second run", async () => {
  const root = await mkdtemp(join(tmpdir(), "relkit-database-migrations-"));
  const path = join(root, "test.sqlite");
  try {
    for (let run = 0; run < 2; run++) {
      const child = Bun.spawn([process.execPath, "run", "db:migrate"], {
        cwd: resolve(import.meta.dir, ".."),
        env: { ...process.env, DATABASE_PATH: path },
        stdout: "pipe",
        stderr: "pipe",
      });
      const [code, stdout, stderr] = await Promise.all([
        child.exited,
        new Response(child.stdout).text(),
        new Response(child.stderr).text(),
      ]);
      if (code !== 0) throw new Error(`Migration failed: ${stdout}\n${stderr}`);
      expect(stdout).toContain("Database migrations applied.");
      const sqlite = new Database(path);
      try {
        const database = drizzle({ client: sqlite });
        if (run === 0) {
          const [user] = await database
            .insert(users)
            .values({ email: "one@example.com" })
            .returning();
          if (user === undefined) throw new Error("User insert did not return a row");
          await database.insert(memberships).values({
            organizationId: "org",
            userId: user.id,
            role: "owner",
          });
        }
        expect(await database.select().from(users)).toMatchObject([
          { email: "one@example.com", active: true },
        ]);
        expect(await database.select().from(memberships)).toMatchObject([{ role: "owner" }]);
      } finally {
        sqlite.close();
      }
    }
  } finally {
    await rm(root, { recursive: true, force: true });
  }
}, 30_000);
```

```sh
bun test tests/migrations.test.ts
```

Add upgrade fixtures for existing data, constraints, and backfills as migrations accumulate. A bootstrap
test on an empty database is not a replacement for testing upgrades from deployed schema versions.

## Choose the right application harness

`createTestApplication` discovers the Drizzle service and activates its real client factory with the test
environment. Set an isolated temporary path explicitly, migrate that file before starting the harness,
and close the application afterward. The environment name alone does not make a custom database factory safe.
For an in-memory database, migrations must run on the harness's actual connection; a separate process
or another in-memory connection cannot initialize it. Direct activation as shown above gives the test
control over that client.

A standalone `invokeFunction` test does not automatically discover and activate the app's Drizzle service.
Provide a database context through its context hook, or use the application harness when you need service
discovery and HTTP together. See [Testing](/docs/modules/operations/testing) and the [Testing API](/docs/api/testing).

Run additional contract tests on the production dialect for transaction isolation, concurrent writes,
native model methods, and MySQL row recovery. The repository-backed database tutorial tests SQLite; it
does not claim PostgreSQL or MySQL behavior was exercised by those tests.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/testing` API](/docs/api/testing)

- [`examples/data-model/tests/data-model.test.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/tests/data-model.test.ts)

---

# Transactions
Source: https://relkit.dev/docs/modules/database/transactions

Use a transaction when related database changes must either all succeed or all be rolled back. The callback receives another database context with the same table methods, models,
overrides, and validation schemas, bound to the transaction.

> **Before you begin**
>
> Before using these examples, complete [database installation and
> configuration](/docs/modules/database/define), including the selected adapter, native ORM, tooling
> and application-owned patch.

## Use the callback's context

Registering a new member creates two records: the user and their organization membership. Neither
should remain without the other if a write fails:

```ts title="src/services/users/functions/register-member.function.ts"
/** Validates native user data and creates the user/membership in one borrowed database transaction, retaining rollback failures. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  input: z.object({ email: z.string().email(), organizationId: z.string().min(1) }),
  output: z.object({ userId: z.number(), membershipId: z.number() }),
  handler: async ({ email, organizationId }, context) => {
    const data = context.database.zodSchemas.users.insert.parse({ email });
    return context.database.transaction(async (tx) => {
      const user = await tx.users.insert({ data });
      const membership = await tx.memberships.insert({
        data: { organizationId, userId: user.id, role: "member" },
      });
      return { userId: user.id, membershipId: membership.id };
    });
  },
});
```

The function validates input, builds the insert data with a generated schema, and awaits both writes
inside the callback. If the membership insert fails after the user insert, neither new record is kept.
If both succeed, the caller receives their IDs. The role is chosen by the application, not the caller.

This example models persistence, not permission to invite members. Check the caller's organization
access before invoking the workflow; it is intentionally not mounted as a public write route.

If the callback resolves, the transaction commits and returns its value. If it rejects, the transaction
rolls back and the error propagates. Catching an error inside the callback and returning normally can
commit the preceding changes; throw when the whole operation must fail.

Await every operation. Use `tx.users` rather than the outer database context inside the callback.
Custom model methods invoked on `tx` receive the bound native Drizzle transaction client, and overrides
that call `base` use that binding too.

## Understand the portable limits

Nested portable transactions are rejected; savepoints and isolation-level options are not exposed by
this helper. PostgreSQL and MySQL delegate to the driver's transaction implementation. SQLite manages
the transaction on its shared connection and serializes portable transaction callbacks per client object.

That SQLite serialization is not a global lock: ordinary operations outside the helper are not gated
by it. On a shared SQLite connection, unrelated work can interleave with an open transaction. Do not
assume the helper provides per-request isolation under concurrent traffic. Use a driver/connection
strategy appropriate to the workload and verify it with concurrency tests.

A transaction does not automatically make a read-then-write sequence race-free at every isolation
level. The portable `upsert` and the sample `findOneAndUpdate` both perform separate statements. Use
database uniqueness, conditional writes, native conflict handling, and deliberate isolation where needed.

## Keep transactions short and database-only

Do not wait for an AI model, a remote HTTP call, or a long-running job inside a database transaction.
Locks and connections remain occupied, and a function deadline does not guarantee cancellation of a
query or rollback of an external effect. Configure driver-level timeouts and cancellation as supported.

Publishing an [event](/docs/modules/events), enqueueing a [job](/docs/modules/jobs), or writing a [bucket object](/docs/modules/storage)
inside this callback does not enlist that system in the database transaction. A rollback cannot undo
those effects. Use a suitable transactional outbox or reconciliation design when a committed change
must reliably trigger follow-up work; RELKIT does not create that guarantee merely by awaiting both calls.

## Test the failure path

Assert that committed rows remain and rolled-back rows do not. Add tests for custom methods called through
`tx`, constraint failures, and the concurrency behavior your application depends on. Use a real isolated
database when testing transactions, not an object mock that only counts calls.

Continue with [Migrations](/docs/modules/database/migrations) for changes to the schema itself, or
[Testing](/docs/modules/database/testing) for activation and cleanup.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)

- [`examples/data-model/src/services/users/functions/register-member.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/users/functions/register-member.function.ts)

---

# Deployment
Source: https://relkit.dev/docs/modules/deployment

Deployment makes a checked application run in its target environment. Begin with local Docker
for development dependencies and container verification, then choose how to host the built server
and supply its production resources.

## Pre-setup

Complete each module's local configuration before building: [database](/docs/modules/database#pre-setup),
[auth](/docs/modules/auth#pre-setup), [storage](/docs/modules/storage#pre-setup),
[cache](/docs/modules/caching#pre-setup), [jobs](/docs/modules/jobs#pre-setup), and
[realtime](/docs/modules/realtime#pre-setup). Keep required application values in `defineEnv`
and connect that descriptor through `defineApp({ env })`.

From the backend root, verify the application before choosing a deployment target:

```sh title="Terminal — application root"
bun run check
bun run typecheck
bun run test
bun run build
```

These commands create no cloud resources. A production server receives secrets from its process
environment; the build does not embed `.env` values. Preserve application state, database migrations,
and immutable worker versions across releases.

**[Start with local Docker](/docs/modules/deployment/local-docker)**

Run local services, then build and verify the minimal app in a container.

**[Deploy to AWS with Pulumi](/docs/modules/deployment/aws)**

Install the supported host and engine, configure roles, preview, and apply a reviewed stack.

**[Run a built Bun server](/docs/modules/deployment/aws#run-a-built-application)**

Install the generated production manifest and start the complete build on your own host.

**[Connect production resources](/docs/modules/deployment/providers)**

Choose storage, cache, database, task, and telemetry providers independently of the host.

## Supported providers

| Role                                | Supported path                                                         | What RELKIT manages                                                                                                                                           |
| ----------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Local development services          | Docker recipes for Redis, MinIO, Inngest, Trigger.dev, and Effect MQ   | Graph-required containers, readiness, connection values, and persistent volumes; [coverage](/docs/modules/integrations/local-docker#supported-local-services) |
| Self-hosted application             | Built Bun server or generated Docker image                             | Portable build output; you provide the host, process/container supervisor, TLS, and resource connections                                                      |
| Cloud application host              | **AWS**, through `@relkit/aws`                                         | ECS/Fargate, networking, load balancer, workload access, and CloudWatch stdout; [AWS setup](/docs/modules/deployment/aws)                                     |
| Infrastructure engine               | **Pulumi**, through `@relkit/pulumi`                                   | Stack configuration, preview, apply, outputs, refresh, and destroy                                                                                            |
| Infrastructure-owned resources      | AWS wrappers for supported S3 and Redis/Valkey resources               | Resource lifecycle and access, separately from the application host                                                                                           |
| Connected file/cache resources      | S3-compatible storage, Redis, Cloudflare R2 and KV                     | Runtime connections to existing resources; [provider configuration](/docs/modules/deployment/providers)                                                       |
| Native durable tasks                | Inngest, Trigger.dev, Effect MQ                                        | Provider-specific worker publication, schedules, and supported run semantics; [job deployment](/docs/modules/jobs/deployment)                                 |
| Application data and authentication | Drizzle with PostgreSQL, MySQL, or SQLite; Better Auth on that service | Application connection and auth activation; you own database hosting, migrations, and backups                                                                 |
| Models and telemetry                | Selected LangChain model SDKs, Sentry, OTLP                            | Selected runtime integration; no implicit provisioning or model account                                                                                       |

AWS is the current built-in cloud **host**. The Cloudflare package provides **R2/KV runtime
adapters**, not Workers application deployment. There are no built-in Vercel, Railway, Azure,
or Google Cloud host integrations. A platform that runs the built Bun server or image can be
used through the self-hosted path; that is separate from `relkit deploy` support.

Pulumi's cloud, local, and object-storage state backends store stack state; they do not add
application hosts. The native job packages also publish deployment hooks for their workers,
not alternative infrastructure engines selected by `defineApp.deployment.engine`.

## Move from local to production deliberately

`docker(adapter)` is a development selection. It does not create cloud infrastructure or make
a loopback connection reachable from production. Use configured connected adapters or supported
infrastructure wrappers for release builds, and keep descriptor IDs and profile names consistent.
Verify the real provider's behavior, credentials, network access, persistence, and migrations before
accepting production traffic.

Cloud/deployment creation flags remain unavailable for new starters. Add the selected tooling to
an existing app following [AWS setup](/docs/modules/deployment/aws#install-deployment-tooling-for-an-existing-app).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/aws` API](/docs/api/integrations/aws)
- [`@relkit/pulumi` API](/docs/api/integrations/pulumi)

- [`examples/commerce/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)

---

# Deploy to AWS with Pulumi
Source: https://relkit.dev/docs/modules/deployment/aws

Deploy an application after its local checks and production build pass. Pulumi is the
deployment engine and AWS is the first host integration, but engine, host, application resources, access, and
runtime wiring remain separate roles. See [supported providers](/docs/modules/deployment) for
the full coverage table and [local Docker](/docs/modules/deployment/local-docker) for the default
development and container verification path.

## Pre-setup

Start from an existing application that passes its [local module setup](/docs/modules/integrations#pre-setup).
Install the host/engine below, configure deployment roles, and choose a separate provider profile for
each production resource. A local-only Docker profile cannot supply a production connection.

Supply application secrets through the deployment's runtime environment and declare required
application fields in `defineEnv`. Supply AWS credentials and Pulumi backend access to the deployment
process through their native credential mechanisms; do not add them to the app's public environment
or bundle. Run `bun run relkit doctor --pulumi` to check local tooling before selecting a stack.

> **Authorization and cost required**
>
> These commands can create billable resources. Use an isolated account and stack, confirm the
> target, review every preview, and continue only when authorized to incur cost.

## Run a built application

Run `bun run build` in the development installation first. The build publishes the executable
`.relkit/build/server/index.js`, its graph and manifests, public assets, and any selected immutable
job workers. Copy the complete `.relkit/build` directory into the same relative path in your
production application root.

The build's `package.json` declares exact observed versions of selected runtime integrations and
their required SDKs. Required dependency patches and overrides travel with this manifest; keep the
complete output, including `patches/` when present. Install it before starting from the application root:

```sh title="Terminal — production application root"
cd .relkit/build
bun install --production --network-concurrency 1
cd ../..
NODE_ENV=production bun run --no-env-file .relkit/build/server/index.js
```

The framework runtime is bundled. This production installation does not need the development CLI,
compiler, Inspector application, or unselected SDKs. `relkit start` remains a convenience command
where the CLI is installed; the generated `start` script uses the JavaScript command above.

Supply required application environment values through the process environment. Startup does not
automatically read dotenv files, and build output does not inline their values. `PORT` overrides the
configured listener port. Run from the application root so default local provider state remains at
`.relkit/state`; public assets are resolved beside the built server. Keep existing state and
immutable job generations when replacing build output.

The generated Dockerfile uses `.relkit/build` as its build context. It installs the selected production
manifest and copies the complete server, public assets, graph, and selected worker history. Environment
files, existing local state, and temporary build module links are excluded from that context.

## Install deployment tooling for an existing app

Cloud and deployment default to `none`. The `--cloud aws --deploy pulumi` creation tuple is
currently rejected before staging because public certification is incomplete. Configure deployment
only on an existing app; installing these packages does not make that creation tuple available.

From its development root, install the selected host/engine and deploy-only SDK peers:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add --dev @pulumi/aws@7.43.0 @pulumi/pulumi@3.259.0 @relkit/aws@0.8.2 @relkit/pulumi@0.8.3
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

These development tools generate/preview infrastructure. They do not belong in the built server's
production dependency closure, and none of these installation steps provisions cloud resources.

## Configure deployment roles

Merge the role imports and `deployment` selection into your existing `relkit.config.ts`.
Retain its application ID, environment contract, and provider profiles. This minimal complete
example selects the host and engine; it does not create any resources during import:

```ts title="relkit.config.ts"
/** Select AWS hosting and Pulumi without provisioning resources during import. */
import "@relkit/aws";
import "@relkit/pulumi";
import { defineApp, defineEnv } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({}),
  deployment: { engine: "pulumi", host: "aws" },
});
```

The [complete commerce configuration](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)
also binds storage, caching, jobs, and telemetry explicitly.

Keep the existing application's resources and runtime integrations separate from these deployment roles.
Checking and building provision nothing.

## Preview before applying

From that existing configured project, after authorization for the selected account/stack:

```sh title="Terminal — relkit-orders"
bun run check
bun run test
bun run build
bun run relkit doctor --pulumi
bun run relkit deploy init --stack development
bun run relkit deploy preview --stack development
```

Use a separate stack for each isolated environment. Supported backends are Pulumi Cloud, local state, and object
storage URLs. Use repeatable `--config key=value` options for non-secret values and `--config-secret key=value`
for Pulumi secrets.

Preview generates and validates the Pulumi program from the graph. Review create, update, replace, and delete
operations before applying:

```sh title="Terminal — relkit-orders"
bun run relkit deploy up --stack development
bun run relkit deploy outputs --stack development
```

`--non-interactive` (alias `--yes`) approves protected operations for automation; it does not replace review or
authorization.

## Understand resource ownership

An infrastructure wrapper such as `aws(s3(...))` or `aws(redis(...))` may contribute supported lifecycle and
least-privilege access operations. A configured adapter passed directly to `defineApp` contributes runtime wiring
but no resource lifecycle. `docker(adapter)` is development-only and never becomes cloud infrastructure.

Job deployment publishes the immutable task worker and registers schedules only after readiness. Keep the
previous worker generation and its routing keys while it owns accepted runs; deployment does not rewrite run
history or turn a provider without native support into a durable fallback.

The AWS host owns ECS/Fargate hosting, networking, the workload role, load balancing, and CloudWatch routing for
redacted structured stdout. It does not implicitly own application jobs, events, model providers, Sentry, or
OTLP.

## Reconcile and clean up

For an isolated temporary stack:

```sh title="Terminal — relkit-orders"
bun run relkit deploy refresh --stack development
bun run relkit deploy destroy --stack development
```

Confirm the stack before destruction and verify cleanup independently. Never edit the generated Pulumi program
to bypass graph or role validation; repair configuration or integration support, run `check`, and preview again.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/events` API](/docs/api/events)
- [`@relkit/buckets` API](/docs/api/buckets)
- [`@relkit/cache` API](/docs/api/cache)
- [`@relkit/aws` API](/docs/api/integrations/aws)
- [`@relkit/pulumi` API](/docs/api/integrations/pulumi)

- [`examples/commerce/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)

---

# Verify locally with Docker
Source: https://relkit.dev/docs/modules/deployment/local-docker

Use local Docker first. RELKIT can manage development provider recipes while Bun runs your
application, and its build can produce a server image for a separate container smoke check.

## Pre-setup

Start with the [minimal app](/docs/learn/create-an-app), a running Docker daemon, and a free
port `3000`. For optional capabilities, complete their [provider setup](/docs/modules/integrations#pre-setup)
and environment contracts first. The image check below uses the unchanged minimal app's Hello
route and no external resources or secrets.

1. **Run development dependencies**

    After configuring the app's required Docker profiles, run:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run relkit local up --detach
    bun run relkit local status
    bun run dev --local=off
    ```

    Expect required providers to become healthy and the backend to report readiness. A minimal app
    with no selected providers has no containers to start. PostgreSQL from the
    [database walkthrough](/docs/modules/database/local-docker) uses its own Compose commands.
    `--local=off` reuses the services you started explicitly.

2. **Build the minimal app's server image**

    Stop the development server with Ctrl+C so port `3000` is free, then run:

    ```sh title="Terminal — application root"
    bun run check
    bun run typecheck
    bun run test
    bun run build
    docker build -t relkit-local:docs .relkit/build
    ```

    Use the complete `.relkit/build` directory as the context. Its Dockerfile installs the generated
    production manifest and copies the server, assets, graph, and selected worker history. Keep
    generated patches and overrides; do not copy only `server/index.js`.

3. **Start and verify the image**

    ```sh title="Terminal — application root"
    docker run --rm --name relkit-docs-preview -p 127.0.0.1:3000:3000 -e PORT=3000 relkit-local:docs
    ```

    In another terminal:

    ```sh title="Second terminal"
    curl -i http://127.0.0.1:3000/hello\?name=RELKIT
    ```

    Expect HTTP `200` and `{"message":"Hello, RELKIT!"}`. Stop this temporary container with Ctrl+C.
    It has no application data. Apps with file-backed state need an explicitly mounted persistent
    volume before accepting data; do not rely on a disposable container's writable layer.

## Add providers to a container deployment

Supply every required environment value at runtime through your host's secret/environment
mechanism. For a local smoke check, Docker supports an explicit `--env-file` containing
non-committed test values; the image itself does not load your project's dotenv files.
Do not reuse a host-loopback URL inside a container: it addresses the container itself.
Configure reachable connected resources using [production provider setup](/docs/modules/deployment/providers).

`relkit local` recipes serve development and publish loopback endpoints. The production image
does not start Docker recipes. Its external services need their own lifecycle, network, credentials,
and persistent volumes. Keep database migration tooling outside normal application startup.

## Stop development services

```sh title="Terminal — application root"
bun run relkit local stop
```

This retains project volumes. Resume with `local up --detach`. Once the image responds correctly,
continue to [AWS/Pulumi](/docs/modules/deployment/aws) or run the built server on your own host.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/docker` API](/docs/api/integrations/docker)

- [`templates/default/v1/minimal/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/minimal/relkit.config.ts)

---

# Configure production providers
Source: https://relkit.dev/docs/modules/deployment/providers

Choose runtime resources independently from the application host. An AWS-hosted app can use an
existing Redis service or Cloudflare R2; selecting those adapters does not make the deployment
stack own their lifecycle.

## Pre-setup

Begin with [local Docker configuration](/docs/modules/integrations#pre-setup) and passing module
checks. Before releasing, obtain the target resource's connection values and store secrets in
your deployment's runtime environment. Keep stable descriptor IDs and profile names when changing
their provider. Verify supported operations: a connected provider is not automatically equivalent
to the one used during development.

Application fields belong in `defineEnv`. The named `binding` references below describe provider
connections; they are not extra `context.env` fields. Keep your existing environment contract,
server settings, and application identity when merging either example.

## Buckets and caches

**S3 and Redis**

Keep Docker as the local default, with explicit connected values available for release builds.
Install the owners you select; this complete example uses both:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/docker@0.7.13 @relkit/s3@0.7.13
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

```ts title="relkit.config.ts"
/** Local Docker recipes pair with explicit connected resource values for release builds. */
import { defineApp, defineEnv, env as binding } from "@relkit/app/config";
import { docker } from "@relkit/docker";
import { redis } from "@relkit/redis";
import { s3 } from "@relkit/s3";

export default defineApp({
  env: defineEnv({}),
  bucket: {
    assets: docker(
      s3({
        endpoint: binding.url("ASSETS_S3_ENDPOINT"),
        bucketName: binding.string("ASSETS_S3_BUCKET"),
        region: binding.string("ASSETS_S3_REGION"),
        credentials: {
          accessKeyId: binding.secret("ASSETS_S3_ACCESS_KEY_ID"),
          secretAccessKey: binding.secret("ASSETS_S3_SECRET_ACCESS_KEY"),
        },
        forcePathStyle: true,
      }),
    ),
  },
  cache: { requests: docker(redis({ url: binding.secret("REQUESTS_REDIS_URL") })) },
  defaults: { bucket: "assets", cache: "requests" },
});
```

Set `ASSETS_S3_ENDPOINT`, `ASSETS_S3_BUCKET`, `ASSETS_S3_REGION`, the two S3 credential values,
and `REQUESTS_REDIS_URL` in the production process environment. The resources must already exist
and be reachable by the server. Adjust path-style access for the selected S3 service.
Docker overrides local connection values during development; it does not provision production resources.

For stack-owned resources, use [AWS wrappers](/docs/modules/deployment/aws#understand-resource-ownership)
and review their [options](/docs/api/integrations/aws). AWS can own supported S3 and Redis/Valkey
resources; a direct connected adapter never requests that lifecycle.

**Cloudflare R2 and KV**

Cloudflare has no bundled Docker recipe. Keep MinIO/Redis for ordinary local development,
then explicitly select this configuration when testing or releasing against existing R2/KV resources:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/cloudflare@0.7.14
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

```ts title="relkit.config.ts — connected Cloudflare alternative"
/** Connect existing R2 and KV resources without selecting Cloudflare application hosting. */
import { defineApp, defineEnv, env as binding } from "@relkit/app/config";
import { kv, r2 } from "@relkit/cloudflare";

export default defineApp({
  env: defineEnv({}),
  bucket: {
    assets: r2({
      accountId: binding.string("CLOUDFLARE_ACCOUNT_ID"),
      bucketName: binding.string("R2_BUCKET_NAME"),
      credentials: {
        accessKeyId: binding.secret("R2_ACCESS_KEY_ID"),
        secretAccessKey: binding.secret("R2_SECRET_ACCESS_KEY"),
      },
    }),
  },
  cache: {
    requests: kv({
      accountId: binding.string("CLOUDFLARE_ACCOUNT_ID"),
      namespaceId: binding.string("KV_NAMESPACE_ID"),
      apiToken: binding.secret("CLOUDFLARE_API_TOKEN"),
    }),
  },
  defaults: { bucket: "assets", cache: "requests" },
});
```

Supply the account ID, bucket name, namespace ID, and three credential values named in the example.
Use credentials scoped to the intended resources. R2 supports signed URLs; KV requires a TTL
of at least 60 seconds and does not support atomic increment. Do not reuse a Redis counter/rate-limit
cache without checking those limits. See [R2 and KV reference](/docs/api/integrations/cloudflare).

This connects REST/S3-compatible runtime APIs from the Bun server. It does not deploy the application
to Cloudflare Workers or create the bucket/namespace.

## Realtime and agent checkpoints

Use the [Redis realtime configuration](/docs/modules/realtime/providers) with a reachable secret
connection binding in production, and configure `agent-state` separately for agents. Confirm Redis
persistence and shared fanout across replicas; local filesystem profiles require one shared,
appropriately managed state location and are not a replacement for distributed provider semantics.

## Durable job providers

| Provider    | Local default        | Deployment guidance                                                                                                               |
| ----------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Inngest     | `docker(inngest())`  | [Inngest setup](/docs/modules/jobs/providers/inngest): connected credentials, native worker registration, and capability evidence |
| Trigger.dev | `docker(trigger())`  | [Trigger.dev setup](/docs/modules/jobs/providers/trigger): target runtime, immutable worker publication, and provider connection  |
| Effect MQ   | `docker(effectMq())` | [Effect MQ setup](/docs/modules/jobs/providers/effect-mq): PostgreSQL-backed native execution and worker lifecycle                |

Follow [job deployment](/docs/modules/jobs/deployment) to publish workers, verify readiness, and
activate schedules. Keep previous worker generations while they own accepted runs. Application
events use the [filesystem provider](/docs/modules/events#pre-setup); persist their state explicitly.

## Database and authentication

The [database service](/docs/modules/database/define) connects PostgreSQL, MySQL, or SQLite.
RELKIT does not provision an application database through `defineApp`. Supply its connection via
`defineEnv`, migrate once before rollout, and keep backups and connection/network policy with the
database owner. The Docker PostgreSQL walkthrough is development setup, not a managed cloud database.

[Better Auth](/docs/modules/auth#pre-setup) shares that service. Use the public production origin
for `BETTER_AUTH_URL`, a stable secret across replicas, and reviewed cookie/origin policy. Keep
credentials and session tables out of generated public CRUD endpoints.

## Models and telemetry

Selected [model SDKs](/docs/modules/ai/agents#choose-a-model) own model credentials and availability.
Sentry and OTLP are independent [telemetry exporters](/docs/modules/operations/observability),
configured with named endpoint/secret bindings. AWS hosting supplies CloudWatch stdout routing;
it does not create a model account, Sentry project, or OTLP service.

## Verify the release configuration

Run `bun run check`, `bun run typecheck`, and `bun run build` after changing bindings. These
validate the application and selected contracts; they do not prove remote credentials or network
access. Verify a real read/write and applicable rejection path against your intended provider in
an isolated environment before accepting traffic. Follow [AWS deployment](/docs/modules/deployment/aws)
only when that host is selected.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/s3` API](/docs/api/integrations/s3)
- [`@relkit/redis` API](/docs/api/integrations/redis)
- [`@relkit/cloudflare` API](/docs/api/integrations/cloudflare)
- [`@relkit/jobs` API](/docs/api/jobs)

- [`apps/docs/examples/setup/connected.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/connected.ts)
- [`apps/docs/examples/setup/cloudflare.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/setup/cloudflare.ts)

---

# Events overview
Source: https://relkit.dev/docs/modules/events

An event records that something happened in your application, such as an order being created. Other functions can subscribe and react—for example, sending a confirmation and recording analytics after an order is created.

The original operation does not wait for these reactions to finish. Use events for follow-up work; use a normal function call when you need the result before continuing.

> **Start here**
>
> Start with [React to order events](/guides/events/react-to-order-events) to install the runtime,
> publish an event, and verify its subscriber. Use [Define an event](/docs/modules/events/define)
> for configuration and the [Events reference](/docs/api/events) for exact contracts.

An event consumer may submit a [task-first job](/docs/modules/jobs/quickstart) when the follow-up needs durable
execution. Publishing an event is not an atomic database write plus task admission.

## Pre-setup

Application events currently use the filesystem provider. It has no Docker recipe; Redis's
cache/realtime adapters do not provide application events. Other configured capabilities
can still use local Docker in this same application.

1. **Install the event provider**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/local@0.7.14
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure event delivery**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Application events use the supported filesystem provider, which has no Docker recipe. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { localEvent } from "@relkit/local";

    export default defineApp({
      env: defineEnv({}),
      event: localEvent(),
      defaults: { event: "default" },
    });
    ```

    This path requires no credentials or new `defineEnv` fields. The `default` profile stores
    state under `.relkit/state`; preserve that directory across restarts. A scaffold may already
    have added this binding—reuse it instead of creating a second profile.

3. **Validate the event and consumer**

    After registering the event and listener, run `bun run check`, `bun run typecheck`, and
    `bun run dev`. Follow [Handle order events](/guides/events/react-to-order-events) to publish
    an event and verify its consumer. Defining an event alone does not run a listener.

## The Events API

| API                                                           | What you use it for                                                                                             |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`defineEvent`](/docs/api/events#defineevent)                 | Name the event and define the data it carries.                                                                  |
| [`defineFunction`](/docs/api/functions#definefunction)        | Perform an operation, then publish with `context.events[eventId].publish(data)`. List the event in `publishes`. |
| [`defineEventFunction`](/docs/api/events#defineeventfunction) | Subscribe with `event: "orders.created"` and run your handler when it is published.                             |

## See your subscribers

After [installing and binding the event runtime](/guides/events/react-to-order-events#install-and-bind-the-selected-event-runtime),
start the app. If you choose inspection, complete the separate [Inspector setup](/docs/modules/operations/inspector)
and open its UI at `http://localhost:3210`. Select **Events & listeners**, then open an event.
**Publishers** shows which functions send it; **Consumer functions** shows its subscribers.

<img
  src="/inspector-event-subscribers.jpg"
  alt="Inspector showing orders.created, its publisher, and its subscribing functions"
/>

Follow the [order confirmation example](/guides/events/react-to-order-events) to publish and consume an event
in your existing app. Use [Define an event](/docs/modules/events/define) for the descriptor details.

---

# Consume an event
Source: https://relkit.dev/docs/modules/events/consume

An event function reacts to a published event without returning a result to the publisher.

> **Before you begin**
>
> Start with an [existing application](/docs/learn/create-an-app) and the event you want to handle.

## Scaffold an event-only function

First complete [event runtime installation and binding](/guides/events/react-to-order-events#install-and-bind-the-selected-event-runtime).
The scaffold reuses or selects a profile; a manually copied subscriber does not install a provider.

After [defining the `orders.created` event](/docs/modules/events/define#define-the-event), run from
the application root:

```sh
bun run relkit add event-function on-order-created --service orders \
  --event orders.created --delivery durable
```

Creates `src/services/orders/functions/on-order-created.function.ts`. `--event` selects an existing
event by ID, binding, or filename. The default delivery is `durable`; choose `transient` for
non-durable delivery. `--profile` selects a compatible event provider profile. In a terminal,
omitted choices are prompted; headless execution needs an unambiguous event target.

The function is event-only, not a public callable service member. Review the placeholder handler
against your event payload before implementing its reaction; the CLI does not generate business logic.

If you scaffolded the event with `add event order-created`, use its generated ID
`orders.order-created-event` for `--event` instead. Keep the subscriber's selected event ID
when adapting the handler below. For manual setup, create the subscriber directly.

For every subscriber scaffolding flag, see the [event-function command reference](/docs/api/cli#relkit-add-event-function-name).

## Create a subscriber

Use `defineEventFunction` to run work when an event is published. After [defining `orders.created`](/docs/modules/events/define), create `src/services/orders/functions/order-confirmation.function.ts`:

```ts title="src/services/orders/functions/order-confirmation.function.ts"
import { defineEventFunction } from "@relkit/app/events";

const orderConfirmation = defineEventFunction({
  id: "orders.confirmation",
  event: "orders.created",
  handler: async (order, context) => {
    context.log.info("order.confirmation.requested", { orderId: order.orderId });
  },
});

export default orderConfirmation;
```

- `id` uniquely names this function.
- `event` is the exact ID of the event to consume.
- `handler` receives the event data. This example logs a confirmation; replace the log with your own work, such as sending an email.

Run `bun run check` from your app's root. RELKIT runs the handler when `orders.created` is published; you do not call it yourself.

Use `defineFunction` when the caller needs a result, such as the created order. Use `defineEventFunction` for a reaction that runs separately, without returning a result to the publisher.

When the reaction must survive the consumer process or expose run progress, trigger a task-first job from
the event function. Event delivery and task admission remain separate operations; use an explicit stable
idempotency key where repeated event delivery could duplicate business work.

## Add another subscriber

To run multiple reactions, add another event function with a different `id` and the same `event`.

---

# Define an event
Source: https://relkit.dev/docs/modules/events/define

Define an event to give an application fact a stable name and a validated payload.

> **Before you begin**
>
> Start with an [existing application](/docs/learn/create-an-app). Event definitions use the app
> package already installed by the starter.

## Pre-setup

Complete [event provider setup](/docs/modules/events#pre-setup) to install `@relkit/local`
and configure `event` plus `defaults.event` in `defineApp`. No additional `defineEnv` values
are required. This provider has no Docker recipe; retain its `.relkit/state` data across restarts.

## Scaffold an event contract

From an application's root, with an existing `orders` service:

```sh
bun run relkit add event order-created --service orders
```

Creates `src/services/orders/events/order-created.event.ts`, a version-1 contract with a string `value`
payload and ID `orders.order-created-event`. It registers the event's type and exposes the event
through the service. Pass `--internal` to omit service exposure.

Use `--profile events` to select that compatible event profile. Without one, scaffolding reuses
a configured default or unique profile, or adds a file-backed `localEvent()` profile. The sample
payload is a starting point; it is different from the hand-authored example below. Declare publication
on a function and add a consumer when needed.

For every event scaffolding flag, see the [event command reference](/docs/api/cli#relkit-add-event-name).

The scaffold normally installs/configures its selected runtime. With `--no-install`, finish
`bun install` and `bun run check`. For manual source setup, complete the
[local event installation and binding](/guides/events/react-to-order-events#install-and-bind-the-selected-event-runtime)
before using the descriptor below; its declaration alone does not select a provider.

## Define the event

Use `defineEvent` to name an event and describe its data. In your app, create `src/services/orders/events/order-created.event.ts`:

```ts title="src/services/orders/events/order-created.event.ts"
import { defineEvent } from "@relkit/app/events";
import { z } from "@relkit/app/schema";

const orderCreated = defineEvent({
  id: "orders.created",
  version: 1,
  input: z.object({
    orderId: z.string().min(1),
    sku: z.string().min(1),
    totalCents: z.number().int().nonnegative(),
  }),
});

export default orderCreated;
```

- `id` uniquely names the event. Use this same name when publishing and consuming it.
- `input` describes the data to send with the event.
- `version` is optional and defaults to `1`.

Here, each order event carries an order ID, product code, and total.

## Check your event

After adding the file, run this from your app's root:

```sh
bun run check
```

---

# Publish an event
Source: https://relkit.dev/docs/modules/events/publish

Publish an event from the function that performs the operation, so other functions can react to its result.

## Publish from a function

> **Before you begin**
>
> Complete the [event runtime installation and
> binding](/guides/events/react-to-order-events#install-and-bind-the-selected-event-runtime) before
> publishing. Acceptance requires the selected profile; a function's `publishes` list grants a
> checked capability but does not install its runtime package.

First, [define `orders.created`](/docs/modules/events/define). Then publish it from the `defineFunction` that creates the order:

```ts title="src/services/orders/functions/create-order.function.ts"
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const createOrder = defineFunction({
  input: z.object({
    orderId: z.string().min(1),
    sku: z.string().min(1),
    quantity: z.number().int().positive(),
  }),
  output: z.object({
    orderId: z.string(),
    sku: z.string(),
    totalCents: z.number().int().nonnegative(),
  }),
  publishes: ["orders.created"],
  handler: async (input, context) => {
    const order = { orderId: input.orderId, sku: input.sku, totalCents: input.quantity * 100 };
    await context.events["orders.created"].publish(order);
    return order;
  },
});

export default createOrder;
```

This function uses the [Orders example's](/guides/events/react-to-order-events) `priceOrder` helper. To publish the event:

1. Add `publishes: ["orders.created"]` to allow this function to publish the event.
2. Call `await context.events["orders.created"].publish(order)` to send the order data.

Use the exact event ID in both places. The data must match the event's `input` schema. Only events listed in `publishes` are available through `context.events`.

Publishing waits for the event to be accepted, not for its consumers to finish. Your function can return the order while confirmation runs separately.

## Publish from an event function

A `defineEventFunction` can publish events the same way: list each ID in `publishes`, then call `.publish()`.

---

# HTTP routes overview
Source: https://relkit.dev/docs/modules/http

An HTTP route connects a method and URL to an operation exposed by a service. A domain owns the business behavior;
its [service](/docs/modules/service) exposes public functions; a route connects a URL and method to one of those
functions. Adding a public function alone does not publish an endpoint.

> **Start here**
>
> Start with [Your first HTTP route](/docs/modules/http/first-route) to expose and call a service
> operation. Use the [Routes reference](/docs/api/routes) for exact descriptor options and types.

Keep these responsibilities separate so the same operation can serve an HTTP request, a scheduled job,
or an AI tool without copying its validation and business rules into each entry point.

## Pre-setup

Start from the [minimal app](/docs/learn/create-an-app). Core HTTP needs no optional integration
or external service. Merge listener settings in `relkit.config.ts` when changing the defaults:

```ts title="relkit.config.ts"
/** HTTP needs listener settings but no external provider or custom PORT field. */
import { defineApp, defineEnv } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({}),
  server: { port: 3000, maxBodyBytes: 1_048_576 },
});
```

Keep your app's existing ID, `env` contract, and other settings. `PORT` is a framework-owned
runtime override; do not add it to `defineEnv`. Put application-specific values in
[`src/platform/env.ts`](/docs/learn/concepts/environment) and keep that descriptor in `defineApp({ env })`.

Configure a route's dependencies before serving it: [database](/docs/modules/database#pre-setup),
[uploads](/docs/modules/storage#pre-setup), [cache/rate-limit storage](/docs/modules/caching#pre-setup),
and [authentication](/docs/modules/auth#pre-setup). These use local Docker where a service is needed.
Then run `bun run check`, `bun run typecheck`, and `bun run dev`; the first route guide verifies
the actual HTTP response. [Scalar](/docs/modules/http/openapi) and
[MCP](/docs/modules/ai/mcp) require their own opt-in setup.

## Follow a request through the application

For a function-backed route, the normal request flow is:

```text
HTTP request
  ↓ URL + method
Route (src/routes/)
  ↓ policy + input mapping
Public function (src/services/<domain>/)
  ↓ validated output
HTTP response
```

The route does not contain another business handler. It selects a public function and describes how
HTTP values become that function's input. RELKIT checks the descriptors, generates transport artifacts,
and registers the checked routes with the runtime.

Core HTTP, RPC and JSON OpenAPI are available in the minimal app without optional protocol/UI SDKs.
[MCP](/docs/modules/ai/mcp), [AG-UI](/docs/modules/ai#observe-durable-execution) and
[Scalar](/docs/modules/http/openapi) each have an independent installation and explicit selection.

The [Orders extension](/docs/learn/first-route) to the minimal app uses the same layers:

```ts title="src/routes/orders/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineServiceRoutes } from "@relkit/app/routes";
import orders from "@app/services/orders/service.js";

export const { POST } = defineServiceRoutes(orders, {
  POST: { member: "createOrder", successStatus: 201 },
});
```

The directory supplies `/orders`, the named export supplies `POST`, and the service member selects
the public `createOrder` function. Its object input comes from JSON; its validated output becomes a
JSON `201` response. Follow [your first HTTP route](/docs/modules/http/first-route) to trace and verify it.

## Know where each change belongs

| You want to change…                             | Edit…                                                         | Continue with…                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Business behavior, schemas, or declared errors  | `src/services/<domain>/functions/` and domain-local contracts | [Functions](/docs/learn/concepts/functions)                                                       |
| Which functions other code may call             | `src/services/<domain>/service.ts`                            | [Define a service](/docs/modules/service/define)                                                  |
| Which function a method invokes                 | `src/routes/**/route.ts`                                      | [Define a route](/docs/modules/http/define)                                                       |
| A URL or path parameter                         | Directories underneath `src/routes/`                          | [File-system routes](/docs/modules/http/routes)                                                   |
| Headers, cookies, query fields, or body mapping | The route's `request` descriptor                              | [Requests](/docs/modules/http/requests)                                                           |
| Multipart parsing and upload limits             | The route plus the domain's file schema                       | [Uploads](/docs/modules/http/uploads)                                                             |
| HTTP authentication, CORS, or response headers  | `src/routes/middleware/`                                      | [Middleware](/docs/modules/http/middleware)                                                       |
| Request frequency limits                        | The function-backed route's `rateLimit`                       | [Rate limits](/docs/modules/http/rate-limits)                                                     |
| Success status or error-to-HTTP mapping         | The route and declared domain errors                          | [Responses](/docs/modules/http/responses)                                                         |
| A native HTTP adapter                           | An `ALL` raw route                                            | [Raw handlers](/docs/modules/http/raw-handlers)                                                   |
| Public API documentation or a typed caller      | Checked artifacts, generated from source                      | [OpenAPI](/docs/modules/http/openapi) · [Generated clients](/docs/modules/http/generated-clients) |

Business rules that must apply to every caller belong in the function, not only in HTTP middleware.
For agents, tools, jobs, events, caching, and storage, use the [domain organization guide](/docs/modules/service/organization)
to choose an owner and continue into that capability's getting-started guide.

## Choose a starting point

New to the application layout? Start with [Service](/docs/modules/service).

Ready to ship an endpoint? Follow [your first HTTP route](/docs/modules/http/first-route).

Already have a public function? Go directly to [defining a route](/docs/modules/http/define).

Returning incremental results? Choose [managed or native
streaming](/docs/modules/http/streaming).

Need the exact descriptor types and helpers? Open the [Routes API reference](/docs/api/routes).

These guides describe function-backed HTTP endpoints first. Raw handlers opt out of that typed pipeline;
generated clients use a separate RPC transport. Their dedicated guides explain those boundaries.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/services` API](/docs/api/services)

- [`templates/default/v1/api/src/routes/echo/route.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/routes/echo/route.ts)

---

# Define a route
Source: https://relkit.dev/docs/modules/http/define

Define a route to connect an HTTP method and path to a public service operation. Import the target through its domain's
`service.ts`; never reach into another domain's private function directory from a route.
The [file-system conventions](/docs/modules/http/routes) determine the URL and allowed method exports.

## Scaffold a route

Run these commands from an installed application's root. Choose the mode that matches the
endpoint you are creating; then edit the generated file using the API examples below.

**Service function**

To route through existing public functions, use service-route mode. With `details` and
`updateDetails` public callable members in the `users` service:

```sh
bun run relkit add route /users/:id/details \
  --mode service-route --service users \
  --map GET=details --map PATCH=updateDetails
```

This creates `src/routes/users/[id]/details/route.ts` with `defineServiceRoutes`. The
mapped names are public service member names, not private filenames or event IDs. Headless
service-route commands need at least one `--map`; supported methods are `GET`, `POST`,
`PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`. `ALL` is auth-only.

**Raw handler**

From an installed application's root, create a standalone raw handler:

```sh
bun run relkit add route /status --mode route
```

This creates `src/routes/status/route.ts` with a raw `GET` returning `{ ok: true }`.
It needs no service or function. It appears in OpenAPI/Scalar with a generic response contract,
not an inferred function response schema. `--map` is not accepted in this mode.

For a complete function-backed endpoint, follow [Add an Orders endpoint](/docs/learn/first-route).
The CLI creates the method mapping; add request mapping, response status, and policy in source.

| URL passed to the command | Generated file                           |
| ------------------------- | ---------------------------------------- |
| `/`                       | `src/routes/route.ts`                    |
| `/users/:id/details`      | `src/routes/users/[id]/details/route.ts` |
| `/files/*parts`           | `src/routes/files/[...parts]/route.ts`   |
| `/files/*parts?`          | `src/routes/files/[[...parts]]/route.ts` |

Write route paths without quotes. Escape literal shell wildcards, for example `/files/\*parts`
or `/files/\*parts\?`, so the shell passes them to the CLI unchanged. Existing target files are never
overwritten; edit an existing route to add another method. Run `bun run check`, then verify
the endpoint and its entry in `/_relkit/v1/openapi.json` while dev is running. The
[Scalar UI](/docs/modules/http/openapi) is available when explicitly selected.

For every route scaffolding flag, see the [route command reference](/docs/api/cli#relkit-add-route-path).

## Expose one public function

Use `defineRoute` for one method-to-function mapping:

```ts title="src/routes/echo/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineRoute } from "@relkit/app/routes";
import echo from "@app/services/echo/service.js";

export const POST = defineRoute({
  target: echo.echo,
});
```

This is `POST /echo`. Omit `request` and `responses` when the input schema and output describe ordinary
JSON correctly. The descriptor selects behavior; it does not call `echo.echo.invoke()` at module load.

A target must be an ordinary callable function exposed by a service. An event contract, event-only
subscriber, tool, or agent is not a route target. To expose agent behavior, use a public
[function that calls the agent](/docs/modules/service/organization#tools-and-agents-stay-with-their-business-domain).

### Use from the frontend

After [frontend installation, contract pull, and provider setup](/guides/frontend/connect-react),
call this `POST /echo` operation with its domain input. The route produces both the React selector
`POST /echo` and the TypeScript operation `route.post.echo`.

**React**

Render this component under `RelkitClientProvider`. Clicking the button sends `{ message }` and
displays the inferred `{ message: string }` result:

```tsx title="src/EchoButton.tsx"
"use client";

/** Calls the documented POST /echo function route after an explicit user action. */
import { useRelkitClient, useRouteMutation } from "@relkit/client/react";

/** Sends domain input and renders the validated output; the hook owns mutation state.
 * @returns An Echo button with pending, failure, and success feedback. */
export function EchoButton() {
  const { status } = useRelkitClient();
  const echo = useRouteMutation("POST /echo");

  return (
    <section>
      <button
        disabled={status !== "ready" || echo.isPending}
        onClick={() => echo.mutate({ message: "Hello from the frontend" })}
      >
        Send message
      </button>
      {echo.isPending && <p role="status">Sending…</p>}
      {echo.isError && <p role="alert">{String(echo.error)}</p>}
      {echo.isSuccess && <p>{echo.data.message}</p>}
    </section>
  );
}
```

**TypeScript**

Without React, load the browser identity before the mutation and call the generated operation:

```ts title="src/echo-client.ts"
/** Calls the Echo contract from a TypeScript browser frontend without React or backend source imports. */
import { createClient } from "@relkit/client";

/** Sends one message over RPC using types from the caller's pulled contract.
 * @param baseUrl - Public backend origin, or the frontend origin when proxying RPC.
 * @param message - Nonempty message accepted by the Echo function.
 * @returns The validated message output; transport and application failures reject. */
export async function echoMessage(baseUrl: string, message: string) {
  const response = await fetch(new URL("/_relkit/v1/client/identity", baseUrl), {
    credentials: "include",
    cache: "no-store",
  });
  if (!response.ok) throw new Error(`Identity request failed (${response.status})`);
  const identity = await response.json();
  if (
    !identity ||
    typeof identity.identityScope !== "string" ||
    typeof identity.sessionEpoch !== "string"
  ) {
    throw new Error("The backend returned an invalid client identity");
  }
  const client = createClient({
    baseUrl,
    headers: {
      "x-relkit-identity-scope": identity.identityScope,
      "x-relkit-session-epoch": identity.sessionEpoch,
    },
  });
  return client["route.post.echo"]({ message });
}
```

The React provider performs this identity step for hooks.

These calls use RPC over `/rpc`, with the same authorization and policy. Pass domain input rather
than assembling the route's REST mapping. Raw handlers and routes with `client: false` do not
generate these operations. Never import the backend descriptor into the browser.

Reference: [`useRouteMutation`](/docs/api/client#useroutemutation),
[`createClient`](/docs/api/client#createclient). Continue with [mutations](/docs/modules/client/mutations).

## Group methods that use one service

Use `defineServiceRoutes` to select public function members by name:

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

`GET: "searchOrders"` uses inference. The `POST` object selects `createOrder` and adds HTTP-specific
mapping and a `201` success status. Both forms produce the same kind of checked function route.

### Use both methods from the frontend

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";

/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
 * @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
  const { status } = useRelkitClient();
  const orders = useRoute("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      {orders.isPending && <p role="status">Loading orders…</p>}
      {orders.data && <p>{orders.data.count} orders</p>}
      {orders.isError && <p role="alert">{orders.error.message}</p>}
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

Keep the exported destructuring form. Supported keys are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`,
`HEAD`, and `OPTIONS`; do not rename the bindings, add a rest binding, or use a default export.
`ALL` is reserved for [raw handlers](/docs/modules/http/raw-handlers), not `defineServiceRoutes`.

Several route files can use the same service. Individual `defineRoute` exports in one file can target
different public services. Put reusable cross-domain orchestration in a domain function instead of
creating business logic inside the route module.

## Add only the transport options you need

| Option                               | Use it when…                                                                                                                                       |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request`                            | Inference cannot express headers, cookies, names, or nesting. It replaces all inferred input mapping. See [requests](/docs/modules/http/requests). |
| `accept`                             | The route consumes `multipart/form-data` instead of JSON. See [uploads](/docs/modules/http/uploads).                                               |
| `successStatus`                      | One successful JSON operation needs a different `2xx` status, such as `201`.                                                                       |
| `responses`                          | You need a complete explicit response contract. It replaces inference; see [responses](/docs/modules/http/responses).                              |
| `maxBodyBytes`                       | Parsing this route needs a specific positive byte ceiling.                                                                                         |
| `timeoutMs`                          | The function invocation needs a route-specific positive timeout.                                                                                   |
| `rateLimit`                          | Requests need a keyed limit before mapping and invocation. See [rate limits](/docs/modules/http/rate-limits).                                      |
| `id`, `title`, `description`, `tags` | You need stable operation identity or human-facing metadata.                                                                                       |

Do not add `path` or `method`: the compiler derives both from source. There is no service-level URL
prefix or middleware property. The `auth` option is specific to a recognized Better Auth raw handler,
not a generic authorization flag for a function route.

## Check the new operation

From the application root:

```sh
bun run check
bun run typecheck
```

Resolve diagnostics before starting the server. Check the generated route method, path, target,
input mapping, and responses. Then test the endpoint itself: a direct function test does not exercise
HTTP parsing or policy. The [first-route walkthrough](/docs/modules/http/first-route) includes both the source
and an in-process HTTP test.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/services` API](/docs/api/services)

- [`examples/commerce/src/routes/orders/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/route.ts)

---

# Your first HTTP route
Source: https://relkit.dev/docs/modules/http/first-route

Follow a `POST /orders` request from its JSON body to the validated function result. That chapter creates this route from maintained API-candidate sources. Follow one `POST /orders` request from JSON to a validated
function result and verify both accepted and rejected input. Run commands from the app root.

1. ## Select the public operation

    The Orders domain calculates a price in `createOrder`. Its service exposes that operation to
    the route. Read the **existing** `src/services/orders/service.ts`:

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import createOrder from "@app/services/orders/functions/create-order.function.js";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    export default defineService({
      functions: { createOrder, priceOrder },
    });
    ```

    The service is the public boundary. A route imports the service, not a private function file.
    If you have the Orders functions but no route yet, scaffold it from the application root:

    ```sh title="Terminal — application root"
    bun run relkit add route /orders \
      --mode service-route --service orders --map POST=createOrder
    ```

    Skip this command when continuing from the [Orders endpoint chapter](/docs/learn/first-route),
    which already created that file. The scaffold maps `POST` to the function and defaults to HTTP
    `200`; edit it to match the `201` response below. The route's folder supplies `/orders`:

    ```ts title="src/routes/orders/route.ts"
    /** Maps the HTTP endpoint to its owning service's public member. */
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { POST } = defineServiceRoutes(orders, {
      POST: { member: "createOrder", successStatus: 201 },
    });
    ```

    `member: "createOrder"` selects the public operation. `successStatus: 201` changes only the
    successful response status; RELKIT infers the JSON input and output contracts from the function.
    The [endpoint chapter](/docs/learn/first-route) changes the price rule without editing this route.

2. ## Send a request and inspect the result

    Start the app with `bun run dev`. In another terminal, send a valid request:

    ```sh title="Terminal — relkit-orders"
    curl -i -X POST http://localhost:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"route-1","sku":"book","quantity":3}'
    ```

    Expect HTTP `201` and `totalCents: 300`. The starter's HTTP test checks the same status and
    body in process. Create `tests/integration/orders.route.test.ts` from this source:

    ```ts title="tests/integration/orders.route.test.ts"
    import { afterAll, expect, test } from "bun:test";
    import { createTestApplication } from "@relkit/testing";
    import config from "../../relkit.config.js";

    const testApp = await createTestApplication(config, { resourceProviders: "fake" });

    test("POST /orders", async () => {
      const response = await testApp.http.request("/orders", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ orderId: "order-1", sku: "book", quantity: 3 }),
      });
      expect(response.status).toBe(201);
      expect(await response.json()).toEqual({
        orderId: "order-1",
        sku: "book",
        totalCents: 300,
      });
    });

    afterAll(() => testApp.close());
    ```

    Run `bun test tests/integration/orders.route.test.ts`. Then send `quantity: 0`; the running
    server returns HTTP `422` before the handler creates an order. The test harness also maps
    function-input validation to `422`, but it does not reproduce every middleware or transport
    behavior. Check security policy and alternate transports against the running server.

3. ## Inspect the generated contract

    Run `bun run check` and `bun run typecheck`, then open `/_relkit/v1/openapi.json` on the
    running backend. Find `POST /orders`, its request fields, success response, and validation
    response. Edit source to change the contract; do not edit `.relkit/generated` output.
    Select the [optional Scalar UI](/docs/modules/http/openapi) when you want an interactive reference.

    For path parameters, headers, and cookies, continue with [Request mapping](/docs/modules/http/requests).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/services` API](/docs/api/services)
- [`@relkit/testing` API](/docs/api/testing)

- [`templates/default/v1/api/tests/integration/echo.route.test.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/tests/integration/echo.route.test.ts)

---

# Generated clients
Source: https://relkit.dev/docs/modules/http/generated-clients

Generate a typed client so callers can use your routes without maintaining their own request and response types. Operation names come from route
IDs; input, output, and declared application errors come from the target functions.
Raw handlers do not become generated-client operations.

The client uses **RPC over `/rpc`**. Every exposed route has its stable route-ID procedure and a
deterministic method/path alias. Both execute the original route's authorization, middleware, rate
limit, timeout, error mapping, and telemetry against its canonical method and path. Use the
[OpenAPI document](/docs/modules/http/openapi) when you need the native REST request and response shape.

1. ## Install the caller

    The backend's minimal starter already supplies check/generation tooling. In a separate caller package,
    install the framework-independent client and its required peer before importing the generated client:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @opentelemetry/api@1.9.1 @relkit/client@0.8.4
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    Only a selected React/query leaf needs its additional peers; follow [React setup](/docs/modules/client)
    for that path. A standalone frontend also needs the development CLI for `client pull`/`client check`,
    as shown there. Keep frontend installation and contract output in the frontend root.

2. ## Generate the contract

    From your application's root:

    ```sh
    bun run check
    ```

    This writes `.relkit/generated/contract.ts` and `.relkit/generated/client.ts`, alongside graph,
    OpenAPI, and JSON client-contract artifacts. Never hand-edit them.

    Make the generated contract part of the caller's TypeScript program: import the generated client
    entry point, or explicitly include the generated contract when using `@relkit/client` directly.
    The contract augments the default client registry so operation names and inputs are typed. Merely
    installing `@relkit/client` in another app does not teach it your server's operations.

    Package or share the generated client and contract together with the dependencies they import.
    Regenerate and review them when route identities, input, output, or errors change.

    The same generated contract includes public task-first jobs under `jobs.<name>`. A job trigger returns an
    accepted `runId`; inspect, watch, and control it through the generated `runs` procedures rather than treating
    the trigger response as the task output. Keep the original operation ID and request when an acceptance response
    is unknown.

3. ## Configure the transport

    This repository example configures a client instance:

    ```ts title="examples/commerce/src/platform/generated-client.ts"
    import { createClient } from "@relkit/client";

    export const liveHeaders = new Headers();
    export const client = createClient({ baseUrl: "http://localhost:3000", headers: liveHeaders });
    ```

    Set `baseUrl` to the backend origin, without appending `/rpc`; the client adds that transport path.
    The snippet uses port `3000`, the generated-app default. Change it to `4000` when calling the commerce
    app with its default configuration.

    `headers` accepts a header collection or a provider, including an asynchronous provider.
    Use request-scoped headers or a provider for credentials; do not mutate one shared instance with
    different users' credentials in a server process. The example's mutable `liveHeaders` is not a
    multi-user session store. Browser credentials default to `include`; cross-origin cookies still
    require appropriate browser, cookie, and server CORS configuration. A custom `fetch` is supported.

4. ## Call with domain input

    Select the checked route ID with editor completion. For the unmodified Echo tutorial, the operation
    is `route.post.echo` and the input is `{ message: "hello" }`. It resolves to the function's validated
    output, not a native `Response`.

    In a separate frontend using `client pull`, select the route ID directly:

    ```ts title="src/api.ts"
    /** Calls the Echo contract from a TypeScript browser frontend without React or backend source imports. */
    import { createClient } from "@relkit/client";

    /** Sends one message over RPC using types from the caller's pulled contract.
     * @param baseUrl - Public backend origin, or the frontend origin when proxying RPC.
     * @param message - Nonempty message accepted by the Echo function.
     * @returns The validated message output; transport and application failures reject. */
    export async function echoMessage(baseUrl: string, message: string) {
      const response = await fetch(new URL("/_relkit/v1/client/identity", baseUrl), {
        credentials: "include",
        cache: "no-store",
      });
      if (!response.ok) throw new Error(`Identity request failed (${response.status})`);
      const identity = await response.json();
      if (
        !identity ||
        typeof identity.identityScope !== "string" ||
        typeof identity.sessionEpoch !== "string"
      ) {
        throw new Error("The backend returned an invalid client identity");
      }
      const client = createClient({
        baseUrl,
        headers: {
          "x-relkit-identity-scope": identity.identityScope,
          "x-relkit-session-epoch": identity.sessionEpoch,
        },
      });
      return client["route.post.echo"]({ message });
    }
    ```

    The base client does not load identity automatically. This browser example performs the identity
    handshake first and includes its scope and session epoch on the mutation, as the React provider does.

    See [the route declaration and React button](/docs/modules/http/define#use-from-the-frontend)
    side by side, or follow [Call your API from React](/guides/frontend/connect-react) to connect
    a separate frontend. [Client transports](/docs/modules/client/transports) covers HTTP,
    WebSocket, and automatic transport selection.

    | Original REST route                                     | Generated RPC call                                        |
    | ------------------------------------------------------- | --------------------------------------------------------- |
    | Maps path, query, headers, cookies, and body into input | Accepts the target function's input directly              |
    | Uses the route's `request` mappings and transforms      | Does not replay those mappings or transforms              |
    | Returns the selected HTTP success status and body       | Resolves to typed function output                         |
    | Returns an HTTP error envelope                          | Rejects with an RPC error                                 |
    | Handles multipart according to the route                | Does not automatically reconstruct that multipart request |

    For example, the Orders REST route obtains `orderId` from `idempotency-key`; an RPC caller supplies
    the function's `orderId` input property. Sending that header alone does not fill the RPC input.
    Likewise, catch-all input is an array supplied to the function, not a REST path the client constructs.

## Handle failures by contract

RPC failures use `ORPCError`. Declared application errors retain their stable error code and data;
unexpected failures use transport-level codes. Branch on the code and validated data, not a formatted
message. Do not expect a REST validation `422` body to be the RPC error shape.

A response returned by HTTP middleware is not automatically a declared function error. The RPC
middleware bridge maps a returned `401` to `UNAUTHORIZED`, a `429` to `TOO_MANY_REQUESTS`, and other
returned responses to `INTERNAL_SERVER_ERROR`. Test these cases if middleware protects the operation.

## Test security at both entry points

Registered Better Auth protection and route policy run with the operation's canonical method/path.
If a policy cannot be reproduced safely over RPC, compilation fails until the route is marked
`client: false`; that opt-out registers neither RPC identity, and direct calls return `NOT_FOUND`.

Point the client at a running local test server. The current `createTestApplication` HTTP helper does
not serve `/rpc`, so connecting it through a custom `fetch` is not an RPC integration test.
Cover success, invalid input, a declared error, missing credentials, and any quota policy.
Keep REST tests too; RPC tests do not exercise request mapping. See [Testing](/docs/modules/operations/testing)
for the other available test layers.

## Review compatibility changes

Changing an inferred route ID renames the client operation. A required input field, a removed error
code, or a narrowed output can break consumers even if the server compiles. Compare generated
artifacts in review and version shared contracts with their callers.

For a complete first endpoint and HTTP integration test, return to
[Your first HTTP route](/docs/modules/http/first-route).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/platform/generated-client.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/platform/generated-client.ts)

---

# HTTP middleware
Source: https://relkit.dev/docs/modules/http/middleware

Use HTTP middleware for policy that needs the request or response, such as CORS, cookies, or early rejection. Put it under `src/routes/middleware/`.
Keep business authorization that must apply to jobs, tools, and direct calls in domain functions as well.
There is no service-middleware layer or `middleware` option on `defineService`.

## Scaffold middleware

From your application's root:

```sh
bun run relkit add middleware order-policy --path /orders/\*
```

Creates `src/routes/middleware/order-policy.middleware.ts` with a pass-through `next()` call.
It does not implement authentication or authorization. `--path` is required headlessly; the
interactive prompt suggests `*`. Use a URL scope such as `/orders/:orderId` or a trailing
wildcard, not bracket-directory syntax. No service selection is needed.

For every middleware scaffolding flag, see the [middleware command reference](/docs/api/cli#relkit-add-middleware-name).

## Define path-scoped policy

```ts title="examples/commerce/src/routes/middleware/order-auth.middleware.ts"
/** Checks the demonstration order authorization function before forwarding matching HTTP requests; denial returns 401. */
import { defineMiddleware } from "@relkit/app/routes";
import orders from "../../services/orders/service.js";

const orderAuth = defineMiddleware("/orders/*", async (context, next) => {
  const result = await orders.authorizeOrder.invoke({
    authorization: context.req.header("authorization") ?? "",
  });
  if (!result.allowed) return context.json({ error: "unauthorized" }, 401);
  await next();
});

export default orderAuth;
```

The middleware reads a header, delegates the decision to a public function, and returns `401` when
denied. It calls `next()` only when processing should continue.

> **This example is not token verification**
>
> The commerce authorization function only checks for a `Bearer ` prefix. It demonstrates the
> control flow, not production authentication. Use a verified session or credential validation for
> real access control.

The handler receives the Hono `context`, `next`, and a RELKIT context containing `signal`, `env`,
`auth`, `log`, and `time`. It does not receive the route target's validated input or its dependency clients.
Call public service functions for domain behavior rather than importing their private implementation.

## Choose the match scope

| Pattern            | Intended scope         |
| ------------------ | ---------------------- |
| `*`                | Global middleware      |
| `/orders`          | The collection path    |
| `/orders/:orderId` | A named path parameter |
| `/orders/*`        | An Orders path subtree |

Middleware patterns use `:parameter` and a trailing `*`, not the route directories' bracket syntax.
The declared pattern controls matching; nesting a middleware file under a directory does not scope it.
Use the narrowest pattern that covers the policy, and test both a subtree's base path and its children.
Include callback and preflight requests in those tests so broad authentication does not block them accidentally.

## Understand execution order

For a function-backed HTTP endpoint, processing runs through framework request setup and limits,
registered authentication, matching HTTP middleware, the route's rate limiter, request mapping,
function input validation and invocation, then response mapping.

Matching declared middleware is registered in normalized ID order, not service membership or import
order. `await next()` uses onion-style execution: before-code runs inward, and after-code runs outward
in reverse order. Returning a `Response` without `next()` skips the downstream route.

Consequently, middleware can reject before mapping or read a header before the rate limiter, but it
cannot assume function input has been validated. Avoid consuming the raw body stream in middleware
when the route still needs to parse it. Use header/session policy where possible and test any body access.

## Verify short-circuit and pass-through

With the commerce app running locally in test mode on its configured port `4000`:

```sh
curl -i http://localhost:4000/orders/order-1
curl -i http://localhost:4000/orders/order-1 \
  -H 'authorization: Bearer example'
```

The first request should return the middleware's `401`. The second passes this demo policy and reaches
the normal route outcome; that may be a declared not-found error if the order does not exist.
Use [local development](/docs/learn/local-development) to start your own app and adjust its port.

Add integration assertions for a denied request, an accepted request, a path outside the scope,
and response headers after `next()`. Assert that denial prevents the target from running.
Middleware-only statuses are not automatically included in the route's OpenAPI response contract;
document them alongside [responses](/docs/modules/http/responses).

Run middleware assertions against the actual server pipeline. The current `createTestApplication`
HTTP helper does not execute declared HTTP middleware, so its success alone cannot verify this policy.

## Include alternate entry points in policy tests

Generated clients call `/rpc`, not the original REST URL. The RPC runtime replays associated
path-scoped middleware, but it sees the native RPC request, not reconstructed REST path or body values.
Read [Generated clients](/docs/modules/http/generated-clients) before relying on path/body-dependent policy.
Test both transports if both are reachable.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/middleware/order-auth.middleware.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/middleware/order-auth.middleware.ts)

---

# OpenAPI and Scalar
Source: https://relkit.dev/docs/modules/http/openapi

Generate an OpenAPI document from your application's checked routes, schemas, and declared responses. Paths, methods, request locations,
schemas, statuses, declared errors, rate limits, and operation IDs therefore come from authored descriptors
rather than a separate annotation file.

The document describes HTTP routes, not the generated client's `/rpc` protocol.
[Raw handlers](/docs/modules/http/raw-handlers) use a generic response contract because their adapters own the response.

## Generate the document

### Refresh checked artifacts

```sh title="Terminal — relkit-orders"
bun run check
```

Inspect `.relkit/generated/openapi.json` when no server is running. The file is generated; fix route or
schema source when it is wrong.

### Inspect the runtime document

```sh title="Terminal — relkit-orders"
curl http://localhost:3000/_relkit/v1/openapi.json
```

With your existing app's [Echo endpoint](/docs/modules/http/define#expose-one-public-function) running, confirm
`openapi` is `3.1.0` and find `POST /echo`. Use the configured backend port if it differs.
The commerce example uses `4000` and also includes `/orders/{orderId}`.

### Open the interactive reference

JSON OpenAPI needs no documentation UI package. To select Scalar, install its optional peer from
your application root, then set `server.apiDocs.ui` to `"scalar"` in your existing `relkit.config.ts`:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @scalar/hono-api-reference@0.12.9
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

Restart the application after changing the selection. Startup validates the selected peer and
initializes the renderer before publishing readiness.

```sh title="Terminal — relkit-orders"
open http://localhost:3000/_relkit/v1/api-reference
```

Scalar renders the same protected document. Select an operation and verify parameters, request body,
success response, declared errors, and validation response.

## Trace a field back to source

The dynamic order route demonstrates path mapping, a named transform, several HTTP methods, and
response-status overrides:

```ts title="examples/commerce/src/routes/orders/[orderId]/route.ts"
/** Maps order methods to service members, normalizing GET identifiers and preserving the deletion 202 response. */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import orders from "../../../services/orders/service.js";
import normalizeOrderId from "@app/routes/transforms/orders/normalize-id.transform.js";

export const { GET, HEAD, PUT, PATCH, DELETE, OPTIONS } = defineServiceRoutes(orders, {
  GET: {
    member: "getOrder",
    request: http.input({
      orderId: http.transform(normalizeOrderId, http.path("orderId")),
    }),
  },
  HEAD: "getOrder",
  PUT: "updateOrder",
  PATCH: "updateOrder",
  DELETE: { member: "deleteOrder", successStatus: 202 },
  OPTIONS: "getOrder",
});
```

If a path parameter is absent from OpenAPI, inspect the filesystem segment and the route request mapping. If
a response is absent, inspect the target's declared errors or the route's explicit `responses` array. Use
`bun run relkit graph print` to connect the operation back to its source file.

## Operation identity and compatibility

OpenAPI's operation ID and the generated client's procedure key use the checked route ID. Changing a
path or method changes the inferred ID unless it is pinned explicitly. Moving a private function
without changing its route does not rename the endpoint. Compare generated contracts in review and
treat removed paths, newly required inputs, and narrowed outputs as compatibility decisions.

## Protect production documentation

> **Production documentation is opt-in**
>
> Enable `server.apiDocs.enabledInProduction` only with internal-endpoint authorization. Scalar
> embeds the protected OpenAPI document; protect the raw JSON endpoint as well as the UI. Enabling
> production docs without the required authorization configuration causes a startup configuration
> error.

In development and test, JSON OpenAPI is available independently of the UI. Scalar is disabled by
default; `server.apiDocs.ui: false` leaves the JSON document available without loading Scalar.
`server.apiDocs.excludeDomains` filters the served document; it does not disable those domains'
routes, revoke access, or remove generated-client operations. Documentation visibility is not authorization.

Disabling the public reference does not remove the build-time `openapi.json` artifact. Release tooling can
publish it to a controlled developer portal without exposing introspection from every application instance.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/orders/[orderId]/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/[orderId]/route.ts)

---

# Rate limits
Source: https://relkit.dev/docs/modules/http/rate-limits

Set a route's `rateLimit` to bound requests for a particular key during a time window. Matching HTTP middleware runs first; the route limiter then runs before input mapping and function invocation.
Rate limiting is transport policy, not authentication or a guarantee that a business operation executes once.

## Add a local policy

This source-backed compiler test demonstrates a process-local policy:

```ts title="Local rate-limit options — checked compiler example"
const route = defineRoute({
  id: "orders.local-rate-limit",
  target,
  rateLimit: { limit: 2, windowMs: 1_000, key: http.constant("global") },
});
```

In your route file, add that `rateLimit` object to the existing `defineRoute` options, keeping your
public service target and named method export. With `defineServiceRoutes`, add it to the object
containing `member`. Import `http` from `@relkit/app/routes` for the key mapping.

Here, `limit: 2` permits two requests per `windowMs: 1_000` for the constant key. It is a shared bucket
for callers of that route within one process, not a separate bucket per user. Both values must be
positive safe integers. Omitted `store` uses memory that resets with the runtime generation.

## Choose a trustworthy key

Supported key sources are a scalar `http.path`, `http.query`, `http.header`, `http.cookie`, or
`http.constant`. Body fields, catch-all arrays, transforms, optional/default wrappers, and callbacks
are not supported key mappings.

Choose a stable identity whose provenance you can verify. A client-controlled account header alone is
not a verified account: callers can rotate it to evade a limit. Enforce trusted proxy/header boundaries
or validate credentials in middleware. An absent key shares a missing-value bucket; it does not
automatically reject an unauthenticated request.

Key values are serialized into counter keys; they are **not hashed** by the limiter. Avoid putting raw
secrets in the key, logs, or metrics. Counter storage needs the same access controls as the identifiers it holds.

## Plan production counter storage

Local counters are independent per process. A production compilation rejects a rate-limited route
without an explicit `store`. The reference must resolve to a checked cache with numeric values, and
its provider must offer shared counters appropriate for the deployed replicas.

The compiler's production test checks the store reference and inferred `429` contract:

```ts title="Shared store descriptor — compiler test setup"
const store = defineCache({
  id: "api-rate-limits",
  key: z.string(),
  value: z.number(),
});
const route = defineRoute({
  id: "orders.list.http",
  target,
  rateLimit: {
    limit: 100,
    windowMs: 60_000,
    key: http.header("x-api-key"),
    store,
  },
});
```

This is compiler-level setup, not a complete domain layout or provider deployment recipe. It shows
the `store` contract; do not copy its `x-api-key` choice as advice to store secrets. Follow
[Caching](/docs/modules/caching) for cache ownership and provider configuration. Do not reach into another
domain's private cache from a route just to satisfy the reference.

An explicit store is a prerequisite, not proof of a deployment-wide quota. Verify the provider's
counter behavior under concurrency, process restarts, and multiple replicas before relying on the limit.

## Verify the response

After adding the two-per-second policy above to the [Echo endpoint](/docs/modules/http/first-route), run the
app in development and send three requests within one window:

```sh
for attempt in 1 2 3; do
  curl -i -X POST http://localhost:3000/echo \
    -H 'content-type: application/json' \
    -d '{"message":"hello"}'
done
```

Expect two `200` responses followed by `429` if all three arrive before the window resets.
The rejection body contains `error: "rate-limit"` and `retryAfterMs`. Inspect `RateLimit-Policy`,
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `Retry-After`; reset/retry header values
use seconds. A subsequent request can succeed after the window resets.

For repeatable tests, exercise the actual server pipeline with controlled counter storage. The current
`createTestApplication` HTTP helper does not apply route rate limits. Test key isolation for nonconstant
keys and confirm rejected requests do not invoke the target. See [Testing](/docs/modules/operations/testing).

## Check which entry points are actually limited

The route limiter wraps the original HTTP method/path. It does not wrap a [raw handler](/docs/modules/http/raw-handlers)
or the generated client's `/rpc` invocation of the target. If RPC is reachable, enforce equivalent
policy at that entry point or in shared business authorization; do not assume the REST limit protects it.
See [Generated clients](/docs/modules/http/generated-clients#test-security-at-both-entry-points).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/cache` API](/docs/api/cache)

- [`tests/compiler/rate-limit.test.ts`](https://github.com/rel-kit/relkit/blob/main/tests/compiler/rate-limit.test.ts)

---

# Raw handlers
Source: https://relkit.dev/docs/modules/http/raw-handlers

Mount a raw route when an integration already provides a native `Request`-to-`Response` handler. Use a [function-backed route](/docs/modules/http/define) for ordinary domain
operations that need RELKIT input validation, declared errors, and generated contracts.

> **Create the route from the terminal**
>
> Use [`relkit add route --mode route`](/docs/modules/http/define#scaffold-a-route) to create a raw
> `GET` handler, then replace its placeholder with your integration. For Better Auth, use [`relkit
> add auth`](/docs/modules/auth/better-auth#scaffold-the-auth-baseline), which creates the
> specialized service and its `ALL` mount together.

## Mount an HTTP integration

A raw route uses `defineRoute({ handler: ... })` and the named export `ALL`:

The auth example below requires complete [Better Auth installation and configuration](/docs/modules/auth/better-auth)
first. A minimal app does not acquire the auth SDK or database by copying this route.

```ts title="examples/commerce/src/routes/api/auth/[[...auth]]/route.ts"
/** Mounts the native Better Auth handler once for all methods and protects account/MCP application paths. */
import { defineRoute } from "@relkit/app/routes";
import auth from "../../../../services/auth/service.js";

export const ALL = defineRoute({
  // Forward every Better Auth method through one filesystem route.
  // Only the listed application paths require an authenticated session.
  handler: auth.handler,
  auth: { protected: ["/account/*", "/mcp"] },
});
```

This optional catch-all mounts the auth adapter at `/api/auth` and its nested paths. `ALL` delegates
every HTTP method at those paths; the adapter decides which operations it accepts.
The handler accepts a native `Request` and returns a `Response`, synchronously or asynchronously.

Do not combine `handler` and `target`, export a raw handler as `GET` or `POST`, or pass `ALL` to
`defineServiceRoutes`. Route file naming and collision checks still apply.

## Understand the boundary

| Behavior                                              | Function-backed route                              | Raw route                               |
| ----------------------------------------------------- | -------------------------------------------------- | --------------------------------------- |
| Entry point                                           | Public service function                            | Native HTTP handler                     |
| Input parsing and validation                          | Inferred or explicit mapping, then function schema | Owned by the adapter                    |
| Response construction                                 | Function output and declared response contract     | Adapter returns the complete `Response` |
| Function invocation context and declared dependencies | Available inside the target                        | No automatic function invocation        |
| Route `rateLimit`, `request`, and `responses` options | Supported                                          | Not part of the raw-handler API         |
| OpenAPI and generated-client operation                | Generated                                          | Excluded                                |

Framework request setup and matching HTTP middleware still surround raw routes. Do not assume this
makes arbitrary adapter body reads bounded or validates their payloads: configure the adapter's own
limits, signature checks, session security, and error handling. Use middleware or an upstream gateway
for transport policy that the raw-route API does not provide.

## Keep Better Auth protection explicit

The example's `auth.protected` list protects `/account/*` and `/mcp` using the registered Better Auth
service. It is not a list of routes created by the auth handler. The adapter owns the `/api/auth`
endpoints; protected paths select other application entry points that require a session.

The `auth` option is accepted only when `handler` belongs to a recognized Better Auth service.
It cannot add authentication to an arbitrary raw handler. This route also needs the corresponding
auth service and database configuration; copying only the route is not a complete auth setup.
See the [specialized service guidance](/docs/modules/service/organization#resources-do-not-go-in-the-service-member-list)
for the owning domain and the [Routes API reference](/docs/api/routes) for raw-route options.
Use [Better Auth service](/docs/modules/auth/better-auth) for a complete setup and
[Protect routes](/docs/modules/auth/protect-routes) for exact path matching and authorization boundaries.

## Verify the adapter separately

From the application root, run `bun run check`. Then test the base catch-all path, a nested path,
an unsupported method, a protected request without a session, and one with a valid session.
Assert the adapter's actual statuses, headers, and cookies; there is no generated route contract
to supply those assertions. Use the [testing guide](/docs/modules/operations/testing) for the application harness.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/api/auth/[[...auth]]/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/api/auth/[[...auth]]/route.ts)

---

# Request mapping
Source: https://relkit.dev/docs/modules/http/requests

Map HTTP parameters, headers, and body fields into the input expected by your function. The handler receives validated
business data, not a framework request object. Keep parsing choices on the route and reusable constraints
in the [function's schema](/docs/learn/concepts/schemas).

## Start with inference

When `request` is omitted, RELKIT projects the target's object input schema:

| Method                             | Properties matching path parameters | Remaining properties       |
| ---------------------------------- | ----------------------------------- | -------------------------- |
| `GET`, `HEAD`, `DELETE`, `OPTIONS` | Read from the path                  | Read from query parameters |
| `POST`, `PUT`, `PATCH`             | Read from the path                  | Read from the JSON body    |

For a write route with `accept: "multipart/form-data"`, remaining properties map from multipart fields
instead. Array properties use repeated fields; scalar properties use one field. See [Uploads](/docs/modules/http/uploads).

Thus `POST /echo` maps a JSON `message` into the Echo function without an explicit descriptor:

```ts title="src/routes/echo/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineRoute } from "@relkit/app/routes";
import echo from "@app/services/echo/service.js";

export const POST = defineRoute({
  target: echo.echo,
});
```

Path, query, header, and cookie scalar values arrive as strings. Use a schema that intentionally
coerces a number when needed; do not assume `?quantity=2` is already a JavaScript number.
Catch-all path values are arrays of decoded segments, not slash-joined strings.

## Replace inference when the HTTP contract differs

Use `http.input` for headers, cookies, renamed fields, nesting, or explicit transformations:

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

The public Create Order input remains independent of HTTP. This route chooses to obtain `orderId`
and `customerEmail` from headers, and `sku` and `quantity` from the JSON body.

An explicit `request` replaces inference completely. Include every required input field, including
matching path properties; RELKIT does not merge omitted fields back into the mapping.
If the input schema cannot be projected as an object, the compiler asks for an explicit mapping.
The mapping root is still `http.input`, which constructs an object: wrap a scalar or array body in a
named function-input property rather than expecting arbitrary non-object root input.

## Choose a source for each input property

| Helper                              | Value supplied                                     |
| ----------------------------------- | -------------------------------------------------- |
| `http.path(name)`                   | One path parameter                                 |
| `http.pathSegments(name)`           | Catch-all segment array                            |
| `http.query(name)`                  | One query parameter                                |
| `http.header(name)`                 | One header, matched case-insensitively             |
| `http.cookie(name)`                 | One cookie                                         |
| `http.body(name)`                   | One top-level JSON body field                      |
| `http.body()` or `http.wholeBody()` | The whole parsed JSON body, assigned to a property |
| `http.multipart(name)`              | One multipart text field or file                   |
| `http.multipartAll(name)`           | Repeated multipart fields or files                 |
| `http.constant(value)`              | A declared constant                                |
| `http.nested(fields)`               | An object assembled from nested mappings           |

`http.optional(source)` permits absence; `http.default(source, value)` supplies a fallback for absence.
Neither makes malformed or duplicated scalar input valid. Keep the resulting optional/default shape
consistent with the function schema.

## Scaffold a request transform

From your application's root:

```sh
bun run relkit add transform normalize-id
```

Creates `src/routes/transforms/normalize-id.transform.ts` with a string schema. Specialize
the schema and reference the descriptor with `http.transform` in a route's request mapping;
the CLI does not attach it to routes automatically. Transforms belong to the route platform,
so no service selection is needed.

For every transform scaffolding flag, see the [transform command reference](/docs/api/cli#relkit-add-transform-name).

Use `http.transform(transform, source)` with a compiler-known `defineTransform` descriptor, not an
inline callback. Put HTTP transforms under `src/routes/transforms/`. The commerce transform is schema-based:

```ts title="examples/commerce/src/routes/transforms/orders/normalize-id.transform.ts"
import { defineTransform } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";

export default defineTransform({ schema: z.string().min(1) });
```

The [dynamic Orders route](/docs/modules/http/routes#export-the-methods-you-support) applies it to `http.path("orderId")`.
See the [Routes API reference](/docs/api/routes) for helper signatures.

## Verify the transport boundary

For an app containing the [Echo tutorial](/docs/modules/http/first-route), with the backend running on port `3000`:

```sh
curl -i -X POST http://localhost:3000/echo \
  -H 'content-type: application/json' \
  -d '{"message":"hello"}'
```

Expect `200`. Repeat with an empty message, a missing field, and malformed JSON; expect validation
`422` before the function handler. For explicit mappings, also test a missing header, repeated scalar
query fields, and each optional/default branch. Unsupported body content types are mapping failures,
not automatically a `415` response.

HTTP middleware can inspect native request details, but function calls from jobs, events, tools,
or other domains do not receive a fabricated HTTP request. Pass business data explicitly.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/schema` API](/docs/api/schema)

- [`examples/commerce/src/routes/orders/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/route.ts)

---

# HTTP responses
Source: https://relkit.dev/docs/modules/http/responses

A function-backed route turns the function's validated result or declared error into an HTTP response. Start with inference;
override the transport only when the public HTTP contract needs it. Keep reusable errors in the
[domain's error declarations](/docs/learn/concepts/errors).

## Understand inferred responses

| Outcome                                       | Default response                         |
| --------------------------------------------- | ---------------------------------------- |
| Non-void function output                      | JSON `200`                               |
| `void` or `undefined` output                  | Empty `204`                              |
| Request mapping or input validation failure   | Validation JSON `422`                    |
| Declared application error                    | Its `http.status`, or `500` when omitted |
| Route rate-limit rejection                    | JSON `429`                               |
| Invalid function output or an internal defect | Safe server error `500`                  |

Declared application errors use the public error envelope, including their stable identity and
validated data. Do not assume the envelope is identical to the error's data schema alone.
Undeclared exceptions are not a way to create a public error contract.

Runtime failures can also produce responses such as provider failure `502` or timeout `504`.
The inferred OpenAPI list is not an exhaustive list of infrastructure or middleware failures.

## Choose one successful status

`POST` does not imply `201`. Set `successStatus` when one successful operation needs a different
`2xx` status while retaining inferred output and errors:

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

The Orders `POST` returns JSON `201`; its output schema and declared errors still come from
`createOrder`. The route above does not use an explicit `responses` array.
Use `successStatus` for this case instead of copying all inferred response declarations.

`HEAD` invokes the target but removes the response body. `204` responses are empty as well;
do not choose `204` when callers need the returned JSON.

## Replace the complete response contract only when needed

An explicit `responses` array replaces inference. The [Routes API](/docs/api/routes) provides:

| Helper                                 | Declaration                                                 |
| -------------------------------------- | ----------------------------------------------------------- |
| `http.success(status, schema)`         | Successful output and status                                |
| `http.error(errorId, status, schema)`  | Status for a declared application error and its data schema |
| `http.validationError(status, schema)` | Validation response; status defaults to `422`               |
| `http.response(id, status, schema)`    | A named generic response declaration                        |

Include success, validation, declared application errors, and any other outcomes the endpoint
promises. Omission does not prevent a runtime failure; it can leave the generated contract incomplete.
An omitted application-error mapping falls back to an internal error rather than a declared status.

Declarations are not branch handlers. Ordinary successful invocation uses the first success
declaration (or the first generic response when there is no success declaration). Listing several
success statuses does not select one based on returned data. These helpers do not define response
headers or content negotiation, and adding a `3xx` declaration does not implement a redirect.

Use [middleware](/docs/modules/http/middleware) for response headers and transport short-circuits. For an
adapter that owns redirects, binary bodies, or another HTTP protocol, consider a
[raw handler](/docs/modules/http/raw-handlers) and document its separate contract.

## Distinguish request failures from server failures

Input schema and mapping failures return `422` by default. That includes malformed JSON and
unsupported body content types in the request mapper. The framework's global Content-Length
check can reject an oversized request with `413`; a byte-limit failure encountered later while
mapping the body is a validation response. Test the layer your client actually reaches.

Function output is validated by the invocation engine. Invalid output is a server defect, not
a caller's `422`. Additional explicit response-schema checks run in development and test mode;
do not use a response-only schema as the sole production validation boundary.

## Verify status, headers, and body together

With the [Echo endpoint](/docs/modules/http/first-route) running on port `3000`:

```sh
curl -i -X POST http://localhost:3000/echo \
  -H 'content-type: application/json' \
  -d '{"message":"hello"}'
curl -i -X POST http://localhost:3000/echo \
  -H 'content-type: application/json' \
  -d '{"message":""}'
```

Expect JSON `200` for the first request and validation `422` for the second. Add tests for every
declared application error and middleware rejection in your own endpoint. A correct body with the
wrong status is still a broken HTTP contract.

Middleware-only responses are not automatically added to OpenAPI or the generated client's error
types. Describe them explicitly, and test the [RPC client](/docs/modules/http/generated-clients) separately:
it does not consume the REST response envelope.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/commerce/src/routes/orders/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/route.ts)

---

# File-system routes
Source: https://relkit.dev/docs/modules/http/routes

Place a `route.ts` file under `src/routes/` to define a URL, then export the HTTP methods it accepts. Named exports define its HTTP methods.
The domain directory does not supply a URL prefix: `/uploads` can call the Assets service, and
several paths can call the same public function. See [Define a route](/docs/modules/http/define) for the factories.

> **Let the CLI create the route path**
>
> [`relkit add route`](/docs/modules/http/define#scaffold-a-route) converts URL paths such as
> `/orders/:orderId` into `src/routes/orders/[orderId]/route.ts`. Choose a raw handler or map HTTP
> methods to public service functions; the conventions below apply to both.

## Choose a path

| File                                    | Route pattern              | Matching input                                 |
| --------------------------------------- | -------------------------- | ---------------------------------------------- |
| `src/routes/route.ts`                   | `/`                        | None                                           |
| `src/routes/orders/route.ts`            | `/orders`                  | None                                           |
| `src/routes/orders/[orderId]/route.ts`  | `/orders/:orderId`         | `orderId` string                               |
| `src/routes/files/[...parts]/route.ts`  | `/files/*parts`            | `parts` array of strings; at least one segment |
| `src/routes/docs/[[...parts]]/route.ts` | `/docs` and `/docs/*parts` | Optional `parts` array                         |

These are normalized route patterns, not literal URLs to request. For example, `/files/images/logo.png`
maps `parts` to `["images", "logo.png"]`. A catch-all must be the final segment; an optional catch-all
also matches the base path without any segments. Use an array input schema for catch-all values.

Parameter names must be valid identifiers and cannot repeat in one path. Route groups, parallel
routes, intercepting routes, and single optional segments such as `[[id]]` are not supported.
Keep layout or domain names out of the route tree unless they should appear in the URL.

## Export the methods you support

Function-backed routes support `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`:

```ts title="examples/commerce/src/routes/orders/[orderId]/route.ts"
/** Maps order methods to service members, normalizing GET identifiers and preserving the deletion 202 response. */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import orders from "../../../services/orders/service.js";
import normalizeOrderId from "@app/routes/transforms/orders/normalize-id.transform.js";

export const { GET, HEAD, PUT, PATCH, DELETE, OPTIONS } = defineServiceRoutes(orders, {
  GET: {
    member: "getOrder",
    request: http.input({
      orderId: http.transform(normalizeOrderId, http.path("orderId")),
    }),
  },
  HEAD: "getOrder",
  PUT: "updateOrder",
  PATCH: "updateOrder",
  DELETE: { member: "deleteOrder", successStatus: 202 },
  OPTIONS: "getOrder",
});
```

Each export is a separate operation, even when several exports select the same function.
The `GET` above maps the dynamic parameter through an explicit transform; other methods use inference.
Path properties map first, then remaining properties come from query or body according to the method.
See [Requests](/docs/modules/http/requests).

Export `HEAD` explicitly when it is part of the contract. It invokes the target but removes the response
body, so it still performs the target's work. An `OPTIONS` export also invokes its selected target;
it is not an automatic CORS policy. Use [middleware](/docs/modules/http/middleware) for CORS behavior.

Helper exports are allowed. A default route export, legacy `*.route.ts` layout, or explicit `path`/`method`
configuration produces migration diagnostics. `ALL` is reserved for [raw handlers](/docs/modules/http/raw-handlers).

## Understand matching precedence

Static segments match before dynamic segments, then required catch-all, then optional catch-all.
For example, `/orders/search` takes precedence over `/orders/[orderId]`. The compiler checks ambiguous
or duplicate registrations before activation; do not depend on module import order to choose a route.

An optional catch-all has base and expanded runtime registrations but remains one authored operation.
Test both forms, especially when middleware or authentication depends on the path.

## Treat route identity as a public contract

When `id` is omitted, RELKIT derives it from the method and normalized URL. For example,
`GET /orders/:orderId` becomes `route.get.orders.by-order-id`, and `GET /` becomes `route.get.root`.
Changing a path or method changes that inferred identity. Route IDs also name generated-client operations.

An explicit `id` can preserve operation identity during a move, but it does not preserve the old URL.
Review both URL compatibility and generated-client compatibility when renaming routes.

## Verify discovery and matching

From your application's root:

```sh
bun run check
```

Inspect the checked graph and `.relkit/generated/openapi.json` for every intended method and path.
Use HTTP integration tests for a static path beside a dynamic path, an unknown path, and both forms of
an optional catch-all. The [first-route walkthrough](/docs/modules/http/first-route) shows the test harness.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/orders/[orderId]/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/[orderId]/route.ts)

---

# Streaming responses
Source: https://relkit.dev/docs/modules/http/streaming

Return a sequence of values when a response should arrive incrementally instead of as one completed JSON object.

## Choose managed streaming

Declare `output: streamOf(itemSchema)` and return an async generator. The iterator is lazy,
single-consumer, schema-validates each item, and retains invocation scope until completion or
cancellation. The queue is bounded to 32 items and 4 MiB; a fully encoded item over 1 MiB fails
immediately.

```ts title="examples/commerce/src/services/orders/functions/stream-order-report.function.ts"
/** Supplies the report route with ten validated stream items, stopping when its invocation signal aborts. */
import { defineFunction, streamOf } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

const streamOrderReport = defineFunction({
  input: z.object({ reportId: z.string().min(1) }),
  output: streamOf(z.object({ completed: z.number().int(), total: z.number().int() })),
  handler: async function* (_input, context) {
    for (let completed = 1; completed <= 10; completed += 1) {
      // if (completed > 1) {
      //   await Bun.sleep(1_000);
      // }
      if (context.signal.aborted) return;
      yield { completed, total: completed };
    }
  },
});

export default streamOrderReport;
```

## Use from the frontend

Expose that function through a route before pulling its contract:

```ts title="src/routes/reports/[reportId]/route.ts — backend"
/** Maps a report path identifier to the order stream and exposes its validated items as server-sent events. */
import { defineRoute, http } from "@relkit/app/routes";
import orders from "../../../services/orders/service.js";

export const GET = defineRoute({
  target: orders.streamOrderReport,
  request: http.input({ reportId: http.path("reportId") }),
  client: { operation: "query" },
  stream: { format: "sse" },
});
```

After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
this component under the provider. The `GET /reports/:reportId` route exposes the streaming function:

```tsx title="src/Report.tsx"
"use client";

/** Consumes the commerce report route as a cancellable typed stream inside the client provider. */
import { useRelkitClient, useStream } from "@relkit/client/react";

/** Starts one report explicitly and displays its validated progress items.
 * @returns Start/cancel controls and visible progress or stream failure. */
export function Report() {
  const { status } = useRelkitClient();
  const report = useStream("GET /reports/:reportId");

  return (
    <section>
      <button
        disabled={status !== "ready"}
        onClick={() => void report.start({ reportId: "daily" })}
      >
        Run report
      </button>
      <button onClick={() => report.cancel()}>Cancel report</button>
      <p role="status">Completed: {report.items.map((item) => item.completed).join(", ")}</p>
      {report.error && <p role="alert">{String(report.error)}</p>}
    </section>
  );
}
```

`streamOf` supplies the item type, so `report.items` exposes each item's `completed` field.
`start({ reportId })` begins the request; `cancel()` releases it. Use the domain input even when
REST places a field in the URL. Streaming operations are excluded from finite `useRoute` queries.

Reference: [`useStream`](/docs/api/client#usestream).
Continue with [stream lifecycle and failures](/docs/modules/client/streams).

## Choose a native format

Managed oRPC iterators preserve typed completion and failure. Native SSE emits `relkit-item` and an
explicit `relkit-complete` or sanitized `relkit-error`. Native text and bytes abort on a post-header
application failure; because EOF cannot always distinguish failure, use managed streaming or SSE
when callers need an explicit terminal result. Existing raw Hono routes remain the escape hatch.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/client` API](/docs/api/client)

- [`packages/runtime-hono/tests/native-stream.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/runtime-hono/tests/native-stream.test.ts)

---

# File uploads
Source: https://relkit.dev/docs/modules/http/uploads

Accept multipart files by mapping request fields into your function's file schemas. RELKIT maps multipart fields into the target function's schemas,
enforces request and file ceilings, and invokes the function only after validation. Uploads are currently
buffered, so limits protect memory as well as domain policy.

## Model the upload operation

> **Before you begin**
>
> First complete [Storage's upload setup](/guides/storage/upload-product-images), including its
> selected adapter, local resource and provider binding. Multipart HTTP parsing alone does not
> install or configure a bucket.

The commerce example keeps storage behavior in a function and transport parsing in a route:

```ts title="examples/commerce/src/services/assets/functions/upload-assets.function.ts"
/** Validates multipart image files, writes them through the declared assets bucket and returns their uploaded names. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import assets from "../buckets/assets.bucket.js";

const uploadedFile = z.file({
  maxBytes: 1024 * 1024 * 10,
  mediaTypes: ["image/jpeg", "image/png"],
});

const uploadAssets = defineFunction({
  input: z.object({
    label: z.string().min(1),
    primary: uploadedFile,
    attachments: z.array(uploadedFile),
  }),

  output: z.object({
    label: z.string(),
    files: z.array(z.string()),
  }),

  dependencies: { buckets: { assets } },

  handler: async ({ label, primary, attachments }, context) => {
    const files = [primary, ...attachments];

    // This demo uses filenames as keys; uploading the same name replaces the file.
    await Promise.all(
      files.map(async (file) =>
        context.buckets.assets.put(file.name, new Uint8Array(await file.arrayBuffer()), {
          contentType: file.type,
        }),
      ),
    );

    return { label, files: files.map(({ name }) => name) };
  },
});

export default uploadAssets;
```

`z.file` values provide the validated file name, media type, size, and bytes. The function declares bucket
access, writes through the provider-neutral client, and returns ordinary JSON metadata. It does not receive a
multipart parser or raw HTTP request.

```ts title="examples/commerce/src/routes/uploads/route.ts"
/** Admits bounded multipart upload requests to the assets service's validated image handler. */
import { defineRoute } from "@relkit/app/routes";
import assets from "../../services/assets/service.js";

export const POST = defineRoute({
  target: assets.uploadAssets,
  accept: "multipart/form-data",
  maxBodyBytes: 10 * 1024 * 1024,
});
```

The route opts into `multipart/form-data` and sets a route-specific body ceiling. The function schema decides
which fields are single files, repeated files, or text values. No explicit `request` is needed for this
matching object shape; use `http.multipart` and `http.multipartAll` inside `http.input` when names differ.

To add this to your own app, follow [Storage's upload walkthrough](/guides/storage/upload-product-images) for the
bucket, public Assets service, provider configuration, and tests. Copying only the route does not create
its dependencies.

## Send a complete multipart request

1. ### Prepare representative files

    Use two real, small PNG files named `primary.png` and `detail.png` in your terminal's working
    directory. Keep their combined request below 1 MiB for the default commerce configuration.
    These commands assume the commerce app is running locally in test mode on port `4000`, with its
    local bucket provider available. Adjust the port for your own app.

2. ### Upload every required field

    ```sh title="Terminal — relkit-orders"
    curl -i -X POST http://localhost:4000/uploads \
      -F label=receipts \
      -F "primary=@primary.png;type=image/png" \
      -F "attachments=@detail.png;type=image/png"
    ```

    Expect HTTP `200` and JSON listing `primary.png` and `detail.png`. Repeat `attachments` for more files.
    Let curl set the multipart Content-Type boundary; do not supply a bare Content-Type header yourself.

3. ### Prove invalid input is rejected

    ```sh title="Terminal — relkit-orders"
    curl -i -X POST http://localhost:4000/uploads \
      -F label=receipts \
      -F "primary=@primary.png;type=text/plain" \
      -F "attachments=@detail.png;type=image/png"
    ```

    Expect a bounded `422` response for the unsupported declared media type. The storage handler must
    not run. Also test missing required fields and duplicate scalar fields.

## Set every relevant limit

Coordinate `server.maxBodyBytes`, the route's `maxBodyBytes`, and individual `z.file` constraints.
The framework checks Content-Length against the server ceiling before the route runs; the request
mapper then enforces the route-specific ceiling, or the server/default limit when omitted. Raising
only the route limit does not bypass an earlier global rejection.

The commerce server ceiling is 1 MiB, even though this route and each file schema declare 10 MiB.
That is why the commands above use small files. A request ceiling includes multipart framing and all
fields; accepting several maximum-size files requires a correspondingly larger total budget. Test
oversized requests with and without Content-Length. See [Responses](/docs/modules/http/responses) for `413`
versus mapping-validation failures.

For large media, streaming ingestion, resumable transfer, or direct-to-object-store uploads, use a purpose-built
upload flow rather than raising a buffered route to unbounded sizes. A signed upload URL can keep large bytes
off the application server while a later validated request records metadata.

## Security checklist

- Generate storage keys independently from untrusted file names when overwriting matters.
- Treat reported media type as input, not proof of file content; the schema does not sniff file bytes.
- Keep private buckets private and return signed URLs only after authorization.
- Avoid logging file bytes, access tokens, or multipart bodies.
- Test missing fields, repeated fields, zero-byte files, media mismatch, and both size ceilings.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/schema` API](/docs/api/schema)
- [`@relkit/buckets` API](/docs/api/buckets)

- [`examples/commerce/src/routes/uploads/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/uploads/route.ts)

---

# Integration catalog
Source: https://relkit.dev/docs/modules/integrations

An integration connects a RELKIT capability to a provider, such as S3 for files or Redis for cached values. Services, functions, routes, and events
depend on checked capability contracts; integrations connect those contracts to Redis, S3,
telemetry exporters, local Docker services, and deployment platforms.

> **Start here**
>
> For your first local integration, follow [Cache product
> prices](/guides/caching/cache-product-prices) for Redis or [Upload product
> images](/guides/storage/upload-product-images) for MinIO. Both include installation,
> configuration, and verification. The [integration references](/docs/api#integrations) list each
> package's exact APIs.

## Pre-setup

Start with a working minimal app and Docker. Install the owner of each selected adapter,
then bind it in `relkit.config.ts` through `defineApp`. Use `docker(adapter())` when it has
a local recipe; the wrapper supplies development connection values. Follow the module's
setup before adding its first resource:

**[Buckets and MinIO](/docs/modules/storage#pre-setup)**

**[Cache and Redis](/docs/modules/caching#pre-setup)**

**[Realtime and Redis](/docs/modules/realtime#pre-setup)**

**[Native task providers](/docs/modules/jobs#pre-setup)**

**[PostgreSQL and auth](/docs/modules/database/local-docker)**

**[Agent state](/docs/modules/ai#pre-setup)**

Named connection bindings such as `binding.secret(...)` select provider values; `defineEnv`
declares application values available to functions. Keep the distinction when configuring
[environment contracts](/docs/learn/concepts/environment). Run `bun run check` before
`bun run dev`; a package installation alone creates no profile or running resource.
The [Docker coverage table](/docs/modules/integrations/local-docker#supported-local-services)
identifies providers without a recipe.

## Choose packages by role

| Package               | Role                                                                             | Continue with                                                 |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `@relkit/redis`       | Redis cache adapter and pinned local recipe                                      | [Caching](/docs/modules/caching)                              |
| `@relkit/s3`          | S3-compatible bucket adapter and pinned MinIO recipe                             | [Storage](/docs/modules/storage)                              |
| `@relkit/sentry`      | Error telemetry exporter                                                         | [Observability](/docs/modules/operations/observability)       |
| `@relkit/otlp`        | OTLP trace exporter                                                              | [Observability](/docs/modules/operations/observability)       |
| `@relkit/docker`      | Local-recipe selector and Docker materializer                                    | [Local Docker](/docs/modules/integrations/local-docker)       |
| `@relkit/local`       | Filesystem event/job, realtime and agent-state profiles; local lifecycle support | [Local providers](/docs/modules/integrations/local-providers) |
| `@relkit/aws`         | AWS host, infrastructure ownership, and access materialization                   | [AWS deployment](/docs/modules/deployment/aws)                |
| `@relkit/pulumi`      | Pulumi deployment engine                                                         | [Deployment](/docs/modules/deployment)                        |
| `@relkit/cloudflare`  | R2/KV runtime adapters; no application host                                      | [Connected providers](/docs/modules/deployment/providers)     |
| `@relkit/inngest`     | Native durable-task adapter and account-free Docker recipe                       | [Jobs](/docs/modules/jobs/providers/inngest)                  |
| `@relkit/trigger`     | Trigger.dev task adapter and worker publication                                  | [Jobs](/docs/modules/jobs/providers/trigger)                  |
| `@relkit/effect-mq`   | PostgreSQL-backed retryable task adapter                                         | [Jobs](/docs/modules/jobs/providers/effect-mq)                |
| `@relkit/drizzle`     | Optional database integration and selected native ORM                            | [Database installation](/docs/modules/database/define)        |
| `@relkit/better-auth` | Optional auth bridge; native SDK and React leaf selected separately              | [Auth installation](/docs/modules/auth/better-auth)           |
| `@relkit/langchain`   | Optional native agent engine and selected SDK cohort                             | [Agent installation](/guides/ai/build-an-offline-agent)       |
| `@relkit/inspector`   | Separately installed UI and history tool                                         | [Inspector setup](/docs/modules/operations/inspector)         |

Install standalone packages when you want the smallest dependency surface:

**Docker Redis**

For Docker Redis, the selected recipe is:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

**Cloudflare KV/R2**

For connected Cloudflare KV/R2 instead, install its owner and supply that adapter's named connection
values. This does not select AWS/Pulumi or a Docker recipe:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/cloudflare@0.7.14
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The optional `@relkit/integrations` catalog contains package metadata and installs no adapters.
Import executable capabilities directly from the selected standalone packages. The following source
illustrates separate choices; install only the owners you actually import, using their linked setup:

```ts title="Standalone integration imports"
/** Demonstrates a Redis cache selected through its standalone Docker integration. */
import { defineApp, defineEnv } from "@relkit/app/config";
import { docker } from "@relkit/docker";
import { redis } from "@relkit/redis";

export default defineApp({
  env: defineEnv({}),
  cache: docker(redis()),
});
```

Native agents use `@relkit/langchain` together with its documented LangChain SDK requirements.
Install the model provider package selected by your application directly.

## Understand ownership

Connected adapters wire a resource that already exists. `docker(adapter)` selects the adapter's local recipe
for development only. Infrastructure wrappers such as `aws(adapter)` let the deployment stack own a resource.
The deployment engine and host are separate roles, so selecting AWS hosting does not claim every connected
Redis, S3-compatible, Cloudflare, or model resource.

Run `bun run check` to validate package registration, source wrappers, profile selection, and deployment-role
compatibility before starting a runtime or previewing infrastructure.

## Declare authoring entrypoints

If you are implementing an adapter, begin with [Provider authoring](/docs/modules/integrations/provider-authoring) for a maintained example and validation steps. Use [Local providers](/docs/modules/integrations/local-providers) when explicitly owning local runtime state.

Integration package authors list their application authoring entrypoints in
`package.json` under `relkit.integration.exports.authoring`. Use a string for one exact export,
such as `"."`, or an explicit list when multiple authoring leaves are public:

```json
{ "authoring": [".", "./sqlite", "./pg", "./mysql"] }
```

Every listed leaf must also exist in the package's `exports` map. The compiler accepts only those
exact imports; listing a parent does not permit its children. Wildcards and path traversal are
rejected. Drizzle declares its three dialect model entrypoints, and Better Auth declares its root
and `./drizzle` bridge. Runtime internals, React adapters, and testing helpers do not become
application authoring entrypoints through this declaration.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/integrations` API](/docs/api/integrations/catalog)
- [`@relkit/docker` API](/docs/api/integrations/docker)
- [`@relkit/redis` API](/docs/api/integrations/redis)
- [`@relkit/s3` API](/docs/api/integrations/s3)
- [`@relkit/cloudflare` API](/docs/api/integrations/cloudflare)
- [`@relkit/local` API](/docs/api/integrations/local)

- [`apps/docs/examples/landing/catalog.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/landing/catalog.ts)

---

# Local Docker services
Source: https://relkit.dev/docs/modules/integrations/local-docker

Run selected providers locally with Docker recipes while keeping their configuration in your application. `check` writes a deterministic plan
without contacting Docker. `dev` then starts only the recipes required by the checked graph, waits for their
health checks, and supplies their outputs to the matching binding.

## Pre-setup

Start Docker and complete the selected capability's installation and `defineApp` configuration
from the table below. Docker recipes supply their own connection values; application-specific
fields still belong in `defineEnv`. Keep all existing profiles and state when adding a recipe.

## Supported local services

| Capability                  | Default local setup                                  | Configuration and environment                                                             |
| --------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Buckets                     | MinIO through `docker(s3())`                         | [Storage pre-setup](/docs/modules/storage#pre-setup); generated local credentials         |
| Caches                      | Redis through `docker(redis())`                      | [Caching pre-setup](/docs/modules/caching#pre-setup); generated connection                |
| Realtime                    | Redis through `docker(redisRealtime())`              | [Realtime pre-setup](/docs/modules/realtime#pre-setup)                                    |
| Agent state                 | Redis through `docker(redisAgentState())`            | [AI pre-setup](/docs/modules/ai#pre-setup); model secrets are separate                    |
| Native jobs                 | Docker Inngest, Trigger.dev, or Effect MQ            | [Jobs pre-setup](/docs/modules/jobs#pre-setup); provider-specific composite recipes       |
| Application database        | PostgreSQL through an application-owned Compose file | [Database pre-setup](/docs/modules/database/local-docker); `DATABASE_URL`                 |
| Application events          | Filesystem provider; no Docker recipe                | [Events pre-setup](/docs/modules/events#pre-setup); preserve `.relkit/state`              |
| HTTP, local logs, Inspector | No external service required                         | [HTTP](/docs/modules/http#pre-setup) and [Operations](/docs/modules/operations#pre-setup) |

The database Compose service is managed with `docker compose`, not `relkit local`.
Connected Cloudflare KV/R2, hosted models, Sentry, and OTLP have no bundled local Docker recipe.

## Current bundled images

> **Before you begin**
>
> First complete the selected [Redis cache](/guides/caching/cache-product-prices) or [S3/MinIO
> bucket](/guides/storage/upload-product-images) installation. Each selects its adapter plus
> `@relkit/docker`; installing the materializer alone supplies no Redis/S3 adapter or binding.

The integration packages pin an immutable digest. A RELKIT package release therefore
selects an exact local-service image rather than whatever a mutable tag points to later.

| Adapter    | Image reference          | Immutable digest                                                          |
| ---------- | ------------------------ | ------------------------------------------------------------------------- |
| Redis      | `redis:7.4.2-alpine`     | `sha256:02419de7eddf55aa5bcf49efb74e88fa8d931b4d77c07eff8a6b2144472b6952` |
| S3 / MinIO | `ghcr.io/teableio/minio` | `sha256:a1ea29fa28355559ef137d71fc570e508a214ec84ff8083e39bc5428980b015e` |

The MinIO reference uses a public mirror of `RELEASE.2025-04-22T22-12-26Z` with the same digest as the
original image.

RELKIT discovers the Docker server version at startup but does not currently enforce a minimum engine
version. Use a maintained Docker Engine or Docker Desktop release with the `docker` CLI available on `PATH`:

```sh
docker version
bun run relkit local status
```

## Select local recipes

Use `docker(redis())` or `docker(s3())` for a local-only binding. Wrap a configured connected adapter when
development should use Docker while release builds resolve named binding values. The Redis and storage guides
show both forms in the commerce application.

Docker starts Redis with a persistent `/data` volume and waits for `redis-cli PING`. MinIO receives generated
project-local credentials, persists `/data`, waits for its readiness endpoint, and initializes the `relkit`
bucket. Both publish random loopback ports instead of claiming fixed host ports.

## Optional file-backed events and legacy jobs

The filesystem event and legacy job profiles do not use Docker. `localEvent()` and `localJob()` from `@relkit/local` register
the existing durable filesystem runtimes and store their state under `.relkit/state` by default. The `event`,
`event-function`, and `job` add commands reuse compatible profiles; a full service bundle creates these local
profiles when no configured defaults exist. See the [Local API](/docs/api/integrations/local) for direct
authoring. Use a different `root` only when the application needs an isolated local state directory.
New task-first jobs use a native Docker provider from the table above; `localJob()` is not that provider.

The corresponding scaffold normally installs the owner. For manual file-backed configuration,
select this installation before importing those profiles:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/local@0.7.14
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

## Control the project lifecycle

```sh
bun run relkit local up --detach
bun run relkit local status
bun run dev --local=off
bun run relkit local stop
bun run relkit local reset --yes
```

Healthy services and volumes survive source reloads. `stop` stops this project's labelled services; `reset`
also removes its validated volumes and override state. It refuses a live attached lease and never targets
another checkout. Docker is not contacted by `build`, deployment preview, or deployment apply.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/docker` API](/docs/api/integrations/docker)
- [`@relkit/redis` API](/docs/api/integrations/redis)
- [`@relkit/s3` API](/docs/api/integrations/s3)

- [`integrations/packages/redis/src/local-recipe/index.ts`](https://github.com/rel-kit/relkit/blob/main/integrations/packages/redis/src/local-recipe/index.ts)
- [`integrations/packages/s3/src/local-recipe/index.ts`](https://github.com/rel-kit/relkit/blob/main/integrations/packages/s3/src/local-recipe/index.ts)

---

# Local runtime providers
Source: https://relkit.dev/docs/modules/integrations/local-providers

Use `@relkit/local` to select local event, job, realtime, and agent-state profiles in
application configuration. `@relkit/providers-local` contains lower-level implementations
for runtime authors and tests. Creating one directly makes you responsible for its state
directory and lifetime.

## Read and write a local object

In a tooling or test package, install `@relkit/providers-local` at the version used by the
application. Pass a dedicated directory to this helper:

```ts title="local-object.ts"
/** Shows filesystem bucket ownership with a caller-owned directory and explicit cleanup. */
import { createLocalBucketProviderForTest } from "@relkit/providers-local";

/** Writes and reads a local object, then closes the provider without deleting its directory.
 * @param root - Dedicated directory owned by this test/application.
 * @returns The stored bytes, or undefined if an object unexpectedly disappears. */
export async function readLocalObject(root: string): Promise<Uint8Array | undefined> {
  const bucket = createLocalBucketProviderForTest({ root, maxObjectBytes: 1024 });
  try {
    if (!bucket.put || !bucket.get) throw new Error("Bucket must support reads and writes");
    await bucket.put("example.txt", new TextEncoder().encode("Hello, RELKIT!"), {
      contentType: "text/plain",
    });
    return await bucket.get("example.txt");
  } finally {
    await bucket.close();
  }
}
```

The result decodes to `Hello, RELKIT!`. The helper closes the provider after reading;
closing does not delete the directory. The caller owns directory creation and removal.
Local filesystem buckets do not create signed download or upload URLs. Use the
[S3-compatible storage setup](/docs/modules/storage/local-storage) when you need those capabilities.

## Choose a capability

| Capability  | Runtime APIs                                                    | Application workflow                                           |
| ----------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| Buckets     | `createLocalBucketProvider`, `createLocalBucketProviderForTest` | [Upload product images](/guides/storage/upload-product-images) |
| Cache       | `createLocalCacheProviderForTest`                               | [Cache product prices](/guides/caching/cache-product-prices)   |
| Events      | `createLocalEventProvider`                                      | [React to order events](/guides/events/react-to-order-events)  |
| Jobs        | `createLocalJobProvider` and queue/store helpers                | [Choose a job provider](/docs/modules/jobs/providers)          |
| Realtime    | `createLocalRealtimeProvider`                                   | [Realtime providers](/docs/modules/realtime/providers)         |
| Agent state | `createLocalAgentStateProvider`                                 | [Build an offline agent](/guides/ai/build-an-offline-agent)    |

See the [complete local provider API](/docs/api/providers-local#all-exported-apis) for
options, errors, state protocols, and helper types. For ordinary function tests, prefer
the smaller [testing fakes](/docs/modules/operations/testing#replace-provider-profiles-explicitly).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/providers-local` API](/docs/api/providers-local)
- [`@relkit/local` API](/docs/api/integrations/local)

- [`apps/docs/examples/public-api/local.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/local.ts)

---

# Author a provider
Source: https://relkit.dev/docs/modules/integrations/provider-authoring

A provider adapter describes how an application connects a capability to an integration.
Use the existing [integration catalog](/docs/modules/integrations) when you need Redis, S3,
or another supported provider. This page is for authors adding an integration.

## Define the connection and behavior

Install `@relkit/provider` in the integration package. Keep its version aligned with the
RELKIT packages you test against. The following descriptor declares a cache connection:

```ts title="src/provider.ts"
/** Builds a provider's serializable authoring descriptor; acquiring a runtime is a separate integration role. */
import {
  defineConnectionContract,
  defineIntegrationReference,
  defineProviderAdapter,
  defineProviderBehavior,
  defineProviderCapability,
} from "@relkit/provider";

export const cacheAdapter = defineProviderAdapter({
  integration: defineIntegrationReference("example-cache"),
  capability: defineProviderCapability("cache"),
  adapterId: "example-cache.v1",
  connectionContract: defineConnectionContract({ url: { sensitive: true } }),
  connection: { url: "redis://127.0.0.1:6379" },
  behavior: defineProviderBehavior({ keyPrefix: "products" }),
});
```

`defineProviderCapability` identifies the capability. `defineConnectionContract` declares
allowed connection fields; fields are required by default. Mark credentials and connection
URLs as sensitive. `defineProviderBehavior` holds serializable settings, and
`defineProviderAdapter` checks the field names and produces an immutable descriptor.

This example produces metadata; it does not connect to Redis. The runtime integration owns
connection acquisition, capability operations, cancellation, readiness, and cleanup.
Follow the [Redis implementation](https://github.com/rel-kit/relkit/tree/main/integrations/packages/redis/src)
for an existing implementation of these separate responsibilities.

## Publish the correct entrypoints

Declare the authoring import in `relkit.integration.exports.authoring`, as explained in
[integration registration](/docs/modules/integrations#declare-authoring-entrypoints).
Expose runtime and local-recipe entrypoints only for the roles your integration implements.
Application configuration imports the authoring descriptor; runtime acquisition remains
outside descriptor construction.

The [provider API index](/docs/api/provider#all-exported-apis) includes bindings, features,
local recipes, connection validation, and their companion types. APIs ending in `Effect`
are the lazy forms for integration authors already composing Effect programs; application
configuration can use the synchronous builders shown above.

Continue with [local Docker recipes](/docs/modules/integrations/local-docker), or see an adapter
in an application in [Cache product prices](/guides/caching/cache-product-prices).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/provider` API](/docs/api/provider)

- [`apps/docs/examples/public-api/provider.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/provider.ts)

---

# Jobs
Source: https://relkit.dev/docs/modules/jobs

A job exposes work that can continue after the request that started it has ended. Define a typed task, expose it through a job, and let RELKIT persist the run, retry transient failures, and report progress.

> **Start here**
>
> Follow the [quickstart](/docs/modules/jobs/quickstart) to run an order export. For exact task and
> job options, open the [Jobs reference](/docs/api/jobs).

## Pre-setup

Use a native task provider in local Docker. Inngest is the starting path here;
[Trigger.dev](/docs/modules/jobs/providers/trigger) and [Effect MQ](/docs/modules/jobs/providers/effect-mq)
also have Docker recipes. Choose one and review its [capabilities](/docs/modules/jobs/providers/comparison).

1. **Install Inngest and local tooling**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/inngest@0.8.3 @relkit/local@0.7.14 inngest@4.20.0
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the jobs profile**

    Merge `jobs` and `defaults.jobs` into your root configuration. Keep your existing ID,
    `env` import and other settings; the example imports the environment contract from `src/platform/env.ts`.

    ```ts title="relkit.config.ts"
    /** Declares task application defaults with inspection disabled until selected. */
    import { defineApp } from "@relkit/app/config";
    import env from "@app/platform/env.js";
    import { docker } from "@relkit/docker";
    import { inngest } from "@relkit/inngest";

    export default defineApp({
      id: "relkit-inngest",
      env,
      server: { port: 3000, maxBodyBytes: 1_048_576 },
      telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
      jobs: { default: docker(inngest()) },
      defaults: { jobs: "default" },
    });
    ```

    Docker supplies the local provider's connection values; there are no new `defineEnv` secrets
    for this recipe. Jobs with `profile: "default"` use this binding. `localJob()` is the older
    function-target provider and is not a substitute for the native task provider used here.

3. **Check and start after registering the task and job**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

    Use `bun run relkit jobs capabilities` to inspect the selected provider, then follow
    [Your first durable job](/docs/modules/jobs/quickstart) to submit and observe a run.

## Start here

[Quickstart](/docs/modules/jobs/quickstart) — define a task and trigger its job.

[Tasks](/docs/modules/jobs/tasks) — the unit of durable execution.

[Bindings](/docs/modules/jobs/bindings) — choose a provider and bind jobs to it.

[Execution policy](/docs/modules/jobs/execution-policy) — timeouts, concurrency, and
cancellation.

[Retries and idempotency](/docs/modules/jobs/retries-and-idempotency) — safe retry behavior.

[Clients](/docs/modules/jobs/clients) — trigger, watch, and recover runs.

[Schedules](/docs/modules/jobs/schedules) — register provider-backed schedules.

[Providers](/docs/modules/jobs/providers) — compare native capability evidence.

## The model

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

```ts title="examples/commerce/src/services/orders/jobs/export-orders.job.ts"
/** Registers the export task as a public job exposing trigger, get, list and watch with progress/output fields. */
import { defineJob } from "@relkit/app/jobs";
import exportOrders from "../tasks/export-orders.task.js";

const exportOrdersJob = defineJob({
  name: "exportOrders",
  id: "orders.export-orders",
  task: exportOrders,
  client: {
    public: true,
    operations: ["trigger", "get", "list", "watch"],
    fields: ["status", "progress", "output"],
  },
});

export default exportOrdersJob;
```

Tasks own execution code, schemas, retry policy, limits, and hooks. Jobs own the public API name, admission, schedules, service selection, and client projection. The task ID, version, input schema, output schema, and policy are part of the durable identity of a run.

## Defaults worth knowing

- A run accepts at most 1 MiB of input and returns at most 1 MiB of output.
- A progress or stream item is limited to 64 KiB.
- The default retry policy is three attempts, one-second initial delay, 30-second maximum delay, factor two, and no jitter.
- Run lists default to 25 items and accept at most 100.

Read [provider comparison](/docs/modules/jobs/providers) before depending on durable sleep, native listing, or a schedule policy.

## Legacy API

The older function-target pages (`define`, `enqueue`, `first-job`, `retries`, `idempotency`, and `schedules`) remain available for migration. New code should use task-first jobs so task identity and compatibility checks are explicit.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/services` API](/docs/api/services)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/jobs/export-orders.job.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/jobs/export-orders.job.ts)

---

# Bindings
Source: https://relkit.dev/docs/modules/jobs/bindings

A job binding selects the provider that accepts and executes your application's tasks. The commerce fixture uses the same shape:

> **Before you begin**
>
> Before copying this Inngest binding into an existing app, complete its [adapter, SDK and
> local-tooling installation](/docs/modules/jobs/providers/inngest).

```ts title="examples/commerce/relkit.config.ts"
jobs: { default: docker(inngest()) },
defaults: {
  bucket: "assets",
  cache: "requests",
  realtime: "default",
  "agent-state": "agents",
  jobs: "default",
},
```

The binding is part of the compiled deployment plan. It records the provider profile, capability evidence, execution limits, and the worker identity used for publication. A job may use an explicit binding when a service needs a different provider or environment.

An explicit job selects a named service with `service: "default"`; it does not use a `binding` field.
If no service is specified, the compiler resolves the application's default jobs binding and records the
selected adapter in the manifest.

The compiler rejects a job whose requested execution mode is not provided by its binding. Run `relkit jobs capabilities` to inspect the selected provider and its actual limits.

Provider guides: [Inngest](/docs/modules/jobs/providers/inngest), [Trigger.dev](/docs/modules/jobs/providers/trigger), and [Effect MQ](/docs/modules/jobs/providers/effect-mq).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/docker` API](/docs/api/integrations/docker)
- [`@relkit/inngest` API](/docs/api/integrations/inngest)

- [`examples/commerce/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)
- [`examples/commerce/src/services/orders/jobs/export-orders.job.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/jobs/export-orders.job.ts)

---

# Job clients
Source: https://relkit.dev/docs/modules/jobs/clients

Trigger a job through the generated client, then use its run handle to observe progress and completion. Only jobs with a `client` policy appear. Triggering one admits work; the returned
handle identifies a run and is **not** the completed result:

Install the [frontend client and development CLI](/docs/modules/client) in the caller's package first.
Submit with `client.jobs.exportOrders.trigger({ input: { orderIds }, options: { operationId } })`,
then read `client.jobs.exportOrders.runs.get({ runId: accepted.runId })`. The caller installs no
provider SDK; those dependencies belong to the backend's selected job binding.

Keep `accepted.runId` and `operationId` so a later page load or retry can inspect the same run.
The app must authorize the caller for this job; a typed client alone does not grant access.

## Use from React

The [`defineJob` example](/docs/modules/jobs/quickstart#2-expose-a-job) names this job `exportOrders`
and exposes `trigger`, `get`, `list`, and `watch`. After [frontend setup](/guides/frontend/connect-react)
and pulling that backend's contract, render this component under `RelkitClientProvider`:

```tsx title="src/ExportOrders.tsx"
"use client";

/** Submits one commerce export and observes the accepted run without replaying an uncertain submission. */
import { useJobRun, useJobTrigger, useRelkitClient } from "@relkit/client/react";

/** Keeps the accepted receipt separate from the task's eventual output.
 * @returns One explicit submission button and its receipt, observation, or failure state. */
export function ExportOrders() {
  const { status } = useRelkitClient();
  const submit = useJobTrigger("exportOrders");
  const run = useJobRun("exportOrders", submit.data ? { runId: submit.data.runId } : {});

  return (
    <section>
      <button
        disabled={status !== "ready" || !submit.isIdle}
        onClick={() => submit.mutate({ input: { orderIds: ["order-1"] } })}
      >
        Export orders
      </button>
      {submit.isPending && <p role="status">Submitting…</p>}
      {submit.isError && (
        <p role="alert">{String(submit.error)}. Check the outcome before submitting again.</p>
      )}
      {submit.data && <p>Run ID: {submit.data.runId}</p>}
      <p role="status">
        Connection: {run.connection}; run: {run.run?.status ?? "not accepted"}
      </p>
    </section>
  );
}
```

The hook selector is the job's public **name**, `exportOrders`, rather than its stable backend ID
`orders.export-orders`. `useJobTrigger` supplies managed operation identity and retains pending
receipt metadata. `useJobRun` waits for an accepted `runId`; mounting it does not submit a job.
Persist that receipt in your application's own UI state if the page must restore it after navigation.

| Client API                                                                                | Backend policy required               | Use                                                          |
| ----------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------ |
| [`useJobTrigger`](/docs/api/client#usejobtrigger)                                         | `trigger`                             | Submit typed task input and receive a run handle.            |
| [`useJobRun`](/docs/api/client#usejobrun) / [`watchJobRun`](/docs/api/client#watchjobrun) | `watch`                               | Observe only the fields selected by the job's client policy. |
| [`useJobCancel`](/docs/api/client#usejobcancel)                                           | `cancel`                              | Send an explicit control with `runId` and `operationId`.     |
| [`useJobRetry`](/docs/api/client#usejobretry)                                             | `retry`                               | Ask the provider to retry a run explicitly.                  |
| [`watchJobStream`](/docs/api/client#watchjobstream)                                       | `streams` and a declared named stream | Read the run's named content stream with its own lifecycle.  |

Cancel, retry, and named streams are not exposed by this example's policy. Declare the needed
operations on the backend and pull a new contract before using them. Generated types also restrict
which run fields the frontend can read. For an uncertain write, follow
[recovery guidance](/docs/modules/client/offline); do not turn reconnect into automatic resubmission.

## Watch one accepted run

`watchJobRun` uses the accepted run ID. This public API example subscribes to state changes,
connects once, and disposes the watcher when its caller is finished:

```ts title="Watch an export run"
import { createClient } from "@relkit/client";
import { watchJobRun } from "@relkit/client/jobs";

export async function watchExport(runId: string): Promise<() => Promise<void>> {
  const client = createClient({ baseUrl: "http://127.0.0.1:3000" });
  const watch = watchJobRun(client, "exportOrders", { runId });
  const unsubscribe = watch.subscribe(({ connection, run }) => {
    console.log(connection, run?.status);
  });
  try {
    await watch.connect();
  } catch (error) {
    unsubscribe();
    await watch.dispose();
    throw error;
  }
  return async () => {
    unsubscribe();
    await watch.dispose();
  };
}
```

Call the returned cleanup function when the component or request scope ends. Reconnection
resumes observation; it does not trigger a second run. Keep credentials on the server-side
boundary for private jobs.

Cancel and retry are explicit controls with `{ runId, operationId }`, allowing audit and recovery.
The server may process them asynchronously; read or watch until the requested state appears.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/client` API](/docs/api/client)

- [`apps/docs/examples/jobs/watch-run.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/watch-run.ts)

---

# Deployment
Source: https://relkit.dev/docs/modules/jobs/deployment

Publish the worker build together with the task and job definitions it will execute. The staged flow is:

> **Before you begin**
>
> First complete the existing app's [deployment installation and
> roles](/docs/modules/deployment/aws) and its selected [provider
> setup](/docs/modules/jobs/providers). Deployment SDKs stay in development tooling; native worker
> runtime SDKs stay in the selected production closure.

1. Provision host resources and network/IAM prerequisites.
2. Resolve secrets without putting values in the plan.
3. Publish the immutable worker build.
4. Register definitions and schedules.
5. Wait for worker readiness.
6. Activate schedules and the new service generation.

Pulumi emits provider-native worker publication and registration operations. Each operation records the task ID, task version, build ID, service generation, runtime, limits, and capability evidence. Provider integrations export their native publication mechanism rather than pretending all providers share one deployment API.

Keep the previous build, signing keys, and registrations until in-flight runs finish or are explicitly migrated. Readiness must pass before activation, and an old generation must not be retired while it owns active runs. Rollback activates the previous compatible generation; it does not rewrite run history.

Cloud deployment is opt-in. The local Docker gate proves the selected adapter and its persisted state before
any managed account or infrastructure mutation is authorized.

The commerce example selects a Docker-backed job profile and a separate Pulumi/AWS
deployment role. See the [application configuration](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)
for the complete source.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/pulumi` API](/docs/api/integrations/pulumi)

- [`examples/commerce/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)

---

# Docker providers
Source: https://relkit.dev/docs/modules/jobs/docker

Local job providers can use Docker, but the generator currently accepts only certified creation combinations. The explicit `--jobs` flags below are rejected before staging or installation:

```sh
relkit create my-app --jobs inngest-docker
relkit create my-app --jobs effect-mq-docker
relkit create my-app --jobs trigger-docker
```

For an existing project, install the provider packages and bind the selected provider in
`relkit.config.ts`; do not interpret performance evidence as native-provider certification.
The local CLI also needs `@relkit/local` in the application. Follow the provider-specific setup:
[Inngest](/docs/modules/jobs/providers/inngest), [Effect MQ](/docs/modules/jobs/providers/effect-mq), or
[Trigger.dev](/docs/modules/jobs/providers/trigger).

```sh
relkit local up --detach
relkit local status
relkit local stop
relkit local reset --dry-run
```

`--detach` lets you start the backend in the same terminal afterward. Without it, `local up`
stays attached until interrupted. `local stop` stops services without deleting state.
`local reset` is destructive to local job state; use the dry run first. Run `relkit jobs capabilities`
after the backend starts to inspect the selected provider's limits.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/docker` API](/docs/api/integrations/docker)
- [`@relkit/inngest` API](/docs/api/integrations/inngest)
- [`@relkit/trigger` API](/docs/api/integrations/trigger)
- [`@relkit/effect-mq` API](/docs/api/integrations/effect-mq)

- [`templates/default/v1/tasks/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/tasks/relkit.config.ts)

---

# Durations and sleep
Source: https://relkit.dev/docs/modules/jobs/durations-and-sleep

Pause task execution through the provider's durable sleep capability when the selected provider supports it.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

Set `maxDuration` or `maxElapsed` on the task. Duration values are enforced by the runtime and should be
shorter than the provider's own request timeout.

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

Durable sleep records a continuation with the provider. A durable task calls
`context.sleep("1 hour", { key: "wait-before-notifying" })`; it must not use `setTimeout` in a worker
process because a restart would lose the continuation.

Providers differ. Inngest currently supports durable sleep for its supported path. Effect MQ does not advertise durable sleep. Trigger Docker does not claim checkpointed sleep. Check capabilities before relying on a long pause.

Use UTC for provider-native schedules. A task that needs a local business timezone should calculate the next instant explicitly and persist the business timezone in its input.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)

---

# Execution policy
Source: https://relkit.dev/docs/modules/jobs/execution-policy

Set retry, timeout, concurrency, and cancellation policy on the task that owns the work.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

Execution policy belongs to the task because it describes how the durable operation runs.

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

Use task fields such as `maxDuration`, `maxElapsed`, `resources`, `concurrency`, `logging`, and `retry`.
Jobs keep admission and client exposure together; they do not override task execution policy.

Admission runs before a durable run is accepted. Keep admission checks fast and deterministic. Authorization belongs at the public boundary; the task must still validate every value it trusts from persisted input.

Cancellation is cooperative: the runtime records the requested state and the task should stop between side effects or checkpointable work. Do not delete a run to cancel it. Use the run control API so the provider can retain history and the operation ID can be audited.

The default run-list limit is 25 and the maximum is 100. Provider-specific ceilings are reported by `relkit jobs capabilities`.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)

---

# Inspector
Source: https://relkit.dev/docs/modules/jobs/inspector

Use the Inspector's Jobs area to find runs, inspect progress, and request supported controls.

> **Before you begin**
>
> Complete the separate [Inspector installation, bridge enablement and tool
> launch](/docs/modules/operations/inspector) first, alongside the selected [job provider
> setup](/docs/modules/jobs/providers). The backend's `relkit jobs` CLI remains usable independently
> of this optional tool.

- Definitions: task/job IDs, versions, schema hashes, bindings, and limits.
- Runs: status, attempts, progress, output metadata, errors, and controls.
- Schedules: registered definitions, pause state, next occurrence, and ownership.
- Services: worker generations, provider identity, readiness, and rollout state.

Run lists are bounded: 25 by default and 100 maximum. Filters should be scoped to a service, job, tenant, or time range before loading history.

Controls are asynchronous. A cancel, retry, or schedule write returns an operation ID; keep the operation visible until the Inspector observes the resulting state. The Inspector reports provider capability errors rather than presenting an unsupported control as successful.

Protect the Inspector endpoint. It is an operator surface, not a replacement for application authorization.

The run detail keeps the accepted `runId`, task version, service generation, result availability, progress,
and native diagnostics separate. A disconnected Inspector view never cancels accepted work.

[Inspector job-filter regression test](https://github.com/rel-kit/relkit/blob/main/tests/inspector/job-name-filters.test.ts)

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/client` API](/docs/api/client)

- [`tests/inspector/job-name-filters.test.ts`](https://github.com/rel-kit/relkit/blob/main/tests/inspector/job-name-filters.test.ts)

---

# Migration
Source: https://relkit.dev/docs/modules/jobs/migration

Preserve durable job and task identities when changing application source or provider configuration. Preserve the existing public job ID, task ID, version, input schema, output schema, dedupe scope, schedule identity, and client fingerprint unless the change is intentional.

This is a one-release compatibility window. Legacy function-target definitions, `.enqueue()` producers,
and the deprecated `profile` spelling remain available only when explicitly enabled; new code must use a
task-first definition and `service` selection. Use a compatible release cohort before changing the
application graph; packages have independent versions, so follow the selected owner's installation
requirements rather than assigning one version number to every RELKIT package.

The migration helper is exposed from the jobs package; run it against the previous and next snapshots before
activation. It reports identity, binding, schema, history, schedule, dedupe, and client-fingerprint changes.

```ts title="packages/jobs/tests/migration.test.ts"
import { expect, test } from "vitest";
import { diagnoseJobMigration, diagnoseLegacyCompatibility } from "../src/index.ts";

const base = {
  name: "exportOrders",
  id: "orders.export",
  idSource: "explicit" as const,
  taskId: "orders.export",
  taskVersion: "1",
  inputSchemaHash: "input-v1",
  binding: "implicit" as const,
  publicFingerprint: "client-v1",
  clientFingerprint: "client-v1",
  hasHistoricalRuns: true,
  scheduleIds: ["nightly"],
  dedupeScope: "tenant",
};

test("explains identity, binding, schema, history, and client migration hazards", () => {
  const diagnostics = diagnoseJobMigration(base, {
    ...base,
    name: "exportOrderArchive",
    id: "exportOrderArchive",
    idSource: "name",
    binding: "explicit",
    taskVersion: "2",
    inputSchemaHash: "input-v2",
    publicFingerprint: "client-v2",
    clientFingerprint: "client-v2",
    scheduleIds: ["weekly"],
    dedupeScope: "account",
  });
  expect(diagnostics.map(({ code }) => code)).toEqual([
    "PINNED_JOB_ID_CHANGED",
    "IMPLICIT_TO_EXPLICIT_BINDING",
    "TASK_VERSION_CHANGED",
    "TASK_INPUT_SCHEMA_CHANGED",
    "PUBLIC_CLIENT_FINGERPRINT_CHANGED",
    "DEDUPE_SCOPE_CHANGED",
    "SCHEDULE_TARGET_CHANGED",
    "HISTORICAL_RUNS_PINNED",
  ]);
  expect(diagnostics.every((diagnostic) => diagnostic.message.length > 0)).toBe(true);
});

test("keeps legacy execution explicitly gated and aliases exclusive", () => {
  expect(
    diagnoseLegacyCompatibility({ usesFunctionTarget: true, legacyJobsEnabled: false })[0]?.code,
  ).toBe("LEGACY_JOBS_DISABLED");
  expect(
    diagnoseLegacyCompatibility({
      usesFunctionTarget: true,
      legacyJobsEnabled: true,
      legacyKeys: ["job"],
      newKeys: ["jobs"],
    })[0]?.code,
  ).toBe("LEGACY_ALIAS_CONFLICT");
  expect(
    diagnoseLegacyCompatibility({
      usesFunctionTarget: false,
      legacyJobsEnabled: false,
      legacyKeys: ["defaults.job"],
    })[0]?.code,
  ).toBe("LEGACY_ALIAS_DEPRECATED");
});
```

Diagnostics flag pinned/default-derived ID changes, implicit-to-explicit binding changes, task version or schema incompatibility, history and schedule changes, dedupe changes, and client fingerprint changes. Legacy aliases and function-target definitions must be explicit during the migration window; the compiler does not silently rewrite them.

Roll out a compatible worker first, register the task-first definition, wait for readiness, then activate new triggers. Keep the old definition and worker generation until historical runs are terminal. If the input or output contract is incompatible, use a new task version or a new public job ID and document the boundary.

Provider retention, native listing, durable sleep, schedule recovery, and cancellation limits are variant-specific.
Check the [provider comparison](/docs/modules/jobs/providers) and deployment evidence before relying on them; unsupported
or not-tested capabilities are not emulated by the RELKIT runtime.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/jobs` API](/docs/api/jobs)

- [`packages/jobs/tests/migration.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/migration.test.ts)
- [`apps/docs/examples/jobs/send-receipt.job.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/jobs/send-receipt.job.ts)

---

# Progress and streams
Source: https://relkit.dev/docs/modules/jobs/progress-and-streams

Report bounded progress from a task so callers can follow the run without holding its execution open.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

Progress is an observation channel, not a second source of truth. Define its shape and emit snapshots from
the task:

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

Progress and stream items are limited to 64 KiB. Keep payloads small, include a sequence or cursor when consumers need ordering, and store durable results in the task output or application database.

Streams may be live, durable, or unavailable depending on the binding. A reconnect can observe a gap when retention has expired; reset the UI from the latest run snapshot instead of replaying untrusted client state. Provider capability output is authoritative for the selected environment.

Progress does not authorize a client to read a private run. Apply the same ownership and field-level redaction rules to progress and stream payloads as to the final output.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)

---

# Provider comparison
Source: https://relkit.dev/docs/modules/jobs/providers

Choose a job provider according to the execution and recovery behavior your application needs. The selected binding and deployment environment are authoritative.
In the current fresh-app Orders CSV check, Inngest and Effect MQ both registered and
completed a run. Trigger.dev's local service did not become healthy. The provider guides
show the exact setup and proof checks, including that unresolved outcome. An adapter
capability is not a successful application run.

```ts title="examples/commerce/relkit.config.ts"
jobs: { default: docker(inngest()) },
defaults: {
  bucket: "assets",
  cache: "requests",
  realtime: "default",
  "agent-state": "agents",
  jobs: "default",
},
```

```json title="tests/jobs/compatibility/evidence/capability-matrix.json"
{
  "schemaVersion": 1,
  "recordedAt": "2026-09-20",
  "status": "ready",
  "completionScope": {
    "certified": ["inngest self-hosted Docker", "effect-mq self-hosted PostgreSQL"],
    "deferred": ["Trigger native/Docker evidence", "Pulumi, AWS, and managed-cloud evidence"],
    "diagnostic": "Deferred modes remain not-tested and are not support claims for this change."
  },
  "evidence": [
    "tests/jobs/compatibility/evidence/inngest-native.json",
    "tests/jobs/compatibility/evidence/phase0-1.6-1.10.json",
    "tests/jobs/compatibility/evidence/phase0-1.11.json",
    "tests/jobs/compatibility/evidence/phase0-effect-mq.json",
    "tests/jobs/compatibility/evidence/phase5-adapters.json",
    "tests/jobs/compatibility/evidence/phase9-regressions.json",
    "tests/jobs/compatibility/evidence/phase9-native-completion.json",
    "tests/jobs/compatibility/evidence/phase9-scaffold.json",
    "tests/jobs/compatibility/evidence/phase9-coverage.json"
  ],
  "providerCatalog": [
    { "provider": "inngest", "package": "@relkit/inngest", "recipe": "inngest-docker@2" },
    { "provider": "trigger", "package": "@relkit/trigger", "recipe": "trigger-docker@2" },
    { "provider": "effect-mq", "package": "@relkit/effect-mq", "recipe": "effect-mq-docker@2" }
  ],
  "requiredCommonSubset": {
    "features": [
      "durable acceptance",
      "retryable execution",
      "current-state read",
      "cancel request",
      "native scheduling"
    ],
    "minimumNativeEngines": 2,
    "nativeEnginesProven": ["inngest", "effect-mq"],
    "gate": "ready",
    "diagnostic": "Inngest and effect-mq prove the declared common subset; Trigger has an executable native-shaped adapter and account-free recipe, but provider-native Docker/managed evidence remains not-tested. Inngest local listing and unsupported schedule/version diagnostics remain unchanged."
  },
  "variants": [
    {
      "provider": "inngest",
      "profile": "managed",
      "deployment": "cloud",
      "status": "not-tested",
      "features": {},
      "evidence": []
    },
    {
      "provider": "inngest",
      "profile": "self-hosted",
      "deployment": "docker",
      "status": "passed",
      "features": {
        "durableAcceptance": "native",
        "retryableExecution": "native",
        "durableSleep": "native",
        "currentStateRead": "native",
        "cancelRequest": "native",
        "scheduleCron": "native",
        "scheduleTimezone": "native",
        "scheduleOwnership": "unverified",
        "scheduleDst": "unverified",
        "scheduleOverlap": "unsupported",
        "scheduleMisfire": "unverified",
        "workerVersionTargeting": "unsupported",
        "boundedFilteredListing": "native",
        "historicalBuildResume": "unsupported"
      },
      "evidence": [
        "tests/jobs/compatibility/evidence/inngest-native.json",
        "tests/jobs/compatibility/evidence/phase0-1.6-1.10.json",
        "tests/jobs/compatibility/evidence/phase0-1.11.json"
      ],
      "diagnostics": [
        "The pinned local v2 API proves bounded app/status/function filtering, opaque cursor continuation, event-scoped runs and signing-key authorization without a full scan.",
        "Replacement registration resumed an old run on the new worker build; old-build retirement is explicitly blocked unless the old route and key remain retained.",
        "The pinned server does not expose native ownership listing, so schedule reconciliation remains unverified.",
        "Cron has no portable overlap or misfire control, and DST transition replay is unverified in this SDK/server profile."
      ]
    },
    {
      "provider": "trigger",
      "profile": "managed",
      "deployment": "cloud",
      "status": "not-tested",
      "features": {},
      "evidence": []
    },
    {
      "provider": "trigger",
      "profile": "self-hosted",
      "deployment": "docker",
      "status": "not-tested",
      "features": {},
      "evidence": [
        "tests/jobs/compatibility/evidence/phase0-1.6-1.10.json",
        "tests/jobs/compatibility/evidence/phase5-adapters.json"
      ],
      "diagnostics": [
        "Task registration, scoped subscription cleanup, and schedule declarations have local structural coverage only; this does not certify a Trigger server."
      ]
    },
    {
      "provider": "effect-mq",
      "profile": "managed",
      "deployment": "cloud",
      "status": "unsupported",
      "features": { "durableSleep": "unsupported" },
      "evidence": []
    },
    {
      "provider": "effect-mq",
      "profile": "self-hosted",
      "deployment": "docker",
      "status": "passed",
      "features": {
        "durableAcceptance": "native",
        "retryableExecution": "native",
        "currentStateRead": "native",
        "cancelRequest": "native",
        "nativeScheduling": "native",
        "scheduleOwnership": "native",
        "durableSleep": "unsupported"
      },
      "evidence": [
        "tests/jobs/compatibility/evidence/phase0-1.6-1.10.json",
        "tests/jobs/compatibility/evidence/phase0-effect-mq.json",
        "tests/jobs/compatibility/evidence/phase5-adapters.json"
      ],
      "diagnostics": [
        "LISTEN wake-ups are unavailable under the pinned Effect runtime; native polling fallback was observed and correctness passed.",
        "Durable sleep remains unsupported by the queue/retryable profile."
      ]
    }
  ]
}
```

| Capability             | Inngest            | Trigger.dev        | Effect MQ                               |
| ---------------------- | ------------------ | ------------------ | --------------------------------------- |
| Durable task execution | Native Docker path | Provider-dependent | Not advertised by the retryable profile |
| Retryable execution    | Native Docker path | Provider-dependent | Native PostgreSQL path                  |
| Run reads and controls | Native subset      | Provider-dependent | Native adapter subset                   |
| Durable sleep          | Supported path     | Not claimed        | Unsupported                             |
| UTC cron               | Supported path     | Provider-dependent | Configured path                         |
| Managed cloud evidence | Not tested         | Not tested         | Unsupported                             |

Read the [Inngest](/docs/modules/jobs/providers/inngest), [Trigger.dev](/docs/modules/jobs/providers/trigger), and
[Effect MQ](/docs/modules/jobs/providers/effect-mq) guides before selecting a capability. `relkit jobs capabilities`
reports the binding's actual limits; the compiler rejects a task that requires an unproven capability.

The [evidence matrix](https://github.com/rel-kit/relkit/blob/main/tests/jobs/compatibility/evidence/capability-matrix.json)
keeps unsupported and not-tested variants explicit. Local structural tests do not certify a provider server.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/inngest` API](/docs/api/integrations/inngest)
- [`@relkit/trigger` API](/docs/api/integrations/trigger)
- [`@relkit/effect-mq` API](/docs/api/integrations/effect-mq)

- [`tests/jobs/compatibility/evidence/capability-matrix.json`](https://github.com/rel-kit/relkit/blob/main/tests/jobs/compatibility/evidence/capability-matrix.json)

---

# Provider capability detail
Source: https://relkit.dev/docs/modules/jobs/providers/comparison

Compare the providers' supported capabilities before choosing a job binding. Verify the capabilities of your actual deployment as well as the adapter.

| Capability                         | Inngest        | Trigger.dev            | Effect MQ                       |
| ---------------------------------- | -------------- | ---------------------- | ------------------------------- |
| Task submission and run lookup     | Supported      | Provider-dependent     | Supported by configured adapter |
| Observation and run listing        | Supported      | Provider-dependent     | Supported by configured adapter |
| Retry and cancellation             | Supported path | Provider-dependent     | Retryable queue work            |
| Durable sleep                      | Supported path | Not claimed for Docker | Not advertised                  |
| UTC cron schedules                 | Supported path | Provider-dependent     | Configured provider path        |
| Provider-native worker publication | Inngest SDK    | Trigger SDK            | Effect MQ SDK                   |
| Docker checkpoint resume           | Not a claim    | Not claimed            | Not claimed                     |

Treat “provider-dependent” as an instruction to inspect the generated capability manifest, not as a promise. `relkit jobs capabilities` reports the selected profile, actual limits, and unsupported operations. The compiler should reject a job that requires a capability the binding cannot prove.

---

# Effect MQ
Source: https://relkit.dev/docs/modules/jobs/providers/effect-mq

Use Effect MQ to run RELKIT jobs through a PostgreSQL-backed queue. You will prepare a validated
Orders CSV and inspect the native queue row after submitting it. You need Bun 1.3.10 and a
running Docker daemon. Start where `relkit-effect-mq` does not already exist. This example
returns CSV text; it does not write a file or query the Orders database.

1. ## Configure an existing app

    The `--jobs effect-mq-docker` creation tuple is currently rejected before staging because its native
    and timing evidence is incomplete. Begin with an existing project and install the selected adapter,
    native SDK/ORM, local tooling and application-owned repair before applying the configuration below:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/effect-mq@0.8.3 @relkit/local@0.7.14 drizzle-orm@1.0.0-rc.5-169397b effect-mq@0.7.0
    bun add --dev create-relkit@0.8.8
    ```

    The selected Drizzle version also needs the release's declaration repair. The development-only `create-relkit` package supplies its exact asset; a dependency cannot register Bun patches for its consumer.

    ```sh
    mkdir -p patches
    cp node_modules/create-relkit/dist/patches/drizzle-orm.patch patches/drizzle-orm@1.0.0-rc.5-169397b.patch
    ```

    Merge this entry into the application's existing `patchedDependencies`, preserving other patches. Keep the asset in source control:

    ```json
    {
      "patchedDependencies": {
        "drizzle-orm@1.0.0-rc.5-169397b": "patches/drizzle-orm@1.0.0-rc.5-169397b.patch"
      }
    }
    ```

    Then apply the registered repair before check/typecheck:

    ```sh
    bun install
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The binding in `relkit.config.ts` should match this source.
    `jobs.default` connects to Effect MQ through Docker, while `defaults.jobs` selects it for
    jobs without an explicit profile. In an existing app, complete the installation above and extend
    its config with those two entries, retaining its own ID and server settings.

    Effect MQ also requires an application-owned Drizzle declaration patch before running Bun. This
    repair updates Drizzle's SQL error imports for stable Effect 4 and makes its
    optional PostgreSQL configuration fields compatible with strict declarations. Keep the
    generated `patches/` asset and `package.json` `patchedDependencies` entry together.

    The generated installation instructions above copy and register the exact repair from its owning
    release. Preserve other patch entries, then run `bun install`. Installing `@relkit/effect-mq` alone
    does not apply an application-level repair. Validate manual consumers with `skipLibCheck: false`.

    ```ts title="relkit.config.ts"
    /** Declares task application defaults with inspection disabled until selected. */
    import { defineApp } from "@relkit/app/config";
    import env from "@app/platform/env.js";
    import { docker } from "@relkit/docker";
    import { effectMq } from "@relkit/effect-mq";

    export default defineApp({
      id: "relkit-effect-mq",
      env,
      server: { port: 3000, maxBodyBytes: 1_048_576 },
      telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
      jobs: { default: docker(effectMq()) },
      defaults: { jobs: "default" },
    });
    ```

2. ## Set up the PostgreSQL queue

    `effect-mq-docker` starts PostgreSQL and a RELKIT worker; Effect MQ stores its native queue
    in PostgreSQL rather than exposing a separate provider dashboard. You do not need a cloud
    account. `bun run relkit local up --detach` creates the database credentials, starts the
    containers, and supplies the worker connection. Keep those generated credentials in local
    state. The config above binds RELKIT's `default` jobs profile to that queue.

    The worker must be healthy before you trigger the job. `bun run relkit local status` should
    show `provider.job.default: healthy`. If you want to inspect the native store, identify this
    app's PostgreSQL container with the command below; its name ends in `service-postgres`.

    ```sh title="Terminal — relkit-effect-mq"
    docker ps --filter name=service-postgres --format '{{.Names}} {{.ID}}'
    ```

3. ## Add the Orders boundary

    These instructions extend an existing application; they do not create a jobs starter.
    For a grouped minimal app, create `src/services/orders/functions`, `tasks` and `jobs`.
    Add the following boundary and health function. In a compatible flat app, use its
    existing `src/orders/` root consistently instead. If Orders already exists, extend
    its public functions rather than replacing the boundary.

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import exportOrders from "@app/services/orders/jobs/export-orders.job.js";
    import exportOrdersTask from "@app/services/orders/tasks/export-orders.task.js";
    import health from "@app/services/orders/functions/health.function.js";

    export default defineService({
      functions: { health },
      tasks: { exportOrdersTask },
      jobs: { exportOrders },
    });
    ```

    ```ts title="src/services/orders/functions/health.function.ts"
    /** Supplies the orders service with a validated health result independent of job execution. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      id: "orders.health",
      input: z.object({}),
      output: z.object({ ok: z.literal(true) }),
      handler: async () => ({ ok: true as const }),
    });
    ```

    Add `src/services/orders/jobs/export-orders.job.ts` from the maintained task fixture:

    ```ts title="src/services/orders/jobs/export-orders.job.ts"
    /** Registers the export task as a public job exposing trigger, lookup, list and watch with progress/output fields. */
    import { defineJob } from "@relkit/app/jobs";
    import exportOrders from "@app/services/orders/tasks/export-orders.task.js";

    const exportOrdersJob = defineJob({
      id: "orders.export-orders-job",
      name: "exportOrders",
      task: exportOrders,
      client: {
        public: true,
        operations: ["trigger", "get", "list", "watch"],
        fields: ["status", "progress", "output"],
      },
    });

    export default exportOrdersJob;
    ```

    For this provider, set that job's `client.operations` to `["trigger"]` before checking.

    The task file below supplies the job's imported target. Create the sample input file
    when absent. Keep existing durable task/job IDs and bump the task version when
    changing an already deployed contract.

4. ## Read the task before running it

    **Add or update** `src/services/orders/tasks/export-orders.task.ts` with this task. It
    validates each order line, computes cents without floating-point currency arithmetic, and
    returns CSV text with a total. `retryable` matches Effect MQ's execution model. The IDs and
    SKUs here contain no commas or newlines; escape fields before accepting arbitrary text.
    This fresh app keeps version `1`; bump it after a deployed contract change.

    ```ts title="src/services/orders/tasks/export-orders.task.ts"
    import { defineTask } from "@relkit/app/tasks";
    import { z } from "@relkit/app/schema";

    const order = z.object({
      id: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
      unitPriceCents: z.number().int().nonnegative(),
    });

    const exportOrders = defineTask({
      id: "orders.export-orders",
      version: "1",
      execution: "retryable",
      input: z.object({ orders: z.array(order) }),
      output: z.object({ csv: z.string(), orderCount: z.number().int(), totalCents: z.number().int() }),
      handler: async ({ orders }, context) => {
        const lines = ["order_id,sku,quantity,total_cents"];
        let totalCents = 0;
        for (const item of orders) {
          const lineTotal = item.quantity * item.unitPriceCents;
          totalCents += lineTotal;
          lines.push([item.id, item.sku, item.quantity, lineTotal].join(","));
        }
        context.log.info("Orders CSV prepared", { orderCount: orders.length, totalCents });
        return { csv: lines.join("\n") + "\n", orderCount: orders.length, totalCents };
      },
    });

    export default exportOrders;
    ```

    The explicit `src/services/orders/jobs/export-orders.job.ts` exposes `exportOrders` for triggering.
    This profile advertises only the `trigger` client operation; do not assume run listing, watch,
    or progress is available through that job client. The CLI below can inspect the accepted run
    through the backend's Jobs API.

    **Create or update** `examples/export-orders.json` with two order rows. A successful task computes
    `orderCount: 2`, `totalCents: 2100`, and CSV line totals `900` and `1200`.

    ```json title="examples/export-orders.json"
    {
      "orders": [
        { "id": "order-1", "sku": "tea", "quantity": 2, "unitPriceCents": 450 },
        { "id": "order-2", "sku": "mug", "quantity": 1, "unitPriceCents": 1200 }
      ]
    }
    ```

5. ## Start and submit a run

    Check the app, start the PostgreSQL-backed provider, and keep the development server open:

    ```sh title="Terminal — relkit-effect-mq"
    bun run check
    bun run typecheck
    bun run relkit local up --detach
    bun run relkit local status
    bun run dev
    ```

    In another terminal, check registration first: `jobs list` must name `exportOrders`, task
    `orders.export-orders`, and profile `default`. Submit the sample input next. Its accepted
    receipt only proves enqueueing; execution needs a separate native check.

    ```sh title="Second terminal — relkit-effect-mq"
    bun run relkit jobs capabilities
    bun run relkit --json jobs list
    bun run relkit --json jobs trigger --job exportOrders --input-file examples/export-orders.json --operation-id orders-csv-1
    bun run relkit --json jobs runs list --limit 1
    bun run relkit jobs runs get --run-id '<runId>'
    ```

    The list command is the easiest way to see the completed output; replace `<runId>` with the
    exact receipt ID, keeping the quotes because Effect MQ IDs contain shell punctuation. To
    inspect Effect MQ itself, find the local
    PostgreSQL container with `docker ps`, then run the query below with its container ID. A
    completed run must have `state = completed` and an `exit` value containing the CSV result;
    `waiting` proves only that the job was queued.

    ```sh title="Terminal — relkit-effect-mq"
    docker exec <postgres-container-id> psql -U relkit -d relkit -c "select name, state, metadata->>'relkitTaskId' as task_id, exit from effect_mq order by enqueued_at desc limit 1"
    ```

    In a historical flat-layout local-source run, `jobs list` registered `orders.export-orders-job` and the
    PostgreSQL row reached `completed` after one attempt. Its native `exit` contained the CSV
    lines and `totalCents: 2100`; `jobs runs list --limit 1` returned the same completed output.
    The screenshot below is PostgreSQL's actual `psql -H` result for that run. It selects the
    task ID from Effect MQ metadata and the order count and total from its stored exit value;
    it is a database query result. This evidence predates the grouped move and does not certify
    a new grouped creation tuple.

    ![PostgreSQL query of Effect MQ showing the Orders task completed with two orders and 2100 cents](/jobs-effect-mq-completed.png)

    To produce the same focused result yourself, run this query against the container ID found
    above:

    ```sh title="Terminal — relkit-effect-mq"
    docker exec <postgres-container-id> psql -U relkit -d relkit -c "select metadata->>'relkitTaskId' as task_id, state, exit->'value'->>'orderCount' as orders, exit->'value'->>'totalCents' as total_cents from effect_mq order by enqueued_at desc limit 1"
    ```

    The worker must report `ready` at `/_relkit/v1/health/ready`, not merely have a running
    container. An older local recipe left `$POSTGRES_PASSWORD` literal in the worker database
    URL; the current recipe constructs that URL from the generated secret. Effect MQ may still
    log a failed `LISTEN` subscription and fall back to polling; the completed run above was
    observed with that warning present.

    Effect MQ supports retryable execution and provider-native scheduling in its configured path.
    It does **not** advertise durable sleep or a managed-cloud profile. Keep work idempotent so a
    retry cannot duplicate an external effect. See [execution policy](/docs/modules/jobs/execution-policy)
    for retries and [provider comparison](/docs/modules/jobs/providers) for other profiles.

---

# Inngest
Source: https://relkit.dev/docs/modules/jobs/providers/inngest

Use Inngest to give RELKIT tasks a durable execution path. You will prepare an Orders CSV from
validated order rows, submit the job, and confirm both registration and completion. You need
Bun 1.3.10 and a running Docker daemon. Start in a parent directory where `relkit-inngest`
does not already exist. The task returns CSV text; it does not write a file or query a database.

1. ## Configure an existing app

    The `--jobs inngest-docker` creation tuple is currently rejected before staging because its native
    and timing evidence is incomplete. Begin with an existing project and install the selected adapter,
    native SDK and local Docker tooling before applying the configuration below:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/inngest@0.8.3 @relkit/local@0.7.14 inngest@4.20.0
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The `jobs` entry connects the default job service to the Docker-backed Inngest adapter.
    `defaults.jobs` selects that service for the Orders job. Extend the existing config with the two
    jobs entries; keep its current app ID and server settings.

    ```ts title="relkit.config.ts"
    /** Declares task application defaults with inspection disabled until selected. */
    import { defineApp } from "@relkit/app/config";
    import env from "@app/platform/env.js";
    import { docker } from "@relkit/docker";
    import { inngest } from "@relkit/inngest";

    export default defineApp({
      id: "relkit-inngest",
      env,
      server: { port: 3000, maxBodyBytes: 1_048_576 },
      telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
      jobs: { default: docker(inngest()) },
      defaults: { jobs: "default" },
    });
    ```

2. ## Set up Inngest locally

    `inngest-docker` runs Inngest's local server, PostgreSQL, Redis, and a RELKIT worker. You do
    not need an Inngest Cloud account, an API key, or a separate `inngest dev` process for this
    profile. `bun run relkit local up --detach` creates provider credentials and connects the
    worker to the Inngest server. The generated config above is the connection point; do not
    paste the generated signing or event keys into source files. Start the RELKIT backend with
    `bun run dev` after the local services are healthy.

    To find Inngest's dashboard address, inspect the mapped port and open the `127.0.0.1` URL
    for the container ending in `service-inngest`. The host port is allocated dynamically, so
    `8288` is the **container** port, not necessarily the port to enter in your browser.

    ```sh title="Terminal — relkit-inngest"
    docker ps --filter name=service-inngest --format '{{.Names}} {{.Ports}}'
    ```

    In the dashboard, **Functions** must list the Orders export function after the backend
    starts. This historical screenshot records a fresh flat-layout local-source fixture; its
    native registration evidence predates the grouped move and does not certify a new creation tuple.

    ![Inngest local Functions page showing the registered Orders export function](/jobs-inngest-registered.png)

3. ## Add the Orders boundary

    These instructions extend an existing application; they do not create a jobs starter.
    For a grouped minimal app, create `src/services/orders/functions`, `tasks` and `jobs`.
    Add the following boundary and health function. In a compatible flat app, use its
    existing `src/orders/` root consistently instead. If Orders already exists, extend
    its public functions rather than replacing the boundary.

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import exportOrders from "@app/services/orders/jobs/export-orders.job.js";
    import exportOrdersTask from "@app/services/orders/tasks/export-orders.task.js";
    import health from "@app/services/orders/functions/health.function.js";

    export default defineService({
      functions: { health },
      tasks: { exportOrdersTask },
      jobs: { exportOrders },
    });
    ```

    ```ts title="src/services/orders/functions/health.function.ts"
    /** Supplies the orders service with a validated health result independent of job execution. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      id: "orders.health",
      input: z.object({}),
      output: z.object({ ok: z.literal(true) }),
      handler: async () => ({ ok: true as const }),
    });
    ```

    Add `src/services/orders/jobs/export-orders.job.ts` from the maintained task fixture:

    ```ts title="src/services/orders/jobs/export-orders.job.ts"
    /** Registers the export task as a public job exposing trigger, lookup, list and watch with progress/output fields. */
    import { defineJob } from "@relkit/app/jobs";
    import exportOrders from "@app/services/orders/tasks/export-orders.task.js";

    const exportOrdersJob = defineJob({
      id: "orders.export-orders-job",
      name: "exportOrders",
      task: exportOrders,
      client: {
        public: true,
        operations: ["trigger", "get", "list", "watch"],
        fields: ["status", "progress", "output"],
      },
    });

    export default exportOrdersJob;
    ```

    The task file below supplies the job's imported target. Create the sample input file
    when absent. Keep existing durable task/job IDs and bump the task version when
    changing an already deployed contract.

4. ## Read the task before running it

    **Add or update** `src/services/orders/tasks/export-orders.task.ts` with this example. The
    input describes actual order lines; the task calculates each line total and returns CSV text
    plus a reconciled total. It emits progress after each row. The IDs and SKUs in this example
    are simple values without commas or newlines; add CSV escaping before accepting arbitrary
    customer-provided text. Since this is a fresh app and no run has been deployed, the version
    remains `1`. Bump it when changing a deployed task contract.

    ```ts title="src/services/orders/tasks/export-orders.task.ts"
    import { defineTask } from "@relkit/app/tasks";
    import { z } from "@relkit/app/schema";

    const order = z.object({
      id: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
      unitPriceCents: z.number().int().nonnegative(),
    });

    const exportOrders = defineTask({
      id: "orders.export-orders",
      version: "1",
      execution: "durable",
      input: z.object({ orders: z.array(order) }),
      output: z.object({ csv: z.string(), orderCount: z.number().int(), totalCents: z.number().int() }),
      progress: z.object({ completed: z.number().int().nonnegative() }),
      handler: async ({ orders }, context) => {
        const lines = ["order_id,sku,quantity,total_cents"];
        let totalCents = 0;
        for (const [index, item] of orders.entries()) {
          const lineTotal = item.quantity * item.unitPriceCents;
          totalCents += lineTotal;
          lines.push([item.id, item.sku, item.quantity, lineTotal].join(","));
          await context.progress.emit({ completed: index + 1 });
        }
        context.log.info("Orders CSV prepared", { orderCount: orders.length, totalCents });
        return { csv: lines.join("\n") + "\n", orderCount: orders.length, totalCents };
      },
    });

    export default exportOrders;
    ```

    The explicit `src/services/orders/jobs/export-orders.job.ts` names the public `exportOrders` job and
    allows trigger, get, list, and watch operations. The task owns execution; the job controls
    admission and the client-facing operations.

    **Create or update** `examples/export-orders.json` with the following input. The two rows produce
    `orderCount: 2`, `totalCents: 2100`, and CSV lines with totals `900` and `1200`.

    ```json title="examples/export-orders.json"
    {
      "orders": [
        { "id": "order-1", "sku": "tea", "quantity": 2, "unitPriceCents": 450 },
        { "id": "order-2", "sku": "mug", "quantity": 1, "unitPriceCents": 1200 }
      ]
    }
    ```

5. ## Start and submit a run

    Check the app, start Inngest and its local dependencies, then leave the development server
    running. Start the provider **before** the backend so the worker can connect.

    ```sh title="Terminal — relkit-inngest"
    bun run check
    bun run typecheck
    bun run relkit local up --detach
    bun run relkit local status
    bun run dev
    ```

    In a second terminal, first prove that RELKIT registered `exportOrders` with task
    `orders.export-orders` on the `default` profile. Then trigger the job. The trigger response
    is an acceptance receipt, not proof of execution. Copy its `runId` into the final command.

    ```sh title="Second terminal — relkit-inngest"
    bun run relkit jobs capabilities
    bun run relkit --json jobs list
    bun run relkit --json jobs trigger --job exportOrders --input-file examples/export-orders.json --operation-id orders-csv-1
    bun run relkit jobs runs get --run-id <runId>
    ```

    Repeat the read until `run.status` is `completed`. The run moves from the `event:` receipt
    to an Inngest-native run ID. In a local-source check, the worker logged `Orders CSV prepared`
    with `orderCount: 2` and `totalCents: 2100`, and the native run completed. The current
    Inngest run lookup may report `resultAvailability: "void"` even when the task returns CSV;
    use the worker log to verify totals and do not rely on this lookup to download the CSV.
    If the run remains pending, inspect `bun run relkit local status` and the backend terminal.

    Open **Runs** in the same Inngest dashboard. The completed row below is the native run of
    the registered Orders export function from that fresh app, not merely a RELKIT acceptance
    receipt. Match its function name and run ID to your own run when repeating the steps.

    ![Inngest local Runs page showing a completed Orders export run](/jobs-inngest-completed.png)

    The current Inngest path supports UTC cron schedules and durable sleep. Interval schedules,
    arbitrary timezones, overlap policies, and historical-build resume are not established by
    this profile. The documented limits are 1 MiB each for input and output, 64 KiB for a
    progress item, and 100 items for run listing. Check `jobs capabilities` for the selected
    environment before using an optional operation. Continue with [job clients](/docs/modules/jobs/clients)
    to trigger and observe runs from application code.

---

# Trigger.dev
Source: https://relkit.dev/docs/modules/jobs/providers/trigger

Trigger.dev needs a project, environment API key, and published worker generation alongside the RELKIT job binding. This page shows the RELKIT side and the exact
registration checks; it is a compatibility guide, not a passing setup tutorial. For a
verified local run today, use [Inngest](/docs/modules/jobs/providers/inngest) or
[Effect MQ](/docs/modules/jobs/providers/effect-mq).

> **Before you begin**
>
> You need Bun 1.3.10 and Docker. Start where `relkit-trigger` does not already exist. The task
> returns CSV text; it does not write a file or read a database.

## Configure an existing app

The `--jobs trigger-docker` creation tuple is currently rejected before staging because its native
and timing evidence is incomplete. Begin with an existing project and install the selected adapter,
native SDK and Docker materializer before applying the configuration below:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/docker@0.7.13 @relkit/local@0.7.14 @relkit/trigger@0.8.3 @trigger.dev/sdk@4.7.2
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

This aligns declarations with the adapter's current SDK contract. It does not repair the unresolved
provider/server compatibility or publish a worker.

`jobs.default` connects the provider; `defaults.jobs` selects it. Extend the existing config while
retaining its own ID and server settings.

```ts title="relkit.config.ts"
/** Declares task application defaults with inspection disabled until selected. */
import { defineApp } from "@relkit/app/config";
import env from "@app/platform/env.js";
import { docker } from "@relkit/docker";
import { trigger } from "@relkit/trigger";

export default defineApp({
  id: "relkit-trigger",
  env,
  server: { port: 3000, maxBodyBytes: 1_048_576 },
  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
  jobs: { default: docker(trigger()) },
  defaults: { jobs: "default" },
});
```

## What provider setup is missing

Trigger's [official Docker Compose setup](https://trigger.dev/docs/self-hosting/docker)
runs a webapp, database, Redis, and worker supervisor. After bringing that stack up, an
operator creates a project, obtains a development environment API key, configures the SDK
base URL and key, and deploys a worker containing the task before triggering a run. These
are provider-side steps; the RELKIT binding above does not replace them. The generated
`trigger-docker` recipe instead starts a pinned webapp image with PostgreSQL and a RELKIT
worker, generates a random `projectRef` and `secretKey`, and passes them to the SDK. It does
not create those credentials in Trigger.dev or publish a worker generation. Its pinned
webapp also fails its current environment and port configuration. Running the official
Compose stack separately does **not** make this generated RELKIT profile compatible by
itself. The adapter currently imports `@trigger.dev/sdk/v3`; Trigger's
[self-hosting guidance](https://trigger.dev/docs/self-hosting/overview) says 4.5.0 is the
last server release supporting v3 tasks. The server, SDK, task publication, and project
credentials must be aligned together. Do not paste a production Trigger key into the
generated source or assume that `local up` completing means a task is registered there.

## Add the Orders boundary

These instructions extend an existing application; they do not create a jobs starter.
For a grouped minimal app, create `src/services/orders/functions`, `tasks` and `jobs`.
Add the following boundary and health function. In a compatible flat app, use its
existing `src/orders/` root consistently instead. If Orders already exists, extend
its public functions rather than replacing the boundary.

```ts title="src/services/orders/service.ts"
/** Declares the orders service boundary and its public members. */
import { defineService } from "@relkit/app/services";
import exportOrders from "@app/services/orders/jobs/export-orders.job.js";
import exportOrdersTask from "@app/services/orders/tasks/export-orders.task.js";
import health from "@app/services/orders/functions/health.function.js";

export default defineService({
  functions: { health },
  tasks: { exportOrdersTask },
  jobs: { exportOrders },
});
```

```ts title="src/services/orders/functions/health.function.ts"
/** Supplies the orders service with a validated health result independent of job execution. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";

export default defineFunction({
  id: "orders.health",
  input: z.object({}),
  output: z.object({ ok: z.literal(true) }),
  handler: async () => ({ ok: true as const }),
});
```

Add `src/services/orders/jobs/export-orders.job.ts` from the maintained task fixture:

```ts title="src/services/orders/jobs/export-orders.job.ts"
/** Registers the export task as a public job exposing trigger, lookup, list and watch with progress/output fields. */
import { defineJob } from "@relkit/app/jobs";
import exportOrders from "@app/services/orders/tasks/export-orders.task.js";

const exportOrdersJob = defineJob({
  id: "orders.export-orders-job",
  name: "exportOrders",
  task: exportOrders,
  client: {
    public: true,
    operations: ["trigger", "get", "list", "watch"],
    fields: ["status", "progress", "output"],
  },
});

export default exportOrdersJob;
```

For this provider, set that job's `client.operations` to `["trigger"]` before checking.

The task file below supplies the job's imported target. Create the sample input file
when absent. Keep existing durable task/job IDs and bump the task version when
changing an already deployed contract.

## Read the task before running it

**Add or update** `src/services/orders/tasks/export-orders.task.ts` with this task. It
validates order lines and computes CSV text and a total in cents. The `durable` declaration
does not by itself prove checkpoint or resume support. The sample IDs and SKUs contain no
commas or newlines; escape fields for arbitrary text. This new app keeps task version `1`.
The explicit job exposes `exportOrders`; keep one job with this public name.

```ts title="src/services/orders/tasks/export-orders.task.ts"
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";

const order = z.object({
  id: z.string().min(1),
  sku: z.string().min(1),
  quantity: z.number().int().positive(),
  unitPriceCents: z.number().int().nonnegative(),
});

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orders: z.array(order) }),
  output: z.object({ csv: z.string(), orderCount: z.number().int(), totalCents: z.number().int() }),
  handler: async ({ orders }, context) => {
    const lines = ["order_id,sku,quantity,total_cents"];
    let totalCents = 0;
    for (const item of orders) {
      const lineTotal = item.quantity * item.unitPriceCents;
      totalCents += lineTotal;
      lines.push([item.id, item.sku, item.quantity, lineTotal].join(","));
    }
    context.log.info("Orders CSV prepared", { orderCount: orders.length, totalCents });
    return { csv: lines.join("\n") + "\n", orderCount: orders.length, totalCents };
  },
});

export default exportOrders;
```

**Create or update** `examples/export-orders.json` with these two rows. A completed task should
return `orderCount: 2`, `totalCents: 2100`, and CSV line totals `900` and `1200`.

```json title="examples/export-orders.json"
{
  "orders": [
    { "id": "order-1", "sku": "tea", "quantity": 2, "unitPriceCents": 450 },
    { "id": "order-2", "sku": "mug", "quantity": 1, "unitPriceCents": 1200 }
  ]
}
```

## Check the local profile before submitting

The task source can pass RELKIT checks, but these commands are a diagnostic gate. If
`local status` reports an unhealthy provider, stop here; a RELKIT `jobs list` result only
proves that the compiler discovered the job, not that Trigger.dev registered it.

```sh title="Terminal — relkit-trigger"
bun run check
bun run typecheck
bun run relkit local up --detach
bun run relkit local status
docker ps --filter name=service-trigger --format '{{.Names}} {{.Status}} {{.Ports}}'
```

If the Trigger container exits, stop here and inspect its logs. If a future compatibility
fix makes the provider and worker ready, start `bun run dev`, then use `jobs list` to
confirm RELKIT discovered `exportOrders`, then submit the input. An accepted receipt is
only an enqueueing signal. Require **all three** before claiming the integration works:
the task appears in Trigger.dev's project dashboard, its native run reaches `COMPLETED`,
and the run output includes `orderCount: 2` and `totalCents: 2100`.

```sh title="Second terminal — relkit-trigger"
bun run relkit jobs capabilities
bun run relkit --json jobs list
bun run relkit --json jobs trigger --job exportOrders --input-file examples/export-orders.json --operation-id orders-csv-1
bun run relkit jobs runs get --run-id <runId>
```

Replace `<runId>` with the accepted handle only if submission succeeds. Compare it with the
native Trigger.dev run ID and worker logs. No screenshot of a completed native run is shown
here because this profile did not reach that state in a fresh app. A screenshot of
`jobs list`, an accepted receipt, or a healthy Docker container would not prove that the
task was published and executed.

**Current verification limit:** The local-source task passes `check` and `typecheck`, but
the pinned Trigger image requires service environment variables absent from the current
recipe and listens on a different port. Once the image was cached, `local up` briefly
reported healthy while the Trigger container exited. Adding the SDK manually allowed the
RELKIT backend to start during a diagnostic run, but submission returned an unknown outcome
and the worker never became ready. We therefore have **no proof** that this task was
registered with Trigger.dev or executed there. This provider's runtime compatibility remains
**unverified** in the [capability evidence](/docs/modules/jobs/providers). Do not rely on
checkpoint resume, durable sleep, observation, or cancellation until the selected environment
reports and demonstrates them. Keep worker publication and definition registration staged so
an unsuccessful replacement does not remove the active worker generation. Continue with
[provider comparison](/docs/modules/jobs/providers) to choose a profile by verified capability.

---

# Your first durable job
Source: https://relkit.dev/docs/modules/jobs/quickstart

Define an Orders export task, expose it through a job, and follow the run to completion. It is an optional extension after
the [Orders API tutorial](/docs/learn/build-and-run), not a file replacement in your protected
`relkit-orders` app. You need Bun, repository dependencies, and Docker for a live provider run.

## Pre-setup

Use a native task provider in local Docker. Inngest is the starting path here;
[Trigger.dev](/docs/modules/jobs/providers/trigger) and [Effect MQ](/docs/modules/jobs/providers/effect-mq)
also have Docker recipes. Choose one and review its [capabilities](/docs/modules/jobs/providers/comparison).

1. **Install Inngest and local tooling**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/inngest@0.8.3 @relkit/local@0.7.14 inngest@4.20.0
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the jobs profile**

    Merge `jobs` and `defaults.jobs` into your root configuration. Keep your existing ID,
    `env` import and other settings; the example imports the environment contract from `src/platform/env.ts`.

    ```ts title="relkit.config.ts"
    /** Declares task application defaults with inspection disabled until selected. */
    import { defineApp } from "@relkit/app/config";
    import env from "@app/platform/env.js";
    import { docker } from "@relkit/docker";
    import { inngest } from "@relkit/inngest";

    export default defineApp({
      id: "relkit-inngest",
      env,
      server: { port: 3000, maxBodyBytes: 1_048_576 },
      telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
      jobs: { default: docker(inngest()) },
      defaults: { jobs: "default" },
    });
    ```

    Docker supplies the local provider's connection values; there are no new `defineEnv` secrets
    for this recipe. Jobs with `profile: "default"` use this binding. `localJob()` is the older
    function-target provider and is not a substitute for the native task provider used here.

3. **Check and start after registering the task and job**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

    Use `bun run relkit jobs capabilities` to inspect the selected provider, then follow
    [Your first durable job](/docs/modules/jobs/quickstart) to submit and observe a run.

1. ## 1. Define a task

    When adapting this to a separate lean app, first complete [Inngest's selected installation and
    binding](/docs/modules/jobs/providers/inngest). The repository example already declares its native SDK and
    local tooling; copying task/job files does not install them. Provider creation tuples remain unavailable.

    In your own application, with an existing `orders` service and no export task yet, run:

    ```sh title="Terminal — application root"
    bun run relkit add task export-orders --service orders
    ```

    This creates `src/services/orders/tasks/export-orders.task.ts` and registers `exportOrdersTask` in
    the service's task map. Replace its placeholder input, output, and handler with your operation.
    The [task command reference](/docs/api/cli#relkit-add-task-name) lists execution and version options.
    Skip scaffolding when reading the commerce example, which already contains these files.

    A task owns durable execution. This one accepts order IDs, emits progress, and returns CSV text.
    Its helper `exportOrderCsv` lives in the commerce example; if adapting the pattern to your app,
    replace that helper with your own business operation and keep its schemas explicit.

    ```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
    /** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
    import { defineTask } from "@relkit/app/tasks";
    import { z } from "@relkit/app/schema";
    import { exportOrderCsv } from "../helpers/fake-business.js";

    const exportOrders = defineTask({
      id: "orders.export-orders",
      version: "1",
      execution: "durable",
      input: z.object({ orderIds: z.array(z.string()) }),
      output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
      progress: z.object({
        completed: z.number().int().nonnegative(),
        total: z.number().int().positive(),
      }),
      handler: async ({ orderIds }, context) => {
        await context.progress.emit({ completed: 0, total: orderIds.length });
        const csv = exportOrderCsv(orderIds);
        await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
        return { csv, exported: orderIds.length };
      },
    });

    export default exportOrders;
    ```

    The task ID and version are stable compatibility identifiers. Change the version when the input or output contract is intentionally incompatible.

2. ## 2. Expose a job

    In your own app, scaffold the job after creating the task:

    ```sh title="Terminal — application root"
    bun run relkit add job export-orders --service orders \
      --target orders.export-orders-task
    ```

    `--target` is the task's stable ID. This creates `src/services/orders/jobs/export-orders.job.ts`
    and registers the job on the service. Review its provider profile and client policy before
    running it. It does not create the HTTP trigger below. See the
    [job command reference](/docs/api/cli#relkit-add-job-name) for all flags.

    The job gives the task a public name and client policy. The HTTP route below is a separate
    entry point; its handler accepts a run and returns `202`, not the CSV output.

    ```ts title="examples/commerce/src/services/orders/jobs/export-orders.job.ts"
    /** Registers the export task as a public job exposing trigger, get, list and watch with progress/output fields. */
    import { defineJob } from "@relkit/app/jobs";
    import exportOrders from "../tasks/export-orders.task.js";

    const exportOrdersJob = defineJob({
      name: "exportOrders",
      id: "orders.export-orders",
      task: exportOrders,
      client: {
        public: true,
        operations: ["trigger", "get", "list", "watch"],
        fields: ["status", "progress", "output"],
      },
    });

    export default exportOrdersJob;
    ```

    ### Use this job from the frontend

    After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
    this component under the provider. It selects this job's public `exportOrders` name:

    ```tsx title="src/ExportOrders.tsx"
    "use client";

    /** Submits one commerce export and observes the accepted run without replaying an uncertain submission. */
    import { useJobRun, useJobTrigger, useRelkitClient } from "@relkit/client/react";

    /** Keeps the accepted receipt separate from the task's eventual output.
     * @returns One explicit submission button and its receipt, observation, or failure state. */
    export function ExportOrders() {
      const { status } = useRelkitClient();
      const submit = useJobTrigger("exportOrders");
      const run = useJobRun("exportOrders", submit.data ? { runId: submit.data.runId } : {});

      return (
        <section>
          <button
            disabled={status !== "ready" || !submit.isIdle}
            onClick={() => submit.mutate({ input: { orderIds: ["order-1"] } })}
          >
            Export orders
          </button>
          {submit.isPending && <p role="status">Submitting…</p>}
          {submit.isError && (
            <p role="alert">{String(submit.error)}. Check the outcome before submitting again.</p>
          )}
          {submit.data && <p>Run ID: {submit.data.runId}</p>}
          <p role="status">
            Connection: {run.connection}; run: {run.run?.status ?? "not accepted"}
          </p>
        </section>
      );
    }
    ```

    The task determines the `orderIds` input. The job's `client.operations` permits triggering and
    observation, while `client.fields` selects public run data. The returned `runId` is an admission
    receipt; completion and output arrive through the run observer. The example keeps uncertain
    submissions visible instead of automatically sending them again.

    Reference: [`useJobTrigger`](/docs/api/client#usejobtrigger), [`useJobRun`](/docs/api/client#usejobrun).
    Continue with [job clients and recovery](/docs/modules/jobs/clients).

    ### Add a separate HTTP trigger

    ```ts title="examples/commerce/src/routes/orders/export/route.ts"
    /**
     * Accepts an order export through the public orders service and returns its durable
     * run receipt. The service owns the job descriptor; this route owns HTTP transport.
     */
    import { defineRoute } from "@relkit/app/routes";
    import orders from "../../../services/orders/service.js";

    export const POST = defineRoute({
      id: "orders.export",
      handler: async (request) => {
        const input = (await request.json()) as { readonly orderIds: string[] };
        const run = await orders.exportOrders.trigger(input);
        return Response.json(run, { status: 202 });
      },
    });
    ```

    The commerce Orders service exports both the task and job. Its `relkit.config.ts` binds
    `jobs.default` to `docker(inngest())`, so the compiler can check durable capabilities. When
    adapting this to your own app, add a supported job binding before starting a run.

    The generated job owns admission and client operations while
    the task remains the unit of execution and compatibility.

    For the browser side of this declaration, follow the
    [React trigger and run example](/docs/modules/jobs/clients#use-from-react). It uses this job's
    `exportOrders` name and the task's generated input/output types.

3. ## 3. Trigger and observe

    The generated trigger receives `{ input, options }` and returns an accepted `RunHandle`. For example,
    call `client.jobs.exportOrders.trigger({ input: { orderIds }, options: { operationId } })`, then read
    `client.jobs.exportOrders.runs.get({ runId: accepted.runId })`. Keep the accepted `runId` and
    `operationId`; a handle is an admission receipt, not the task output.

    Use [job clients](/docs/modules/jobs/clients) for the complete trigger/watch lifecycle and
    [progress and streams](/docs/modules/jobs/progress-and-streams) for live updates.

4. ## 4. Run locally

    ```sh title="Terminal — examples/commerce"
    bun run check
    bun run typecheck
    bun ../../packages/cli/dist/bin.js local up --detach
    bun ../../packages/cli/dist/bin.js local status
    ```

    Start `bun run dev` after the provider reports ready. In another terminal, submit a run:

    ```sh title="Second terminal — examples/commerce"
    bun ../../packages/cli/dist/bin.js jobs capabilities
    curl -i -X POST http://127.0.0.1:4000/orders/export \
      -H 'content-type: application/json' \
      -d '{"orderIds":["order-1"]}'
    ```

    Expect HTTP `202` and a `RunHandle` with a `runId`; read or watch that ID until completion.
    The local provider is
    selected by the project binding. Use `relkit local reset --dry-run` before clearing local state.

    Run `bun run test` from `examples/commerce` before changing the task. A passing test checks
    application behavior, while the Docker run checks the selected provider.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/schema` API](/docs/api/schema)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)
- [`examples/commerce/src/services/orders/jobs/export-orders.job.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/jobs/export-orders.job.ts)
- [`examples/commerce/src/routes/orders/export/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/export/route.ts)

---

# Retries and idempotency
Source: https://relkit.dev/docs/modules/jobs/retries-and-idempotency

Retry transient failures while using a stable idempotency key to prevent duplicate business work.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

The default retry policy is three attempts with a one-second initial delay, a 30-second maximum delay, factor two, and no jitter.

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

Set `retry` on `defineTask`, using `maxAttempts`, readable `initialDelay` and `maxDelay`, `factor`, and
`jitter`. A job can add an admission idempotency key and retention policy, but it cannot multiply the
task's retry budget.

Retries are at-least-once. Use an idempotency key for every external side effect and store the result before acknowledging the step. A run ID is not an idempotency key: a retry keeps the run identity but may execute the task again.

The dedupe scope is part of compatibility. Changing it can create duplicate work even when the task source is unchanged, so migration diagnostics treat it as a deliberate change.

Classify permanent validation and authorization failures as terminal. Let transient network, rate-limit, and provider failures retry. Never log credentials or full untrusted input while diagnosing a retry loop.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/testing` API](/docs/api/testing)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)
- [`packages/jobs/tests/task-policy.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/task-policy.test.ts)

---

# Schedules
Source: https://relkit.dev/docs/modules/jobs/schedules

Start a job on a schedule by declaring its cron rule and timezone.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

Schedules belong to jobs and use the same task input and admission rules as an on-demand trigger.

```ts title="examples/commerce/src/services/orders/jobs/cleanup-orders.job.ts"
/** Schedules the cleanup task daily at midnight UTC with the established input and skip-misfire policy. */
import { defineJob } from "@relkit/app/jobs";
import cleanupOrders from "../tasks/cleanup-orders.task.js";

const cleanupOrdersJob = defineJob({
  name: "cleanupOrders",
  id: "orders.cleanup",
  task: cleanupOrders,
  schedules: [
    {
      id: "dailyCleanup",
      cron: "0 0 * * *",
      timezone: "UTC",
      input: { before: "30 days ago" },
      misfire: "skip",
    },
  ],
});

export default cleanupOrdersJob;
```

Use `schedules`, an array of definitions with an explicit `id`, canonical `input`, and either a cron/timezone
pair or an interval. Schedule operations return a receipt with an operation ID; they do not pretend that a
provider accepted a write when its outcome is unknown.

Use an explicit job ID and keep schedule ownership in source control. `relkit jobs schedules list|get|upsert|pause|resume|delete` manages the registered definition; each write returns an operation ID that can be audited.

Schedules are provider-backed. Do not run a second process-local scheduler as a fallback: it can double-trigger work after a restart. Check `relkit jobs capabilities` for the selected provider's cron, interval, timezone, overlap, and misfire support. The current Inngest path supports UTC cron schedules; interval and richer misfire policies are not silently emulated.

Pausing a schedule prevents new admissions and does not cancel runs already accepted. Delete or change a schedule only after checking in-flight runs and the migration impact on dedupe keys.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/inngest` API](/docs/api/integrations/inngest)
- [`@relkit/effect-mq` API](/docs/api/integrations/effect-mq)

- [`examples/commerce/src/services/orders/jobs/cleanup-orders.job.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/jobs/cleanup-orders.job.ts)
- [`packages/jobs/tests/schedule-reconciliation.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/schedule-reconciliation.test.ts)

---

# Security
Source: https://relkit.dev/docs/modules/jobs/security

Control who can submit work, read its results, and request job operations.

> **Before you begin**
>
> Use an existing [task/job with its selected provider installed and
> bound](/docs/modules/jobs/quickstart) before running this example. Core task declarations do not
> install the provider's native SDK.

Jobs are private unless their `client` policy sets `public: true` or provides `authorize`. Public means
the selected operations are exposed; it does not disable input validation, admission, authorization, or
output limits.

```ts title="examples/commerce/src/services/orders/jobs/export-orders.job.ts"
/** Registers the export task as a public job exposing trigger, get, list and watch with progress/output fields. */
import { defineJob } from "@relkit/app/jobs";
import exportOrders from "../tasks/export-orders.task.js";

const exportOrdersJob = defineJob({
  name: "exportOrders",
  id: "orders.export-orders",
  task: exportOrders,
  client: {
    public: true,
    operations: ["trigger", "get", "list", "watch"],
    fields: ["status", "progress", "output"],
  },
});

export default exportOrdersJob;
```

- Authorize the caller before triggering, reading, watching, cancelling, or retrying a run.
- Scope every lookup by tenant or account; opaque run IDs are not authorization.
- Validate persisted input again inside the task before side effects.
- Redact secrets and personal data from logs, progress, stream items, and error details.
- Keep provider tokens in secret configuration and expose only their names in deployment plans.
- Treat client fingerprints, task versions, and schema hashes as compatibility metadata, not credentials.

Use the Inspector only on a protected local or operator network. The local admin endpoint must not be exposed publicly without an authenticated proxy.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/jobs/export-orders.job.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/jobs/export-orders.job.ts)

---

# Tasks
Source: https://relkit.dev/docs/modules/jobs/tasks

A task defines the input, result, and behavior of work that a job can run durably.

> **Before you begin**
>
> Install and bind a [compatible job provider](/docs/modules/jobs/quickstart) before scaffolding the
> task. `relkit add task` checks the application, so it needs a configured `jobs` profile and
> `defaults.jobs`. The task command does not configure the provider or install its native SDK.

## Scaffold a task

From the application root, with an existing `orders` service:

```sh
bun run relkit add task export-orders --service orders
```

This creates `src/services/orders/tasks/export-orders.task.ts` with the stable ID
`orders.export-orders-task`, version `1`, and a durable execution model. It registers the
task on the service. Replace the placeholder schemas and handler with your operation; keep
its identity and version stable. Expose it through a
[task-first job](/docs/modules/jobs/quickstart) when callers need admission, run handles, and observation.

For every task scaffolding flag, see the [task command reference](/docs/api/cli#relkit-add-task-name).

## Define the task

A task contains the code and schemas for one durable operation. A task is not a request handler: it may be resumed, retried, observed, or run after the original process exits.

```ts title="examples/commerce/src/services/orders/tasks/export-orders.task.ts"
/** Produces demonstration CSV through the ordinary order helper and emits validated progress around the durable export. */
import { defineTask } from "@relkit/app/tasks";
import { z } from "@relkit/app/schema";
import { exportOrderCsv } from "../helpers/fake-business.js";

const exportOrders = defineTask({
  id: "orders.export-orders",
  version: "1",
  execution: "durable",
  input: z.object({ orderIds: z.array(z.string()) }),
  output: z.object({ csv: z.string(), exported: z.number().int().nonnegative() }),
  progress: z.object({
    completed: z.number().int().nonnegative(),
    total: z.number().int().positive(),
  }),
  handler: async ({ orderIds }, context) => {
    await context.progress.emit({ completed: 0, total: orderIds.length });
    const csv = exportOrderCsv(orderIds);
    await context.progress.emit({ completed: orderIds.length, total: orderIds.length });
    return { csv, exported: orderIds.length };
  },
});

export default exportOrders;
```

Use a stable task ID. The version identifies a compatible task definition, not a deployment build. Schema hashes and the client fingerprint are recorded with each job definition so migration checks can reject accidental contract changes.

Tasks can emit typed progress, return a bounded output, sleep when their provider supports durable sleep, and throw declared errors for retry or terminal failure. Keep business side effects idempotent and put provider-specific code behind the integration boundary. A retryable task does not expose durable sleep.

See [durations and sleep](/docs/modules/jobs/durations-and-sleep), [execution policy](/docs/modules/jobs/execution-policy), and [retries and idempotency](/docs/modules/jobs/retries-and-idempotency).

## Use from the frontend

A task does not become a browser endpoint by itself. Give it a job with a client policy, then use
the [typed job client](/docs/modules/jobs/clients#use-from-react) to trigger and observe it. The task's
schemas determine input and output; the job's policy determines permitted operations and visible fields.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/schema` API](/docs/api/schema)

- [`examples/commerce/src/services/orders/tasks/export-orders.task.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/tasks/export-orders.task.ts)

---

# Testing
Source: https://relkit.dev/docs/modules/jobs/testing

Test tasks with fixed inputs, explicit provider replacements, and controlled time. Assert input/output schemas, retry classification, idempotency, progress limits, and cancellation behavior.

The focused repository suites are `test:jobs:unit`, `test:jobs:types`, `test:jobs:contracts`,
`test:jobs:restart`, `test:jobs:client`, and `test:jobs:inspector`; Docker and native provider suites are
explicitly gated by `test:jobs:docker` and `test:jobs:providers`.

Use provider conformance tests for submission, read, list, observation, cancel, retry, schedules, and durable sleep only when the provider advertises each capability. Test the local rollout path for readiness, rollback, old-build retention, and unsafe retirement.

After the [selected provider installation](/docs/modules/jobs/providers) is complete, application checks and
tests with explicit provider replacements remain local. The generic [test harness](/docs/modules/operations/testing)
does not install native SDKs or start a provider:

```sh
bun run check
bun run typecheck
bun run test
```

Docker lifecycle tests are opt-in. Cloud deployment and acceptance require explicit environment configuration and should not run as part of a normal local test loop.

[Task-wire regression test](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/task-wire.test.ts)

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/testing` API](/docs/api/testing)
- [`@relkit/client` API](/docs/api/client)

- [`packages/jobs/tests/task-wire.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/jobs/tests/task-wire.test.ts)
- [`packages/client/tests/compatibility/jobs-watch.test.ts`](https://github.com/rel-kit/relkit/blob/main/packages/client/tests/compatibility/jobs-watch.test.ts)

---

# Troubleshooting
Source: https://relkit.dev/docs/modules/jobs/troubleshooting

Start with the failing run or command, then check the selected provider's capabilities, registration, and connection.

### Capability or binding errors

> **Before you begin**
>
> Complete the selected [provider installation](/docs/modules/jobs/providers/inngest) first, using
> [Effect MQ](/docs/modules/jobs/providers/effect-mq) or
> [Trigger](/docs/modules/jobs/providers/trigger) when selected instead. The adapter wrapper alone
> does not install a native SDK or register an application patch.

Run `relkit jobs capabilities` and compare the job's requested execution mode with the selected binding. The compiler and deployment plan report the missing capability and the provider's actual limit.

### A run is not progressing

Check worker readiness, service generation, provider health, and the run's last attempt. Do not trigger a duplicate while a run is merely delayed; use the run ID and operation history.

### Watch reconnects or shows a gap

Reload the latest run snapshot, then resume observation. Progress and stream retention are bounded and are not a durable replacement for task output.

### A schedule fires twice

Check for a process-local scheduler, overlapping provider registrations, and a changed dedupe scope. Pause the schedule before removing a registration.

### Deployment rollback is blocked

An old build may still own active runs or a key/registration may still be referenced. Finish or migrate those runs before retiring the generation.

### Trigger is unavailable

Confirm that the backend is running and `jobs list`/`jobs capabilities` identify the selected job and
binding. Resolve missing SDK, binding and provider-readiness diagnostics before retrying. An accepted
CLI receipt proves admission; inspect the native run separately before reporting execution success.

When a trigger response is lost, retain the original `operationId`, idempotency key, and request digest. Show
an unknown outcome and use only the provider-certified recovery action; do not discard the handle or submit a
different payload automatically.

Check the [commerce job binding](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)
against the selected provider when investigating a binding error.

The [task fixture manifest](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/tasks/package.json)
is a repository reference, not an installation recipe. Preserve your own manifest and install only
the packages required by your selected provider.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/jobs` API](/docs/api/jobs)

- [`templates/default/v1/tasks/package.json`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/tasks/package.json)

---

# Operations
Source: https://relkit.dev/docs/modules/operations

Use these pages to test application behavior, inspect running work, diagnose failures, and prepare a deployment. Use local telemetry
and the Inspector while developing, deterministic tests for behavior, a reproducible build before release, and
deployment preview only when cloud infrastructure is intentionally configured.

> **Start here**
>
> Start with [Testing](/docs/modules/operations/testing) to verify an application operation. For a
> terminal walkthrough from a new project to a running build, follow [Create and build an
> API](/guides/cli/create-and-build-an-api). Exact helpers are in the [Testing
> reference](/docs/api/testing).

## Pre-setup

Start with local logging and bounded capture; neither requires a telemetry account, exporter,
new `defineEnv` fields, or a Docker service. Merge these settings into your existing `defineApp`
configuration, retaining its environment contract:

```ts title="relkit.config.ts"
/** Local telemetry works without a remote exporter or extra environment secrets. */
import { defineApp, defineEnv } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({}),
  telemetry: {
    redaction: { mode: "development-redacted", maxBytes: 65_536 },
    localRetention: { maxRecords: 2_000, maxAgeMs: 3_600_000, maxBytes: 16_777_216 },
  },
});
```

Run `bun run check` and `bun run dev`, then send a request to an existing route to produce
correlated logs. For a UI, complete the separate [Inspector setup](/docs/modules/operations/inspector):
installation alone does not enable its bridge. Keep your application's Redis, MinIO, database,
and job providers in [local Docker](/docs/modules/integrations/local-docker).

Remote Sentry/OTLP export is optional. Their integrations have no bundled Docker collector
recipe; configure a reachable service and supply its named endpoint/secret bindings only when
selecting that exporter. Those binding references are distinct from application `context.env` fields.

## Choose the operational task

**[Observability](/docs/modules/operations/observability)**

Configure redaction, local evidence, sampling, Sentry, and OTLP.

**[Inspector](/docs/modules/operations/inspector)**

Follow requests through graph nodes, logs, traces, diagnostics, and API contracts.

**[Testing](/docs/modules/operations/testing)**

Test functions and the in-process application with explicit provider fakes.

**[Deployment](/docs/modules/deployment)**

Verify Docker images and choose supported application hosts and runtime providers.

**[Troubleshooting](/docs/modules/operations/troubleshooting)**

Use stable diagnostics to repair the owning source of truth.

**[CLI](/docs/modules/cli)**

Follow terminal workflows and find command syntax and options.

## Use the generated project commands

The minimal starter exposes the normal application lifecycle as package scripts. This manifest is a
reference for the base app; optional feature guides add only their selected dependencies:

```json title="templates/default/v1/minimal/package.json"
{
  "name": "my-app",
  "private": true,
  "type": "module",
  "packageManager": "bun@1.3.10",
  "scripts": {
    "dev": "relkit dev",
    "check": "relkit check",
    "typecheck": "tsc --noEmit",
    "test": "bun test",
    "test:unit": "bun test tests/unit",
    "test:integration": "bun test tests/integration",
    "build": "relkit build",
    "start": "NODE_ENV=production bun run --no-env-file .relkit/build/server/index.js",
    "graph": "relkit graph print"
  },
  "dependencies": {
    "@relkit/app": "0.8.4",
    "@scalar/hono-api-reference": "0.12.9",
    "effect": "4.0.1"
  },
  "devDependencies": {
    "@types/bun": "1.3.10",
    "@relkit/cli": "0.8.8",
    "@relkit/testing": "0.8.4",
    "typescript": "5.9.3"
  }
}
```

During development, run the narrowest check that proves the change. Before releasing an application, run the
complete local sequence:

```sh title="Terminal — relkit-orders"
bun run check
bun run typecheck
bun run test
bun run build
bun run start
```

Building and starting do not create cloud resources. Deployment is a separate, explicit lifecycle.

## Match the repository gate before pushing

RELKIT contributors can run the same locally reproducible CI coverage before a push:

```sh title="Terminal — relkit repository"
bun run prepush
```

That focused merge gate needs no Docker daemon. Use `bun run prepush:full` with Docker available for
full local acceptance, including container/local-service and browser checks. Dependency review is hosted
CI-only. Real AWS acceptance is separately opt-in locally and is not run by CI; it needs explicit
credentials and authorization for cloud cost.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/testing` API](/docs/api/testing)

- [`templates/default/v1/api/package.json`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/package.json)

---

# Inspector
Source: https://relkit.dev/docs/modules/operations/inspector

import inspectorShell from "../../../../../../tests/e2e/inspector-redesign.spec.ts-snapshots/shell-dark-darwin.png";

The Inspector is an optional tool for browsing your running application's routes, resources, traces, and history. Inspection is optional and disabled by default.
The separate `@relkit/inspector` package owns the UI and diagnostic history. `relkit add inspector`
enables the application bridge and installs that package as a project devDependency; `relkit inspector`
launches it. The tool requires Bun 1.3.10 or newer and Node.js 20.9.0 or newer.
The backend-only development workflow needs no Node.js installation.

`relkit jobs` reads and controls live provider state on the application backend;
it works independently of the inspector UI and application inspection setting.
Selected jobs retain their native authorization and operation IDs. If the backend
sets `RELKIT_INTERNAL_ENDPOINT_TOKEN`, set that same admin token explicitly for
the jobs CLI. Logs, request history and traces belong to the separate inspector.

## Pre-setup

Start from a running local backend. The steps below install the inspector package and enable its
bridge through `defineApp`. No new `defineEnv` values or Docker service are required for the
Inspector itself; retain the backend's environment and local provider configuration.

1. ## Add the inspector

    ```sh title="Terminal — relkit-orders"
    bun run relkit add inspector --project-root .
    ```

    See the [`relkit add inspector` reference](/docs/api/cli#relkit-add-inspector) for its options. This sets `inspector: { enabled: true }` in `relkit.config.ts`, adds `@relkit/inspector` to
    `devDependencies`, installs it, and adds an `inspector` script that runs `relkit inspector`. Nothing is
    installed globally. An authored `inspector.enabled: false` is reported as a conflict, not overwritten.

    To install the tool globally instead, the following command uses this checkout's tool version. Use the compatible published release
    containing the standalone Inspector; a successful local candidate check does not publish it. For an
    unpublished candidate, install its built `.tgz` artifact into an isolated tool environment instead of
    assuming that version is already on the registry. The backend keeps its lean installation.

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    Install the standalone tool with Bun 1.3.10 or newer. Tool installation does not enable application inspection.

    ```sh
    bun add --global @relkit/inspector@0.2.1
    ```

    A global installation needs Bun's global binary directory on `PATH` and does not
    enable inspection. Node is required by the tool's Next UI/history worker, not by the backend-only app.

2. ## Enable the application bridge

    `relkit add inspector` already did this. To enable the bridge by hand, merge the explicit `inspector`
    setting into the existing `relkit.config.ts`, preserving its other options:

    ```ts title="relkit.config.ts"
    /** Explicit development inspection enables the bridge; the standalone UI is launched separately. */
    import { defineApp, defineEnv } from "@relkit/app/config";

    export default defineApp({ env: defineEnv({}), inspector: { enabled: true } });
    ```

    The bridge defaults to `127.0.0.1` with an ephemeral port. Its optional
    `inspector.connection.host` and `inspector.connection.port` settings are separate from the tool's
    UI port, which defaults to 3210. Obsolete `inspector.port` configuration is rejected.

    <img
      src={inspectorShell.src}
      alt="RELKIT Inspector overview with navigation and application summary"
    />

3. ## Follow a request

    ### Start the development runtime

    ```sh title="Terminal — relkit-orders"
    bun run dev
    ```

    Keep the backend running. In a second terminal, launch the project-local tool (`--port` changes the UI port):

    ```sh title="Second terminal — relkit-orders"
    bun run inspector
    ```

    Open `http://127.0.0.1:3210`. The tool discovers and authenticates the
    running session without evaluating application configuration. Stopping it leaves the backend running.

    ### Send an identifiable request

    ```sh title="Terminal — relkit-orders"
    curl -i http://localhost:3000/hello\?name=Inspector \
      -H "x-correlation-id: docs-inspector"
    ```

    ### Inspect the complete path

    In **Requests**, select `/hello` and inspect its route, target function, status, duration, graph hash,
    correlation ID, logs, and trace. Follow the route and function links to their descriptor details.

    ### Compare graph and HTTP contract

    In **Graph**, find the route-to-function edge. The relationship table provides the keyboard and screen-reader
    equivalent of the canvas. Inspect the HTTP contract at
    `http://localhost:3000/_relkit/v1/openapi.json`. New applications select the Scalar
    **API Reference** (`server.apiDocs.ui: "scalar"`) at `http://localhost:3000/_relkit/v1/api-reference`;
    for older applications, follow the [OpenAPI guide](/docs/modules/http/openapi) to install and select it.

## Inspect runtime state

The **Logs** workspace defaults to application and runtime logs at every level from the last 24 hours. Search
redacted messages, components, identifiers, and metadata across retained history. Use **Filter** to narrow by
level, service, function, request, trace, or source; RELKIT lifecycle and Inspector process diagnostics are
available through the source filter.

Select a row to read the full message, structured error, copyable correlation IDs, metadata, and associated trace.
Desktop layouts keep details beside the table; smaller screens open a detail drawer. Arrow keys move between
rows and Escape closes details. Missing or expired records are identified explicitly.

Filters and the selected log are saved in the URL. Live replacement pauses while inspecting a record, scrolling
away from the top, or viewing an older page. **New logs available** returns to the newest results. Backend reloads
and dev restarts preserve committed history within the configured retention limits. History defaults to
`.relkit/observability/observability.duckdb`; use the tool's `--history-directory` for a persistent override.
Package-runner cache removal does not remove project history. The directory accepts one writer and is
bound to one project identity.

Before the tool connects, the bridge retains a bounded redacted buffer, initially 2,048 records/2 MiB.
Overflow, producer delivery failures and interrupted flushing are reported as incomplete capture. The
collector acknowledges a session/sequence only after committing it; replay does not duplicate history.
Later span revisions remain distinct updates. Diagnostic history is separate from durable application data.

Search and detail views cover services, routes, functions, jobs, events, storage, cache, AI, middleware,
integrations, environment contracts, diagnostics, requests, logs, traces, graph relationships, and API contracts.
Provider pages show profile, source kind, integration provenance, local recipe state, and infrastructure roles
without exposing connection values.

The Jobs area keeps task/job definitions, bounded run pages, schedules, and worker services distinct. Run
filters push down stable job/service/status/time identities; unavailable providers are shown as partial rather
than as empty history, and closing the Inspector never cancels accepted work.

Generation views expose the composite activation fingerprint. If a new candidate fails graph, manifest,
integration-plan, local-service, readiness, or override validation, traffic remains on the last known good
generation and the Inspector continues to show that active state.

## Resolve common Inspector problems

**The Inspector is disconnected**

Confirm that the backend is running and inspection is explicitly enabled. With no compatible
live session the tool keeps retrying. With multiple sessions, select a private descriptor
through `--connection-file`. A reload keeps its session; a full dev restart rotates its
credentials.

**History is locked or unavailable**

Stop the other inspector writing the same history directory. Never delete the database to clear
a lock. Resolve permission, disk or worker failures before restarting the tool; automatic
history opening stops after three failures. Existing application data remains outside this
history owner.

**The graph looks stale**

Read the rejected candidate diagnostic. The Inspector intentionally shows the last valid
generation until a replacement passes activation.

**A local integration is waiting**

Inspect its recipe, plan hash, lease, and override generation, then run `bun run relkit local
status` from the same project root.

**Sensitive content is absent**

That is expected. Secret values and protected content are removed before local persistence and
Inspector transport.

Inspection is development-only. Production builds exclude rich inspection regardless of development
configuration or legacy environment overrides. Private descriptors contain session credentials: keep
`.relkit/connections/` private and out of source control. The tool keeps credentials server-side and does
not accept connection paths or network targets from browser requests. Controls retain native application
authorization/operation identity and reject stale generations without blindly retrying mutations.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/inspector` API](/docs/api/inspector)
- [`@relkit/observability-local` API](/docs/api/observability-local)

- [`tests/e2e/inspector-redesign.spec.ts`](https://github.com/rel-kit/relkit/blob/main/tests/e2e/inspector-redesign.spec.ts)

---

# Observability
Source: https://relkit.dev/docs/modules/operations/observability

import inspectorLogs from "../../../../../../tests/e2e/logs.spec.ts-snapshots/logs-workspace-darwin.png";
import inspectorTrace from "../../../../../../tests/e2e/inspector-redesign.spec.ts-snapshots/trace-waterfall-darwin.png";

Follow a request across routes, functions, and resources using RELKIT's correlated logs and traces. Handlers write structured records through `context.log`; functions, providers, jobs, events, tools,
and agents contribute correlated spans without importing a telemetry SDK.

## Pre-setup

Start with local logging and bounded capture; neither requires a telemetry account, exporter,
new `defineEnv` fields, or a Docker service. Merge these settings into your existing `defineApp`
configuration, retaining its environment contract:

```ts title="relkit.config.ts"
/** Local telemetry works without a remote exporter or extra environment secrets. */
import { defineApp, defineEnv } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({}),
  telemetry: {
    redaction: { mode: "development-redacted", maxBytes: 65_536 },
    localRetention: { maxRecords: 2_000, maxAgeMs: 3_600_000, maxBytes: 16_777_216 },
  },
});
```

Run `bun run check` and `bun run dev`, then send a request to an existing route to produce
correlated logs. For a UI, complete the separate [Inspector setup](/docs/modules/operations/inspector):
installation alone does not enable its bridge. Keep your application's Redis, MinIO, database,
and job providers in [local Docker](/docs/modules/integrations/local-docker).

Remote Sentry/OTLP export is optional. Their integrations have no bundled Docker collector
recipe; configure a reachable service and supply its named endpoint/secret bindings only when
selecting that exporter. Those binding references are distinct from application `context.env` fields.

## Configure one pipeline

Core logging and bounded capture need no exporter or Inspector installation. When selecting the
commerce example's exporters, install each chosen owner in the backend first. OTLP uses its own
packaged implementation; Sentry also selects its native Bun SDK:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/otlp@0.7.14
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/sentry@0.8.3 @sentry/bun@10.71.0
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

Use only the chosen exporter entries/imports in your existing configuration. Keeping both entries
below selects both installations; copying telemetry settings never installs their optional packages.

The commerce application combines redacted local capture, bounded retention, export sampling, Sentry, and OTLP:

```ts title="examples/commerce/relkit.config.ts — telemetry"
telemetry: {
  redaction: { mode: "development-redacted", maxBytes: 65_536 },
  localRetention: { maxRecords: 2_000, maxAgeMs: 3_600_000, maxBytes: 16_777_216 },
  exportSampling: { traceRate: 0.25, minimumLogLevel: "info" },
  exporters: {
    errors: sentry({
      dsn: binding.secret("SENTRY_DSN"),
      environment: binding.string("SENTRY_ENVIRONMENT"),
    }),
    traces: otlp({
      endpoint: binding.url("OTLP_ENDPOINT"),
      headers: { authorization: binding.secret("OTLP_AUTHORIZATION") },
      serviceName: "commerce-api",
    }),
  },
},
```

Sentry and OTLP are independent integrations. Their credentials and endpoints use named binding references, so
resolved values do not enter the application graph or Inspector payloads.

## Understand capture order

```text title="Telemetry flow"
runtime event
→ canonical record
→ capture policy
→ redaction
→ bounded retention and live Inspector stream
→ root trace-consistent sampling
→ independent exporters
```

Local capture is independent of external sampling. With `traceRate: 0.25`, the bounded Inspector store can keep
a complete redacted local trace even when that trace is not selected for remote export. Spans, logs, and errors
with the same trace use the same deterministic trace decision. Log export also follows `minimumLogLevel`.
Configure `traceRate: 1` when a Collector performs tail sampling and needs complete failed traces; RELKIT does
not keep a second in-process tail-sampling buffer.

`localRetention` bounds record count, age, and bytes. It is diagnostic evidence, not durable business storage.

Application logging and production telemetry use bounded memory unless a storage capability is explicitly
supplied. They do not install or open DuckDB. Normal console output and external exporters remain usable
without development history. The default memory store keeps at most 1,024 records and 4 MiB of encoded
record payloads; explicit retention settings can lower or change those bounds.

## Read development logs

`bun run dev` prints startup URLs, compilation and reload outcomes, HTTP completions, and application output.
The default terminal level is INFO. Use `bun run dev -- --verbose` for DEBUG events and retained error details,
`--log-level warn` to select an explicit threshold, `--no-color` for plain text, or `--json` for newline-delimited
records on stderr. An explicit level overrides verbose's DEBUG selection. `NO_COLOR` and redirected output also
disable color. Terminal filtering does not reduce captured history.

Persistent development history belongs to the separately installed and launched
[@relkit/inspector tool](/docs/modules/operations/inspector). Complete its install → bridge enablement → tool
startup procedure before using these views. It owns `@relkit/observability-local`, DuckDB and the Node
worker; the backend-only workflow continues to require only Bun.

The tool defaults to `.relkit/observability/observability.duckdb` under its selected project root.
Use the tool's `--history-directory` option for an explicit persistent override. One Inspector writer
owns a history directory, which is bound to one project. Stopping/restarting the tool or reloading the
backend preserves committed history; removing a package-runner cache does not remove project history.

Before collection, an enabled backend bridge holds only a bounded redacted buffer, initially 2,048
records/2 MiB. With no running tool there is no new persisted tool history. Overflow or failed delivery
is reported as incomplete capture; collector receipts acknowledge committed session/sequence records
and deduplicate replay. Backend capture limits and tool history retention are separate budgets.
Exporter delivery remains independent of collector acknowledgments.

The current store uses observability model v2. Moving store ownership preserves existing database schemas,
receipt identities, imported segment markers, and source history files. Incompatible development state is not
reset automatically: RELKIT reports `RELKIT_OBSERVABILITY_STATE_INCOMPATIBLE` and preserves the directory for
diagnosis. Diagnostic history does not own durable job, checkpoint, provider, or agent application state.

If storage fails, application requests continue. The Logs workspace reports degraded storage and failed or
dropped records. Restart the Inspector after fixing the cause; records that failed to commit are not saved.

## Redact before storage or export

`development-redacted` allows bounded invocation and operation input/output capture while replacing protected keys and known secret values.
`maxBytes` is required and prevents oversized content from being retained. Mode `off` omits protected payload
content entirely.

> **UI masking is too late**
>
> Authorization and cookie headers, environment secrets, provider credentials, request bodies,
> prompts, and model results must be removed or redacted before persistence, streaming, or exporter
> queues.

Use synthetic secrets in tests and assert that they do not appear in records, diagnostics, generated artifacts,
or exporter payloads. Redaction is a safety boundary, not permission to log credentials.

## Diagnose exporter health

Exporter fan-out is isolated. A failed Sentry or OTLP exporter cannot block application work or the other
exporter. Failures increment health counters and create redacted local-only diagnostics that are not sent back
through the failed exporter.

Start the app and follow one identifiable request:

```sh title="Terminal — relkit-orders"
bun run dev
curl http://localhost:3000/hello\?name=Telemetry \
  -H "x-correlation-id: docs-telemetry"
```

After the separate [Inspector setup](/docs/modules/operations/inspector), open **Requests**, select `/hello`, and follow its trace, logs, graph hash, generation, and
activation fingerprint. The trace timeline numbers and connects spans and lifecycle events by their recorded
date/time, labels each operation type, and keeps overlapping duration bars visible for concurrent work. Select
a span to open the expanded sheet with separate input, output, outcome, and metadata sections alongside its
resource attributes, events, links, correlated logs,
and safe error details. Event and job continuations remain separate links because they can outlive the HTTP
response. If remote telemetry is silent, inspect exporter health, queue depth, failure count, and drop count
before assuming application capture failed.

## Add application trace detail

RELKIT already creates spans for routes, functions, declared client operations, jobs, events, tools, and agents.
Use `context.trace` only for application work that those boundaries do not describe:

```ts title="examples/commerce/src/services/orders/functions/create-order.function.ts — explicit tracing"
// Dependencies are accessed through the checked execution context.
const unitPrice = await context.trace.span(
  "pricing.calculate",
  { attributes: { "pricing.strategy": "catalog" } },
  () => context.cache.prices.getOrSet({ sku: input.sku }, async () => 1_000),
);
context.trace.event("pricing.calculated", { "pricing.unit_cents": unitPrice });
context.trace.setAttributes({ "pricing.quantity": input.quantity });
```

| Operation                                    | What it records                                                      |
| -------------------------------------------- | -------------------------------------------------------------------- |
| `span(name, callback)`                       | An `internal` child span around the callback                         |
| `span(name, { attributes, kind }, callback)` | A child span with initial attributes and kind `internal` or `client` |
| `event(name, attributes?)`                   | A point-in-time event on the active span                             |
| `setAttributes({ key: value })`              | Additional attributes on the active span                             |

The callback passed to `span` runs with a child span as the active span. RELKIT ends it on success or failure and
returns or rethrows the callback result unchanged. The default kind is `internal`; use `client` only for a custom
outbound dependency RELKIT does not already instrument. Nested and parallel callbacks keep the correct parent.

`event` adds a point-in-time event to the active span. `setAttributes` adds facts to that same active span, so a
call directly in a handler annotates the handler's invocation span while a call inside `span` annotates the child.
There is no manual start or end API.

Attribute values are limited to strings, finite numbers, and booleans. Names beginning with `relkit.` and identity
keys such as `traceId`, `spanId`, and `requestId` are reserved for the runtime. Recording is bounded; Inspector
reports dropped or truncated data instead of implying that omitted telemetry was observed. Do not put secrets,
payloads, or high-cardinality values such as random IDs into attributes.

## Inspect a trace and its logs

The trace view keeps nesting and overlapping work visible. Open a span to inspect its attributes, events, links,
correlated logs, captured redacted input/output, outcome, and safe error details.

<img
  src={inspectorTrace.src}
  alt="RELKIT Inspector trace waterfall showing the nested HTTP request, function, and cache spans"
/>

The Logs workspace preserves structured fields and correlation identities. Selecting a record keeps its associated
trace beside it so developers and operations teams can move from a symptom to the surrounding execution.

<img
  src={inspectorLogs.src}
  alt="RELKIT Inspector Logs workspace with a selected structured log and its associated trace"
/>

AWS hosting routes redacted structured stdout to CloudWatch through the host integration. CloudWatch is host
logging, not an application exporter, so it does not belong under `telemetry.exporters`.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/otlp` API](/docs/api/integrations/otlp)
- [`@relkit/sentry` API](/docs/api/integrations/sentry)

- [`templates/default/v1/api/src/services/hello/functions/hello.function.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/src/services/hello/functions/hello.function.ts)

---

# Realtime, agents, and streaming
Source: https://relkit.dev/docs/modules/operations/realtime-agents-streaming

Keep health checks and controls responsive while clients observe long-running jobs, agents, or streams. Observation
does not consume finite function concurrency. A run remains bound to its original generation;
another generation may serve compatible journal reads and persist controls for the owner, but cannot
migrate execution or continuation. Forced retirement reports `GENERATION_UNAVAILABLE` without replay.

> **Before you begin**
>
> Apply this operational guidance after [realtime provider
> installation](/docs/modules/realtime/providers), the selected [native agent
> setup](/guides/ai/build-an-offline-agent), and [frontend installation](/docs/modules/client).
> Selecting a channel does not select a model engine, and frontend installation does not install
> backend providers.

Deploy frontend and backend public-contract changes together. Even an additive public change blocks
an older browser under exact fingerprint matching. Show an application-updated state, preserve
unknown-operation metadata, and do not auto-reload while a mutation or control is unresolved.

Tune aggregate connection, partition, retained-byte, run, thread, and control limits before public
exposure. Per-principal overload is 429; application/provider overload is 503. Redis-backed guarantees
depend on persistence configuration, and provider resets must advance the provider epoch.

---

# Testing
Source: https://relkit.dev/docs/modules/operations/testing

Choose the test boundary that proves the behavior: a function, an application, or a running HTTP server. Function tests exercise one descriptor without a server.
Application tests load checked configuration and call an in-process HTTP client. Neither layer needs remote
credentials when provider-backed capabilities receive explicit fakes. Use a running backend for final
HTTP middleware, origin, cookie, and transport behavior.

## Install the selected test tooling

The minimal starter already has development-only `@relkit/testing`. In another existing app, install
it explicitly before copying these tests:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add --dev @relkit/testing@0.8.4
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

The generic harness installs no optional database, authentication or model SDK. Keep feature adapters
and native SDKs in the application's selected runtime dependencies. Use `@relkit/testing/drizzle`
for database tests, `@relkit/testing/better-auth` for database-backed auth, and native agent helpers
from `@relkit/langchain` or `@relkit/langchain/testing` after [agent setup](/guides/ai/build-an-offline-agent).

## Test one function

Use `invokeFunction` for input and output validation, declared errors, nested invocation, and handler behavior:

```ts title="templates/default/v1/api/tests/unit/orders.function.test.ts"
/** Checks orders.function through the supported public RELKIT APIs. */
import { expect, test } from "bun:test";
import { invokeFunction } from "@relkit/testing";
import orders from "@app/services/orders/service.js";

test("createOrder invokes pricing", async () => {
  const result = await invokeFunction(orders.createOrder, {
    orderId: "order-1",
    sku: "book",
    quantity: 3,
  });

  expect(result).toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
});
```

```sh title="Terminal — relkit-orders"
bun test tests/unit/orders.function.test.ts
```

Pass test clients when the function declares cache, bucket, job, or event capabilities. Agent tests should
declare or inject a deterministic native LangChain model and inspect recorded effects instead of sleeping or
calling a live service.

## Test the application boundary

Use `createTestApplication` for discovered routes, mapped input, function invocation, and provider
wiring. The [Orders tutorial test](/docs/learn/test-orders) also migrates isolated SQLite and checks
two users' ownership boundary. The starter's smallest HTTP test is:

```ts title="templates/default/v1/api/tests/integration/orders.route.test.ts"
import { afterAll, expect, test } from "bun:test";
import { createTestApplication } from "@relkit/testing";
import config from "../../relkit.config.js";

const testApp = await createTestApplication(config, { resourceProviders: "fake" });

test("POST /orders", async () => {
  const response = await testApp.http.request("/orders", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ orderId: "order-1", sku: "book", quantity: 3 }),
  });
  expect(response.status).toBe(201);
  expect(await response.json()).toEqual({
    orderId: "order-1",
    sku: "book",
    totalCents: 300,
  });
});

afterAll(() => testApp.close());
```

The harness runs in process and exposes `application.http`. It maps invalid function input to a
validation `422`, but it does not implement the entire production HTTP pipeline. It does not prove
all middleware, rate limits, OpenAPI behavior, or RPC transport. Close it in `afterAll` so runtime
state and handles do not leak into another test, then send representative requests to the running
backend as the Start journey does.

## Replace provider profiles explicitly

The commerce suite shows the complete shape for cache, bucket, realtime, and agent-state profiles alongside
native model execution:

[Complete commerce HTTP test](https://github.com/rel-kit/relkit/blob/main/examples/commerce/tests/http.test.ts)

Every graph-required capability and profile must have a replacement. `RELKIT_ENV=test` does not silently select
fakes. Use `createTestCacheFake` and `createTestBucketFake` for deterministic resource behavior, and dedicated
test event, job, or agent utilities for those contracts.

## Run the application gate

```sh title="Terminal — relkit-orders"
bun run test
bun run check
bun run typecheck
bun run build
```

Keep live integration and cloud tests separate and opt-in. In the RELKIT repository, `bun run prepush`
runs the focused merge-blocking checks without Docker; `bun run prepush:full` includes Docker acceptance.

Task-first jobs add focused unit, type, contract, restart, client, Inspector, Docker, and provider suites.
The Docker/provider commands are explicit gates; managed cloud acceptance remains separately authorized.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/testing` API](/docs/api/testing)

- [`templates/default/v1/api/tests/integration/orders.route.test.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/tests/integration/orders.route.test.ts)

---

# Troubleshooting
Source: https://relkit.dev/docs/modules/operations/troubleshooting

Begin with the first failing command and its diagnostic code and source location. Do not delete or hand-edit
`.relkit/generated` or `.relkit/build` to hide a failure; they are evidence produced from authored source,
configuration, and environment.

## Collect structured diagnostics

```sh title="Terminal — relkit-orders"
bun run relkit --version
bun run relkit --help
bun run relkit --json doctor
bun run relkit --json check
```

`--json` is a global option and appears before the command. `check` also writes
`.relkit/generated/diagnostics.json` with stable codes, severity, source locations, descriptor IDs, and suggested
repairs. Review output before sharing it; external tools can still print values RELKIT did not create.

## Diagnose the owning layer

| Symptom                            | Inspect                                                 | Repair                                                                                                                      |
| ---------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| CLI rejects a flag                 | `relkit <command> --help`                               | Use the contextual option and place global flags first.                                                                     |
| Graph will not compile             | `relkit --json check`                                   | Fix the first source-located configuration, identity, target, route, or schema diagnostic.                                  |
| Environment is incomplete          | `relkit env check` and `relkit env explain NAME`        | Supply the declared value; do not add a hidden runtime branch.                                                              |
| Local integration will not start   | `relkit local status` and Docker health                 | Repair the recipe or use `dev --local=off` with connected values.                                                           |
| A new generation will not activate | Candidate diagnostic and readiness                      | Fix graph, manifest, integration, or readiness state; the last valid generation remains active.                             |
| A prepared start falls back        | `relkit --json check` and `relkit dev --prepare`        | Repair stale inputs or an ineligible dynamic configuration; fallback keeps the full safe check.                             |
| Route is unavailable               | `/_relkit/v1/health/live` and the route URL             | Confirm the active project, port, method, and route-to-function edge.                                                       |
| Inspector is stale or absent       | Standalone tool status and private connection selection | Complete [tool install, bridge enablement and launch](/docs/modules/operations/inspector); distinguish UI and bridge ports. |
| Build will not start               | `bun run build` and manifest/hash diagnostic            | Start only the current unedited build output.                                                                               |
| Deployment preview fails           | `relkit --json doctor --pulumi` and preview             | Fix the first Pulumi, backend, role, integration, or environment diagnostic.                                                |
| Test is flaky                      | The smallest test file                                  | Use deterministic fakes and explicit completion; remove arbitrary sleeps.                                                   |

## Verify from narrow to broad

Selected integration diagnostics include `RELKIT_DEPENDENCY_ADAPTER_MISSING`,
`RELKIT_DEPENDENCY_MISSING` and `RELKIT_DEPENDENCY_VERSION_UNSUPPORTED`. Use the diagnostic's
package, supported range and install command from the application root; keep its runtime/development
section and selected repairs. An incompatible authored declaration may instead produce
`RELKIT_ADD_COLLISION`; resolve it deliberately rather than overwriting the manifest or copying an
entire example's dependencies. Reinstall after patch/override changes, then rerun check/typecheck.
These checks report missing packages; they never download SDKs implicitly.

Rerun the command that failed, then expand only as far as the change requires:

```sh title="Terminal — relkit-orders"
bun run test
bun run check
bun run typecheck
bun run build
bun run start
```

For a graph mismatch, run `bun run relkit graph check --hash <expected-hash>` after `check`. For local-service
state, stop the owning process before using `local reset --yes`; reset removes this project's containers,
volumes, and local override state. Deployment state is separate and must be managed through its Pulumi stack.

## Ask for help safely

Include the exact command, exit code, diagnostic code, project-relative source location, Bun version, and whether
the failure occurred in development, tests, build, or deployment. Do not share `.env`, credentials, Pulumi state,
or unreviewed external-tool output.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/testing` API](/docs/api/testing)

- [`templates/default/v1/api/package.json`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/api/package.json)

---

# Realtime channels
Source: https://relkit.dev/docs/modules/realtime

A realtime channel sends live application updates to clients that are currently connected. An order-status change, a new announcement, or a dashboard invalidation are good channel events.

> **Start here**
>
> Start with [provider setup](/docs/modules/realtime/providers), then follow the announcement
> example below and [connect a React subscriber](/docs/modules/realtime/react). The [Realtime
> reference](/docs/api/realtime) lists channel declarations and operations.

The channel is not your database. Load the current state from an ordinary route, then use channel events to update or invalidate that state. This distinction makes refresh and reconnect behavior predictable: the route restores the truth, while the channel keeps the page current.

## Pre-setup

Use Redis in local Docker for replay, fanout, and presence. Start from an existing RELKIT app and a running Docker daemon.

1. **Install Redis and Docker support**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the default realtime profile**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Channels use Docker Redis by default during local development. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { redisRealtime } from "@relkit/redis";

    export default defineApp({
      env: defineEnv({}),
      realtime: docker(redisRealtime()),
      defaults: { realtime: "default" },
    });
    ```

    Channels without `profile` use `default`. Docker supplies Redis's connection values, so there
    are no additional application environment fields. Agent checkpoints need the separate
    [agent-state configuration](/docs/modules/ai#pre-setup).

3. **Check and start after declaring a channel**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

## Realtime channels or application events?

RELKIT has two event-shaped features with different jobs:

| Use                                            | Choose                                       | Why                                                     |
| ---------------------------------------------- | -------------------------------------------- | ------------------------------------------------------- |
| Notify browsers that are viewing a resource    | Realtime channel                             | It supports scoped subscriptions, replay, and presence. |
| Run backend work after something happens       | [Application event](/docs/modules/events)    | It delivers work to server-side consumers.              |
| Return a sequence to the caller of one request | [Typed stream](/docs/modules/http/streaming) | Its lifetime belongs to that request.                   |

A function may publish both an application event and a channel update when both outcomes are needed. Neither mechanism replaces the other.

Use a [job watch](/docs/modules/jobs/clients) for one accepted durable run. Realtime channels remain application
notifications and do not become a substitute for task output, run status, or provider-backed recovery.

## The Realtime API

| API                     | What you use it for                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `defineChannel()`       | Declare partition parameters, event payloads, browser access, replay, and presence. |
| `channel.trigger()`     | Append one validated event from backend code.                                       |
| `channel.getPresence()` | Read declared presence without joining the channel or changing its leases.          |
| `useChannel()`          | Observe one typed channel partition from React.                                     |
| `useRealtime()`         | Manage subscriptions directly when a hook per channel is not convenient.            |

1. ## Declare a channel

    > **Before you begin**
    >
    > Before running this declaration in your own lean app, complete [provider installation and
    > binding](/docs/modules/realtime/providers). For a browser consumer, also complete [frontend client
    > setup](/docs/modules/client) in its own package.

    This public announcements channel has one partition because its parameter schema is empty. It retains recent events for brief reconnects.

    ```ts title="examples/commerce/src/services/announcements/channels/announcements.channel.ts"
    /** Declares public posted-announcement events with five-minute replay retention and a thousand-event limit. */
    import { defineChannel } from "@relkit/app/realtime";
    import { z } from "@relkit/app/schema";

    const announcements = defineChannel({
      id: "announcements.feed",
      params: z.object({}),
      events: { posted: z.object({ message: z.string(), postedAt: z.string() }) },
      client: { public: true },
      replay: { retentionMs: 300_000, maxEvents: 1_000 },
    });

    export default announcements;
    ```

    ### Subscribe from the frontend

    After [frontend setup and pulling the commerce contract](/guides/frontend/connect-react), render
    this component under the provider. It subscribes to this declaration's `announcements.feed` channel:

    ```tsx title="src/Announcements.tsx"
    "use client";

    /** Combines the commerce announcement query with channel invalidation and reconnect recovery. */
    import { useChannel, useRoute } from "@relkit/client/react";

    /** Restores authoritative messages on publication, catch-up, and replay gaps.
     * @returns The current messages with query failure and channel status feedback. */
    export function Announcements() {
      const messages = useRoute("GET /announcements", { input: {} });
      const channel = useChannel("announcements.feed", {
        params: {},
        on: {
          posted: () => {
            void messages.refetch();
          },
        },
        onCaughtUp: async () => {
          await messages.refetch();
        },
        onGap: async () => {
          await messages.refetch();
        },
      });

      if (messages.isError) return <p role="alert">{messages.error.message}</p>;
      return (
        <section>
          <p role="status">Channel: {channel.status}</p>
          {messages.isPending && <p>Loading messages…</p>}
          <ul>
            {messages.data?.messages.map((message, index) => (
              <li key={index}>{message}</li>
            ))}
          </ul>
        </section>
      );
    }
    ```

    `params: {}` selects the channel's empty partition schema. `posted` is a declared event, so its
    callback is checked against the event map. The route query restores the authoritative messages
    after updates, catch-up, or replay gaps. Backend `trigger()` publishes; the browser subscribes.

    Reference: [`useChannel`](/docs/api/client#usechannel), [`useRealtime`](/docs/api/client#userealtime).
    Continue with [subscription and recovery](/docs/modules/realtime/react).

    The declaration controls both publication and generated client types:

    | Option     | Meaning                                                                           |
    | ---------- | --------------------------------------------------------------------------------- |
    | `id`       | Stable channel name used by backend and generated clients.                        |
    | `params`   | Schema that identifies a partition, such as one `orderId`.                        |
    | `events`   | Map of event names to their payload schemas.                                      |
    | `client`   | Omit for backend-only use, set `public: true`, or provide an authorization guard. |
    | `replay`   | Optional retention window and maximum event count for reconnects.                 |
    | `presence` | Optional connection count or protected member projection.                         |
    | `profile`  | Provider profile; otherwise the application default is used.                      |

    An empty `events` map is valid only for a presence-only channel. Event binding is never an access-control boundary; browser access always comes from `client`.

    This declaration generates the browser selector `announcements.feed`. The
    [frontend subscriber example](/docs/modules/realtime/react#subscribe-to-a-channel) shows its typed
    `posted` callback, authoritative route query, and reconnect recovery.

2. ## Publish an update

    Call `trigger()` from backend code after the application change succeeds:

    ```ts title="examples/commerce/src/services/announcements/functions/post-announcement.function.ts"
    /** Inserts a validated announcement, removes older demo rows and publishes its posted event before acknowledgement. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import announcements from "../channels/announcements.channel.js";

    const postAnnouncement = defineFunction({
      input: z.object({ message: z.string().min(1) }),
      output: z.object({ accepted: z.literal(true) }),
      handler: async ({ message }, context) => {
        await context.database.announcements.insert({
          data: { message, createdAt: new Date().toISOString() },
        });
        const stale = await context.database.announcements.findMany({
          orderBy: { field: "id", direction: "desc" },
          limit: 1_000,
          offset: 50,
        });
        for (const { id } of stale) {
          await context.database.announcements.delete({ where: { id } });
        }
        await announcements.trigger({}, "posted", { message, postedAt: new Date().toISOString() });
        return { accepted: true as const };
      },
    });

    export default postAnnouncement;
    ```

    RELKIT validates the partition parameters and payload before appending the event. The returned receipt contains the event ID, checkpoint, provider profile and epoch, and whether an idempotent request was a duplicate.

    `accepted: true` means the provider stored the append and its receipt atomically. It does not mean every subscriber received the event. A subscriber can disconnect immediately after the append and recover according to the channel's replay policy.

    For a retryable publish, pass an `idempotencyKey` created by RELKIT. Reusing the same UUIDv7 key with the same channel, partition, event, and payload during the 24-hour receipt window returns the original receipt. Reusing it for different content fails. Without a key, retrying after a lost response may append the event twice; RELKIT never retries it automatically.

    If a database update and publication must succeed together, write an outbox entry in the same database transaction and publish from the outbox. Calling `trigger()` after a database write does not make the two operations atomic.

3. ## Run the backend example offline

    The snippets above belong to the repository's `examples/commerce` app. From the repository
    root, with dependencies installed, run its focused HTTP test:

    ```sh title="Terminal — RELKIT repository root"
    bun test examples/commerce/tests/http.test.ts
    ```

    The test creates an application with an isolated local realtime provider, posts announcements
    through the public HTTP route, and reads them back. Expect two passing tests; no Docker or
    frontend is needed for this check. A passing test proves the function can append its channel
    event, but does not prove browser delivery or reconnect behavior. The
    [React guide](/docs/modules/realtime/react) connects a browser after this backend path works, and
    [Providers](/docs/modules/realtime/providers) explains the local Redis setup for a live server.

## Choose the next step

[Access and revocation](/docs/modules/realtime/access) explains internal, public, and protected
channels.

[React channels](/docs/modules/realtime/react) connects generated channel types to application
state.

[Replay and recovery](/docs/modules/realtime/recovery) defines mount, reconnect, refresh, and
gap behavior.

[Presence](/docs/modules/realtime/presence) adds connection or member awareness.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/announcements/channels/announcements.channel.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/announcements/channels/announcements.channel.ts)

---

# Access and revocation
Source: https://relkit.dev/docs/modules/realtime/access

Authorize each realtime channel subscription on the server before sending application data.

> **Before you begin**
>
> Start with a channel using an explicitly [installed and bound realtime
> provider](/docs/modules/realtime/providers). Browser consumers also need [frontend installation
> and contract pull](/docs/modules/client).

Channel access is decided on the server for each validated partition. A channel ID, its parameters, or a replay checkpoint never grants access by itself.

## Choose an exposure policy

| Declaration                | Who can subscribe                                                             |
| -------------------------- | ----------------------------------------------------------------------------- |
| Omit `client`              | Backend code only. The channel is absent from the generated browser registry. |
| `client: { public: true }` | Any client that can reach the application endpoint.                           |
| `client: { authorize }`    | Only clients whose current trusted server context passes the guard.           |

Use public access only for data you would return from an unauthenticated route. Protected channels are the normal choice for account, tenant, order, and user-specific updates.

The commerce example protects each order partition:

```ts title="examples/commerce/src/services/orders/channels/order-updates.channel.ts"
/** Declares per-order status events with a native auth-context check, bounded replay and count presence. */
import { defineChannel } from "@relkit/app/realtime";
import { z } from "@relkit/app/schema";

const orderUpdates = defineChannel({
  id: "orders.updates",
  params: z.object({ orderId: z.string().min(1) }),
  events: {
    "status.changed": z.object({
      orderId: z.string(),
      status: z.string(),
      totalCents: z.number().int().nonnegative(),
    }),
  },
  client: {
    authorize: async (_params, context) =>
      typeof context === "object" && context !== null && "auth" in context,
  },
  replay: { retentionMs: 300_000, maxEvents: 10_000 },
  presence: "count",
});

export default orderUpdates;
```

The guard receives validated channel parameters and trusted server context. It should answer one question: may this principal observe this partition now? Authentication alone is often insufficient; an order channel should also verify that the principal can read that order in the active tenant.

A missing session, thrown error, timeout, malformed result, or unavailable authorization dependency denies access.

## How authorization stays current

A successful check creates a short authorization grant for the exact application, identity, session, tenant, channel, and partition. Grants last no longer than 60 seconds. RELKIT authorizes again when the client subscribes, reconnects, replays, renews, changes identity or tenant, or crosses a policy or provider epoch.

This prevents an old checkpoint or an already-open connection from extending access indefinitely. A replacement login for the same user also receives a new session epoch, so stale callbacks and buffered private data cannot cross into the new session.

When renewal is denied, RELKIT:

- stops the subscription;
- removes private frames queued under the old grant;
- invalidates its presence lease;
- discards recovery state tied to that grant; and
- refuses old checkpoints on a later subscription.

The client should treat the channel as unavailable until its authoritative route query succeeds under the new identity.

## Browser transport requirements

Cookie-authenticated WebSocket connections require an exact allowed `Origin`; missing, wildcard, `null`, malformed, and disallowed origins are rejected before subscription. Credentialed cross-origin deployments must name allowed origins explicitly. CORS headers do not replace authentication or channel authorization.

State-changing HTTP operations that lead to channel publication still use the route's CSRF protection. A channel guard cannot make an unsafe mutation safe after it has already executed.

## Keep client identity and authority separate

The client provider uses an opaque server-derived identity scope and session epoch to partition cached and realtime state. A manual `identityKey` may add tenant or application partitioning, but it never authorizes access. The server always derives the current principal independently.

On identity or session replacement, the client aborts active subscriptions, clears private RELKIT state, and ignores callbacks from the previous scope.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/channels/order-updates.channel.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/channels/order-updates.channel.ts)

---

# Presence
Source: https://relkit.dev/docs/modules/realtime/presence

Use presence to show who is connected to a channel partition now.

> **Before you begin**
>
> Start with a channel using an explicitly [installed and bound realtime
> provider](/docs/modules/realtime/providers). Browser consumers also need [frontend installation
> and contract pull](/docs/modules/client).

Presence answers who is connected to one channel partition now. It is lease-based and temporary; use your database for durable membership, permissions, or activity history.

## Choose count or member presence

| Declaration                       | Browser result                          | Use it for                                              |
| --------------------------------- | --------------------------------------- | ------------------------------------------------------- |
| No `presence`                     | No presence API                         | Channels that only deliver events.                      |
| `presence: "count"`               | Connection count and freshness metadata | Viewer counts without identity.                         |
| `{ member, resolve, maxMembers }` | Counts plus typed public members        | Collaborative views that need safe display information. |

The protected order channel enables connection counts:

```ts title="examples/commerce/src/services/orders/channels/order-updates.channel.ts"
/** Declares per-order status events with a native auth-context check, bounded replay and count presence. */
import { defineChannel } from "@relkit/app/realtime";
import { z } from "@relkit/app/schema";

const orderUpdates = defineChannel({
  id: "orders.updates",
  params: z.object({ orderId: z.string().min(1) }),
  events: {
    "status.changed": z.object({
      orderId: z.string(),
      status: z.string(),
      totalCents: z.number().int().nonnegative(),
    }),
  },
  client: {
    authorize: async (_params, context) =>
      typeof context === "object" && context !== null && "auth" in context,
  },
  replay: { retentionMs: 300_000, maxEvents: 10_000 },
  presence: "count",
});

export default orderUpdates;
```

Member presence is allowed only on a protected channel. Its `member` schema defines the public information, `resolve(params, context)` derives that information from trusted server context, and `maxMembers` limits the returned list. It does not limit how many connections may join; provider admission limits are separate.

Return only data another authorized member may see. RELKIT adds an opaque, stable, scope-bound member ID and never exposes the raw ID from your authentication provider.

## Read presence in React

Count presence exposes:

| Field         | Meaning                                                            |
| ------------- | ------------------------------------------------------------------ |
| `connections` | Active connection count, or `undefined` before the first snapshot. |
| `status`      | `loading`, `fresh`, `stale`, or `error`.                           |
| `revision`    | Provider revision for the snapshot, when available.                |
| `scope`       | Whether the count covers one process or a shared provider.         |

Member presence adds `memberCount`, `members`, and `membersTruncated`. Each member has `{ id, info }`, where `info` matches the declared member schema.

Several tabs from the same signed-in member count as several connections but one member. When the transport disconnects, the last values remain available with `status: "stale"`; do not present them as a current census.

## Inspect presence from backend code

For a channel that declares presence, call `channel.getPresence(params)`. The return type matches the declaration: count-only channels cannot access member fields, and channels without presence do not have this method.

The read is side-effect free. It does not subscribe, acquire or renew a lease, emit join or leave activity, or change connection and member counts. It uses the same partition authorization and member-list limit as browser observation.

## Understand leases

The client renews its presence lease while the connection remains healthy. A normal unsubscribe releases it; a crashed tab disappears when the lease expires. Access revocation invalidates the lease immediately so presence does not outlive permission to observe the channel.

Presence reloads from a fresh snapshot after reconnect or refresh. A previously cached count is never treated as proof of current occupancy.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/channels/order-updates.channel.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/channels/order-updates.channel.ts)

---

# Realtime providers
Source: https://relkit.dev/docs/modules/realtime/providers

Select a realtime provider to carry channel events between your backend and connected clients. Agent threads use the separate `agent-state` capability, and ordinary caching continues to use `cache`. Configure only the capabilities your application needs.

## Pre-setup

Use Redis in local Docker for replay, fanout, and presence. Start from an existing RELKIT app and a running Docker daemon.

1. **Install Redis and Docker support**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the default realtime profile**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Channels use Docker Redis by default during local development. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { redisRealtime } from "@relkit/redis";

    export default defineApp({
      env: defineEnv({}),
      realtime: docker(redisRealtime()),
      defaults: { realtime: "default" },
    });
    ```

    Channels without `profile` use `default`. Docker supplies Redis's connection values, so there
    are no additional application environment fields. Agent checkpoints need the separate
    [agent-state configuration](/docs/modules/ai#pre-setup).

3. **Check and start after declaring a channel**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

## Choose a provider

| Provider                  | Best fit                                                   | Replay and fanout                                                  | Durability                                 |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------ |
| `docker(redisRealtime())` | Default local development                                  | Pinned Redis recipe with retained streams and presence             | Persistent Docker volume                   |
| `redisRealtime()`         | Connected Redis; multiple application or gateway instances | Redis Streams read independently by every gateway; shared presence | Depends on Redis persistence configuration |
| `localRealtime()`         | Optional one-machine workflow without Docker               | Filesystem-backed retained state with bounded polling              | Local filesystem                           |

The local provider keeps state under `.relkit/state` by default. Its wait loop polls every 250 ms, so another process can make progress even when filesystem notifications are unavailable. Use its `root` option only when the application needs a different state directory.

Redis uses a stream reader per gateway. Do not replace this with one shared consumer group: consumer groups distribute records among gateways, while realtime fanout requires every gateway with interested subscribers to see the event.

## Alternative provider configuration

**Local filesystem**

The minimal app installs no realtime profile automatically. For one-machine filesystem state,
install the local owner, import `localRealtime` and select a matching `defaults.realtime` profile:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/local@0.7.14
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

**Connected Redis**

For a connected Redis provider, select its owner instead and supply the configured Redis connection:

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

From this guide's application/package root, install only its selected requirements:

```sh
bun add @relkit/redis@0.8.3
```

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

Only a Docker-backed Redis selection also needs `@relkit/docker` and a running daemon; use the
[local Redis setup](/guides/caching/cache-product-prices#configure-caching) for that choice. Agent state is a
separate capability; channels alone do not require `@relkit/langchain` or a model SDK.

The commerce application configures distinct Redis-backed realtime, agent-state, and cache capabilities:

```ts title="examples/commerce/relkit.config.ts"
realtime: docker(redisRealtime({ url: binding.secret("REALTIME_REDIS_URL") })),
"agent-state": {
  agents: docker(redisAgentState({ url: binding.secret("AGENT_STATE_REDIS_URL") })),
},
```

`defaults.realtime` selects the profile used by channels that omit `profile`. A channel can name another profile when one application needs different retention, tenancy, or infrastructure boundaries.

## Understand acknowledgements and resets

`trigger()` acknowledges an atomic provider append and receipt, not delivery to browser tabs. Redis durability is only as strong as the selected Redis persistence and replication settings. Document that deployment choice rather than describing every Redis-backed append as durable.

Each provider exposes an epoch. If retained state is lost or replaced, the epoch changes. Old checkpoints then produce a recovery gap, and missing idempotency receipts are reported as state loss rather than permission to retry an uncertain publish automatically.

## Capacity and overload

RELKIT enforces per-record and aggregate limits for encoded event size, retained bytes, active partitions, live connections, subscriptions, presence members, and receipt retention. Per-principal limits return a typed 429 response; application or provider capacity returns a typed 503 response.

Existing unrelated work is not evicted to admit a new partition or event. Tune provider capacity and retention together: longer replay windows consume more storage, while authoritative route recovery makes short windows safe.

## Production checklist

- Use `redisRealtime()` when subscriptions must survive or fan out across application instances.
- Configure Redis persistence and replication to match the acknowledgement guarantee your product needs.
- Monitor provider resets, rejected appends, slow consumers, expired grants, connection counts, and retained bytes.
- Keep WebSocket upgrades and streaming responses enabled through the generated server and proxy path.
- Configure exact browser origins and credentialed CORS explicitly.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/relkit.config.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/relkit.config.ts)

---

# React channels
Source: https://relkit.dev/docs/modules/realtime/react

Subscribe a React component to one channel partition with `useChannel()`. RELKIT shares equivalent subscriptions by channel name and canonical parameters, so multiple components do not create duplicate transport subscriptions.

The component still owns its application state. A channel callback may patch local state, update the TanStack Query cache, or invalidate an ordinary route query.

## Subscribe to a channel

> **Before you begin**
>
> Complete [frontend package installation and contract pull](/docs/modules/client), then configure
> the backend's selected [realtime provider](/docs/modules/realtime/providers). The frontend client
> does not install backend Redis, filesystem profiles or an agent engine.

The [`defineChannel` announcement example](/docs/modules/realtime#declare-a-channel) generates
`announcements.feed`, its empty partition parameters, and the `posted` event. This component combines
that subscription with the authoritative `GET /announcements` query:

```tsx title="src/Announcements.tsx"
"use client";

/** Combines the commerce announcement query with channel invalidation and reconnect recovery. */
import { useChannel, useRoute } from "@relkit/client/react";

/** Restores authoritative messages on publication, catch-up, and replay gaps.
 * @returns The current messages with query failure and channel status feedback. */
export function Announcements() {
  const messages = useRoute("GET /announcements", { input: {} });
  const channel = useChannel("announcements.feed", {
    params: {},
    on: {
      posted: () => {
        void messages.refetch();
      },
    },
    onCaughtUp: async () => {
      await messages.refetch();
    },
    onGap: async () => {
      await messages.refetch();
    },
  });

  if (messages.isError) return <p role="alert">{messages.error.message}</p>;
  return (
    <section>
      <p role="status">Channel: {channel.status}</p>
      {messages.isPending && <p>Loading messages…</p>}
      <ul>
        {messages.data?.messages.map((message, index) => (
          <li key={index}>{message}</li>
        ))}
      </ul>
    </section>
  );
}
```

The generated registry determines the allowed channel names, partition parameters, event names, payloads, and presence result. Misspelled events and invalid payload assumptions fail during type checking.

Render it under the [Frontend guide's provider](/guides/frontend/connect-react) after pulling a
contract containing those operations. See [`useChannel`](/docs/api/client#usechannel) and
[`useRealtime`](/docs/api/client#userealtime) for the exact hook contracts.

## `useChannel()` options

| Option       | Purpose                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `params`     | Selects one validated channel partition.                                                                |
| `on`         | Maps declared event names to typed callbacks. Omitted events are ignored.                               |
| `onCaughtUp` | Runs after RELKIT has attached to the live tail and applied any valid reconnect replay.                 |
| `onGap`      | Restores authoritative state when replay cannot bridge the previous checkpoint. It may be asynchronous. |

The result exposes:

| Field        | Meaning                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `status`     | Transport state: `idle`, `connecting`, `connected`, `stale`, or `error`. |
| `checkpoint` | Last applied provider checkpoint, when one exists.                       |
| `caughtUp`   | Whether live delivery is safe to present after catch-up or gap recovery. |
| `gap`        | The latest recovery reason, when replay could not continue.              |
| `presence`   | Present only when the channel declares count or member presence.         |

`caughtUp` does not mean your database query has loaded. It means RELKIT has completed the subscription handoff. Coordinate it with the loading state of the route query that owns the page's current data.

## Patch or invalidate?

Patch local state when an event carries the complete change and applying it is simple and deterministic. Invalidate the route query when permissions, derived fields, ordering, or server-side calculations could make a local patch incomplete.

`onCaughtUp` is a useful final invalidation point: load the route, attach the channel, then confirm that no update was missed between those operations. `onGap` must perform a full restoration before it resolves.

## Use the lower-level manager

`useRealtime()` exposes the shared connection status and four typed operations:

| Operation                           | Behavior                                                                   |
| ----------------------------------- | -------------------------------------------------------------------------- |
| `subscribe(name, params, listener)` | Starts or joins a shared subscription and returns an unsubscribe function. |
| `bind(...)`                         | Alias of `subscribe()`.                                                    |
| `unsubscribe(stop)`                 | Calls the returned unsubscribe function.                                   |
| `unbind(stop)`                      | Alias of `unsubscribe()`.                                                  |

Prefer `useChannel()` for components because it handles subscription cleanup and exposes catch-up state. Use `useRealtime()` for an application-level adapter or store that already owns its own lifecycle.

## Mount and identity behavior

The hook waits until `RelkitClientProvider` has a compatible contract and resolved identity. `identityKey: null` blocks private restoration while application identity is unknown. Changing identity or session aborts the old subscription and rejects late frames from it.

Unmounting the final listener releases the shared subscription. It does not delete authoritative application data from your QueryClient.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce-web/app/page.tsx`](https://github.com/rel-kit/relkit/blob/main/examples/commerce-web/app/page.tsx)

---

# Replay and recovery
Source: https://relkit.dev/docs/modules/realtime/recovery

Recover a disconnected client by combining current application state with channel updates.

> **Before you begin**
>
> Start with a channel using an explicitly [installed and bound realtime
> provider](/docs/modules/realtime/providers). Browser consumers also need [frontend installation
> and contract pull](/docs/modules/client).

Realtime events describe changes; they do not contain a complete application snapshot. Reliable recovery therefore combines an authoritative route query with a gap-free channel handoff.

## What happens during each lifecycle

| Situation                      | RELKIT behavior                                                                            | Application behavior                                                                    |
| ------------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Fresh mount                    | Creates a live tail fence and reports `caughtUp`; it does not replay all retained history. | Load authoritative state from a route, then use `onCaughtUp` to check or invalidate it. |
| Brief reconnect with replay    | Reauthorizes and consumes records after the last applied checkpoint.                       | Continue applying events.                                                               |
| Brief reconnect without replay | Reports a gap and establishes a new live fence.                                            | Reload authoritative state in `onGap`.                                                  |
| Full page refresh              | Starts from a new live fence; raw callback cursors are not persisted by default.           | Reload authoritative state.                                                             |
| Invalid or expired checkpoint  | Reports a typed gap and refuses the checkpoint.                                            | Replace derived state from its authoritative source.                                    |

A cursor without the state it represents is not recovery. RELKIT does not persist component state merely because it has persisted or observed a channel position.

## Implement gap recovery

Use `onGap` to refetch the route query or load another authoritative snapshot. The callback may be asynchronous, and `caughtUp` remains false until it resolves. This prevents the UI from presenting partially restored state as current.

Common gap reasons include expired retention, a checkpoint from another identity or session, a policy change, a provider reset, or a future or foreign checkpoint. Do not branch into separate repair algorithms unless your product needs different user messaging; refetching the authoritative view is usually enough.

Use `onCaughtUp` for the final revision check after the live tail is attached. This closes the window in which application data may change between the initial route response and subscription establishment.

## Decide what to retain

Add `replay` when clients benefit from applying a short sequence of missed events after a transient disconnect. Set both:

| Option        | Effect                                        |
| ------------- | --------------------------------------------- |
| `retentionMs` | Maximum age of replayable events.             |
| `maxEvents`   | Maximum retained event count for a partition. |

The order-updates channel keeps a bounded five-minute replay window:

```ts title="examples/commerce/src/services/orders/channels/order-updates.channel.ts"
/** Declares per-order status events with a native auth-context check, bounded replay and count presence. */
import { defineChannel } from "@relkit/app/realtime";
import { z } from "@relkit/app/schema";

const orderUpdates = defineChannel({
  id: "orders.updates",
  params: z.object({ orderId: z.string().min(1) }),
  events: {
    "status.changed": z.object({
      orderId: z.string(),
      status: z.string(),
      totalCents: z.number().int().nonnegative(),
    }),
  },
  client: {
    authorize: async (_params, context) =>
      typeof context === "object" && context !== null && "auth" in context,
  },
  replay: { retentionMs: 300_000, maxEvents: 10_000 },
  presence: "count",
});

export default orderUpdates;
```

Retention is bounded by provider and application-wide storage limits. Reaching a limit does not silently evict unrelated unexpired work; the append fails with a typed overload response.

Replay should be an optimization, not the only way to rebuild a page. Keep an authoritative query even when the retention window is generous.

## Delivery guarantees

The journal is the source of truth. Notifications only wake readers. Providers read after the current checkpoint, register their wait, read again, then wait with a bounded polling fallback. An event appended during replay-to-live attachment is therefore delivered from replay or the next live read rather than falling into a handoff gap.

A provider epoch change signals that retained state may have been reset. RELKIT reports the gap instead of claiming that an absent event or receipt never existed.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/realtime` API](/docs/api/realtime)
- [`@relkit/client` API](/docs/api/client)

- [`examples/commerce/src/services/orders/channels/order-updates.channel.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/channels/order-updates.channel.ts)

---

# Services and domains
Source: https://relkit.dev/docs/modules/service

A service groups related application behavior and exposes the operations other parts of the application can call. Start with the part of the product
you are building—orders, receipts, accounts—not with the technology you will use to build it. Give that
area a domain folder, keep its behavior and resources together, and expose its public operations through
one `service.ts`.

> **Start here**
>
> For a working example, start with [Your first service](/docs/modules/service/first-service). Use
> this overview to understand ownership, or open the [`defineService`
> reference](/docs/api/services#defineservice) for its exact options.

## Pre-setup

Start with a [minimal app](/docs/learn/create-an-app) and retain its `defineApp` configuration
and `defineEnv` contract. A plain service needs no provider profile or Docker service. When
adding a database, bucket, cache, job, event, or agent to the domain, complete that capability's
[provider setup](/docs/modules/integrations#pre-setup) first. Local Docker is the default for
capabilities that require an external service; registering a service does not configure them automatically.

## Domain, service, and function

These three terms describe different things:

| Term     | Meaning                                                                              | Example                                                                                     |
| -------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Domain   | A cohesive area of application responsibility, including its private implementation. | `src/services/orders/` owns order creation, pricing, order events, and order-support tools. |
| Service  | The domain's public boundary, assembled in one `service.ts`.                         | `orders.createOrder` and `orders.orderCreated` are selected public members.                 |
| Function | A validated operation that does the work.                                            | `create-order.function.ts` calculates a total and publishes an event.                       |

When we say a service contains tools, agents, caches, tasks, or jobs, we mean they belong to its **domain**.
`defineService` accepts public `functions`, `events`, `tasks`, and `jobs`; it is not a registry of every file
or a container that injects resources. A function remains the immediate execution unit, while a task owns
durable execution.

## The application architecture

```text
relkit.config.ts              application settings and provider bindings
src/
├── platform/                 shared environment and infrastructure support
├── services/
│   ├── orders/               an application domain
│   │   ├── service.ts        public functions, events, tasks, and jobs
│   │   ├── functions/        business operations and event subscribers
│   │   ├── events/           facts this domain publishes
│   │   ├── tools/            model-callable operations
│   │   ├── agents/           bounded model workflows
│   │   └── cache/            domain-owned cached data
│   └── receipts/             another domain, with its own service.ts
│       ├── service.ts
│       ├── functions/
│       ├── tasks/
│       └── jobs/
└── routes/                   URL paths, HTTP methods, and request policy
```

This is an ownership map, not a checklist of folders to create. Start with a service and one useful
function. Add the other directories only when the domain needs those capabilities. `routes` and
`platform` are special layers, not application domains, and do not need a domain `service.ts`.

The compiler discovers exported descriptors, checks their relationships, and produces an application
graph and runtime manifest. The runtime, Inspector, and deployment tooling use that checked model.
Application authors use ordinary TypeScript descriptors; no Effect imports are required.

Existing flat `src/<name>/service.ts` apps remain supported. Scaffolding preserves their detected
layout, while empty projects default to grouped. Keep one boundary shape throughout the app;
`src/services/service.ts` is not an aggregate boundary. See [optional migration](/docs/modules/service/migration).

## Follow an operation through the layers

In the commerce example, an HTTP route selects `orders.createOrder`. The function validates domain input
and reads the Orders price cache. The [event examples](/docs/modules/events) show how a producing service can
publish a fact and a receiving service can own its reaction; [jobs](/docs/modules/jobs) describe durable work.

Each part has a different job:

- The route handles HTTP input and response mapping.
- The service makes selected domain operations available to callers.
- The function owns business behavior and declares the resources it needs.
- The event contract describes what happened; subscriber functions own the reactions.
- Tools and agents reuse domain behavior without relocating it into an AI-specific application layer.

A service does not create an HTTP endpoint automatically. Nor does adding a member grant a user
permission to call it. Transport exposure and authorization remain explicit.

## Read a real public boundary

This is the larger commerce reference, whose resource/provider packages are already selected. For a
lean first app, use [Your first service](/docs/modules/service/first-service); install a capability from its
linked guide before copying that capability's members into your own domain.

```ts title="examples/commerce/src/services/orders/service.ts"
/** Declares the orders service boundary without acquiring native clients. */
import { defineService } from "@relkit/app/services";
import createOrder from "./functions/create-order.function.js";
import deleteOrder from "./functions/delete-order.function.js";
import getOrder from "./functions/get-order.function.js";
import searchOrders from "./functions/search-orders.function.js";
import updateOrder from "./functions/update-order.function.js";
import authorizeOrder from "./functions/authorize-order.function.js";
import streamOrderReport from "./functions/stream-order-report.function.js";
import cleanupOrders from "./jobs/cleanup-orders.job.js";
import exportOrders from "./jobs/export-orders.job.js";
import cleanupOrdersTask from "./tasks/cleanup-orders.task.js";
import exportOrdersTask from "./tasks/export-orders.task.js";

export default defineService({
  functions: {
    createOrder,
    deleteOrder,
    getOrder,
    searchOrders,
    updateOrder,
    authorizeOrder,
    streamOrderReport,
  },
  tasks: { cleanupOrdersTask, exportOrdersTask },
  jobs: { cleanupOrders, exportOrders },
});
```

Notice what is absent: the Orders cache, support agent, tools, and event subscribers. They still belong
to Orders and are discovered from their own files. They are not public service members.

## Choose your next step

Read [what a domain is and when to split one](/docs/modules/service/domains), then use
[where to put your code](/docs/modules/service/organization) as the map for each capability.
For implementation, follow [define a service](/docs/modules/service/define),
[expose it through routes](/docs/modules/service/routes), or the [first-service example](/docs/modules/service/first-service).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/commerce/src/services/orders/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/service.ts)

---

# Constants and prompts
Source: https://relkit.dev/docs/modules/service/context-values

Use `defineConstants` for named JSON values, environment references, or resolver functions.
Use `definePrompt` for nonempty text or an ordered list of text fragments. Both APIs create
immutable descriptors; they do not read the environment or call a model during construction.

## Scaffold shared values

From an installed application's root, with an existing `orders` service, create the values you need:

```sh title="Terminal — application root"
bun run relkit add constants receipt-settings --service orders
bun run relkit add prompt receipt-policy --service orders \
  --text "Summarize the receipt."
```

The commands create `src/services/orders/constants/receipt-settings.constants.ts` and
`src/services/orders/prompts/receipt-policy.prompt.ts`. Constants start with a domain-qualified
key and a `"replace-me"` value; edit that value in source. Repeated `--text` flags preserve
separate prompt segments. Neither artifact becomes a public service member.

Use `--create-service orders` instead of `--service orders` if the service does not exist.
To create both artifacts, create the service with the first command and use `--service orders`
for the second. For manual setup, define the same descriptors in source as shown below.

See the [constants command](/docs/api/cli#relkit-add-constants-name) and
[prompt command](/docs/api/cli#relkit-add-prompt-name) for all flags, then
[use a prompt in an agent](/docs/modules/ai/agents#scaffold-a-reusable-prompt).

## Define shared values

> **Before you begin**
>
> Start with an [existing RELKIT application](/docs/learn/create-an-app), which already has
> `@relkit/app`. Declare these values alongside its service code:

```ts title="src/services/orders/context-values.ts"
/** Declares shared context values and resolves them without starting an HTTP server or model. */
import {
  createApplicationContextResolver,
  defineConstants,
  defineEnv,
  definePrompt,
  env,
} from "@relkit/app";

const environment = defineEnv({ REGION: env.string() });
export const limits = defineConstants(
  { maxItems: 20, region: environment.REGION },
  { id: "orders.constants" },
);
export const supportPrompt = definePrompt(
  ["Answer using the order details.", "Do not invent delivery dates."],
  { id: "support.prompt" },
);

export const contextResolver = createApplicationContextResolver({
  env: { REGION: "eu-west-1" },
  constants: { orders: limits },
  prompts: { support: supportPrompt },
});
```

`limits` declares `maxItems` and a typed environment reference. `supportPrompt` keeps its
two text fragments in order. The explicit IDs remain stable if you move or rename the file.
For environment parsing and defaults, read [Environment contracts](/docs/learn/concepts/environment).

## Resolve the context

The example also constructs `createApplicationContextResolver` for a caller that owns context
resolution. Call its `resolve` method with a logger and cancellation signal. It returns
`constants.maxItems` as `20`, `constants.region` as `"eu-west-1"`, and
`prompts.support` as the two text fragments.

Static values are prepared when the resolver is created. Function-valued constants run on
each resolution and receive the environment, logger, and cancellation signal. Duplicate
constant names across registered descriptors are rejected. These are context-resolution APIs;
`defineApp` does not accept `constants` or `prompts` configuration properties.

See [`defineConstants`](/docs/api/app#defineconstants), [`definePrompt`](/docs/api/app#defineprompt),
and [`createApplicationContextResolver`](/docs/api/app#createapplicationcontextresolver) for
their exact contracts. Continue with [Invocation context](/docs/learn/concepts/context) or
[Build an offline agent](/guides/ai/build-an-offline-agent).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/app` API](/docs/api/app)
- [`@relkit/config` API](/docs/api/config)

- [`apps/docs/examples/public-api/context.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/public-api/context.ts)

---

# Define a service
Source: https://relkit.dev/docs/modules/service/define

A service's `service.ts` file lists the operations and event contracts other parts of your application may use. Keep handlers in their own files and list only the
operations and event contracts that should form that boundary. `defineService` is available from
`@relkit/app/services`.

> **Before you begin**
>
> Start with an [existing application](/docs/learn/create-an-app). Services use the app package
> already installed by the starter.

## Scaffold a service

From an installed application's root, create a service with one example function:

```sh title="Terminal — application root"
bun run relkit add service Billing
```

If the terminal asks which contents to include, choose the simple service. This creates
`src/services/billing/service.ts` and `functions/example.function.ts` beneath it.
The service exposes the function as `example`. Replace the placeholder schemas and handler with
your behavior, then choose the public members as explained below. If you already have the service,
[add a function to it](/docs/learn/concepts/functions#scaffold-a-callable-function) instead.

For a manual setup, create the service and its owned descriptors yourself. The CLI and manual
paths use the same public APIs. See the [service command reference](/docs/api/cli#relkit-add-service-name)
for all flags, or [scaffold constants and prompts](/docs/modules/service/context-values#scaffold-shared-values).

**Custom and full service bundles**

Choose a custom or full bundle when you need more than the example function:

```sh title="Terminal — application root"
bun run relkit add service Receipts --include function --include error --include job
bun run relkit add service Shipping --full
```

These create different domains; do not run all three if you only need one. Without a mode in
headless execution, the default is `service.ts` plus `functions/example.function.ts`, exposed as
`example`. `--include` is repeatable and cannot be combined with `--full`; dependent sample
artifacts are added and wired automatically.

Simple service creation adds no native model/provider stack. A selected custom/full bundle normally
installs its required adapters, native SDKs and local tooling. With `--no-install`, finish the reported
`bun install` and check steps. Manual source setup follows each capability's installation guide.

The full bundle creates a service, callable function, event-only function, typed error, event,
job, cache, bucket, tool, prompt, agent, constants, and `GET /shipping`. Auth, database, middleware,
and transforms are excluded. See [full-bundle prerequisites](/docs/modules/cli/add-artifacts#add-a-domain)
before starting the generated providers.

For `Shipping --full`, the domain files are:

```text
src/services/shipping/
  service.ts
  functions/example.function.ts
  functions/on-example.function.ts
  errors/example.error.ts
  events/example.event.ts
  tasks/example.task.ts
  jobs/example.job.ts
  cache/example.cache.ts
  buckets/example.bucket.ts
  tools/example.tool.ts
  prompts/example.prompt.ts
  agents/example.agent.ts
  constants/example.constants.ts
src/routes/shipping/route.ts
```

The service exposes the example function, event, task, and job. The function declares its sample error
and publishes the event; the event-only function consumes it. The job targets the task, the tool
targets the callable function, the agent uses the tool and prompt, and the route maps `GET` to `example`
member. Provider configuration, environment examples, and package dependencies are merged as needed.

For every scaffolding flag, see the [CLI reference](/docs/api/cli).

## Select public members

```ts title="examples/commerce/src/services/orders/service.ts"
/** Declares the orders service boundary without acquiring native clients. */
import { defineService } from "@relkit/app/services";
import createOrder from "./functions/create-order.function.js";
import deleteOrder from "./functions/delete-order.function.js";
import getOrder from "./functions/get-order.function.js";
import searchOrders from "./functions/search-orders.function.js";
import updateOrder from "./functions/update-order.function.js";
import authorizeOrder from "./functions/authorize-order.function.js";
import streamOrderReport from "./functions/stream-order-report.function.js";
import cleanupOrders from "./jobs/cleanup-orders.job.js";
import exportOrders from "./jobs/export-orders.job.js";
import cleanupOrdersTask from "./tasks/cleanup-orders.task.js";
import exportOrdersTask from "./tasks/export-orders.task.js";

export default defineService({
  functions: {
    createOrder,
    deleteOrder,
    getOrder,
    searchOrders,
    updateOrder,
    authorizeOrder,
    streamOrderReport,
  },
  tasks: { cleanupOrdersTask, exportOrdersTask },
  jobs: { cleanupOrders, exportOrders },
});
```

`functions` contains ordinary callable function descriptors. `events` contains handler-free event
contracts. `tasks` and `jobs` contain the task/job descriptors owned by the service. All maps are optional.
They are **definition options**, not namespaces on the resulting
service: callers use `orders.createOrder` and `orders.orderCreated`, not
`orders.functions.createOrder` or `orders.events.orderCreated`.

Members are the original descriptors, not copies. A function exposed through a service retains its
identity, input and output schemas, declared errors, and `.invoke()` behavior. Changing the local import
name does not create a new operation.

## Use public functions from the frontend

The service boundary is internal to the backend. Expose its selected functions through a route
before calling them from the browser. These are the same Orders members declared above:

```ts title="src/routes/orders/route.ts — backend"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";

/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
 * @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
  const { status } = useRelkitClient();
  const orders = useRoute("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      {orders.isPending && <p role="status">Loading orders…</p>}
      {orders.data && <p>{orders.data.count} orders</p>}
      {orders.isError && <p role="alert">{orders.error.message}</p>}
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

## Decide what stays internal

Leave a function out of the service if only its own domain uses it. It is still discovered and can be
called by other functions in that domain. A helper does not become public just because its module
exports it in TypeScript.

Do not put caches, buckets, tools, agents, or plain helper values into the member maps. A task/job member
does not expose a browser client by itself; its explicit `client` policy still controls that boundary.
`defineEventFunction` subscribers are event-only and cannot be public callable members either. Keep
those artifacts in the domain; expose an ordinary function when another domain needs their behavior.

For example, expose `askAssistant` as a function that calls a declared agent dependency, rather than
trying to expose the agent descriptor itself. See [the agent placement example](/docs/modules/service/organization#tools-and-agents-stay-with-their-business-domain).

This boundary is about application dependencies. It is not user authorization, an HTTP registration,
or a switch controlling MCP tool visibility.

## Use another domain's service

Import `@app/services/orders/service.js`, then invoke a member such as
`orders.getOrder.invoke({ orderId: "order-1" })` from your function handler. Use `.invoke()`, not
`.handler()`, so the call goes through the common validation and execution boundary.

Within Orders, import other Orders modules directly rather than importing the service back into its
own implementation. Across domains, import the service rather than a private function path.

| Importing layer    | Allowed application imports                                  |
| ------------------ | ------------------------------------------------------------ |
| A domain           | Its own modules, other domains' `service.ts`, and Platform.  |
| Routes             | Route modules, domain `service.ts` boundaries, and Platform. |
| Platform           | Other Platform modules, not domains or routes.               |
| `relkit.config.ts` | Platform support, not domains or routes.                     |

Generated projects map `@app/*` to `src/*`. Keep the `.js` extension in imports for emitted ESM.
An import of another domain's service records a `depends-on-service` graph edge; there is no service
`imports` option or service dependency container to configure.

A service may expose only its **own** functions and events. To compose another service's behavior,
write an operation in the consuming domain that calls it. Do not re-export another domain's descriptor
as your own service member.

## Keep runtime access explicit

Service membership does not provide a cache, bucket, job client, or agent client. Those remain explicit
function dependencies. Event publication uses `publishes` and `context.events[eventId].publish(...)`.
Exposing an event in `service.events` at definition time does not authorize a function to publish it.

There is no general service lifecycle, service middleware, or `context.service` API. Put HTTP policy in
[route middleware](/docs/modules/http/middleware). Put rules that must apply to every invocation in function
logic or [function hooks](/docs/learn/concepts/functions#hooks-and-transport-policy). The specialized
database and authentication services have their own integration APIs.

## Naming and discovery rules

Use a lowercase domain name beginning with a letter and containing only letters, digits, and hyphens,
such as `orders` or `customer-support`. Technical layer names such as `functions`, `events`, and `tools`
are reserved as legacy roots, not useful domain names.

Each domain's `service.ts` must construct and export exactly one service runtime value. Follow the
default-export form above; do not use it as a general barrel of unrelated exports.

The service ID is inferred from its domain directory. If you set it explicitly, it must equal that
directory name. IDs of owned descriptors must start with the domain prefix, such as `orders.`.
Capabilities that support inferred IDs can omit them; follow each capability's guide for its ID rules.

Public member names must be nonempty, normalized, and distinct across both maps. Descriptor fields such
as `id`, `ref`, `functions`, `events`, and `handler` are reserved member names. See the
[Services API](/docs/api/services) for the full type and validation reference.

The recognized flat-to-grouped move preserves explicit and inferred logical IDs: `src/orders` becomes
`src/services/orders` without introducing a `services.` identity prefix. Diagnostics, source maps,
manifests, and editor links retain the real physical path. Other file moves or renaming the domain can
change inferred IDs and their required prefix; review those as contract migrations.

## Can a service expose nothing?

Yes. A domain consisting of internal event subscribers can use this boundary:

```ts title="src/notifications/service.ts"
import { defineService } from "@relkit/app/services";

export default defineService({});
```

The receiving domain owns actual subscriber functions even though it exposes no public members. A
normal domain containing only this empty service and no graph-visible artifacts fails compilation.
Conversely, a domain that only publishes event contracts can expose `events` without exposing any
functions.

## Verify the boundary

From your application's root, run:

```sh
bun run check
bun run typecheck
```

The compiler reports missing or duplicate services, invalid domain IDs, foreign service members, and
disallowed imports. Once the checks pass, [connect public functions to routes](/docs/modules/service/routes)
or [test a first service end to end](/docs/modules/service/first-service).

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)

- [`examples/commerce/src/services/orders/service.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/service.ts)

## Scaffold domain constants

With an existing `orders` service, run from the application root:

```sh
bun run relkit add constants receipt-settings --service orders
```

Creates `src/services/orders/constants/receipt-settings.constants.ts` with a domain-qualified key and
a `"replace-me"` value. Replace that placeholder in source. Constants remain internal and are
not added to service member maps. There is no CLI flag for the final value.

For every constants scaffolding flag, see the [CLI reference](/docs/api/cli).

---

# Design your domains
Source: https://relkit.dev/docs/modules/service/domains

A domain is a part of your product with its own responsibility, such as Orders, Receipts, or Accounts. Orders knows what it
means to create, price, update, or cancel an order. Receipts knows how to prepare and send a receipt.
Both may use functions, events, and storage, but those technologies do not define their boundaries.

In RELKIT, a domain is an immediate child of the selected service root, such as `src/services/orders/`
in a new grouped app or `src/orders/` in an existing flat app. One `service.ts` describes what other
domains and routes may use. Keep the app's boundary shape consistent.

## Why have domains?

As a feature grows, its implementation spans several kinds of code. Order creation can require
validation, a price lookup, a cache, an event, and an AI lookup tool. Grouping all functions together and
all tools elsewhere makes you reconstruct that feature's ownership every time you change it.

A domain keeps those related decisions together. Its public service tells a new contributor what the
rest of the application depends on; its internal files show how the behavior is implemented. You can
change the internals without teaching every caller about the new layout.

The benefit is a shorter change path, not a promise that adding folders makes execution faster:

- **Find the owner quickly.** A request about order pricing starts in Orders, even if the implementation
  now uses a cache or a connected provider.
- **Reuse an operation.** An HTTP route and an AI tool can use the same validated function instead of
  maintaining separate implementations.
- **Review a smaller contract.** Callers depend on selected service members, not every helper file.
- **Add independent reactions.** Receipts can subscribe to an order event without adding receipt logic
  to the order-creation handler.
- **Catch misplaced dependencies early.** `bun run check` reports invalid domain boundaries and public
  members before the application activates.

## Choose the owner before the file type

Ask: “Which part of the product is responsible for this rule or result?”

| Change                                           | Likely owner | Reason                                            |
| ------------------------------------------------ | ------------ | ------------------------------------------------- |
| Calculate an order total                         | Orders       | It defines order pricing behavior.                |
| Add a tool that looks up an order                | Orders       | AI access does not change who owns the lookup.    |
| React to an order by sending a receipt           | Receipts     | The reaction belongs to the receiving domain.     |
| Parse an HTTP header                             | Routes       | It is a transport detail, not an order rule.      |
| Declare a provider endpoint environment variable | Platform     | It supports runtime configuration across domains. |

Start with the smallest boundary that has a useful responsibility. One domain can be enough for a small
application. You do not need one domain per endpoint, database table, function, or developer.

## Keep together what changes together

Keep order-specific functions, schemas, errors, tools, and agents in Orders while they share the same
business rules. A new file or subdirectory is often enough; a new service is not required for each
feature. Nested directories remain part of that owning domain. A nested `service.ts` cannot create an
independent child service; add another immediate service-root child when a separate boundary is needed.

Consider a separate domain when it has a responsibility you can name independently, can expose a small
useful contract, and evolves without requiring callers to understand its internal details. Receipts is
a useful separation when receipt delivery has its own retry, scheduling, and formatting concerns.

Do not create an empty domain for a future feature. A normal domain must own a graph-visible artifact
in addition to its service, even if it has no public functions.

## Call for a result; publish for a reaction

Use a public service function when the caller needs a result before it can continue. Use an event when
the originating operation should not wait for the follow-up work to finish. Events add delivery and
retry considerations, so they are not a substitute for every function call.

This subscriber illustrates the receiving side of that relationship:

```ts title="src/services/orders/functions/order-confirmation.function.ts"
import { defineEventFunction } from "@relkit/app/events";

const orderConfirmation = defineEventFunction({
  id: "orders.confirmation",
  event: "orders.created",
  handler: async (order, context) => {
    context.log.info("order.confirmation.requested", { orderId: order.orderId });
  },
});

export default orderConfirmation;
```

Orders owns the `orders.created` event contract. The receiving domain owns this subscriber and any
follow-up work it starts. If a subscriber needs a synchronous result from another domain, call that
domain's public service function rather than reaching into its private implementation.

Continue with [getting started with events](/docs/modules/events) for publication and subscription, or
[jobs](/docs/modules/jobs) for queued execution. You do not add subscriber functions to the producer's
service or call them directly; `defineEventFunction` is event-only.

## Iterate without widening every boundary

For a new order feature, first add or change the function inside Orders and test its behavior. Add it to
the service only if a route or another domain needs to call it. Then attach the appropriate entry point:
a route, tool, job, or event subscriber. Keep existing callers on the same public contract where possible.

If two domains repeatedly need each other's private helpers, reconsider the boundary. Put the rule with
its real owner and expose a meaningful operation, or keep the code in one domain if it cannot be
separated coherently. Do not use Platform to bypass domain ownership.

A domain is a source and application boundary, not an independently deployed microservice. Defining
several services does not create several servers, network hops, or isolated databases. Domain separation
also does not provide authentication or authorization by itself.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/events` API](/docs/api/events)

- [`apps/docs/examples/events/order-confirmation.function.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/events/order-confirmation.function.ts)

---

# Your first service
Source: https://relkit.dev/docs/modules/service/first-service

Trace the Orders endpoint through its route, service, and pricing function to see where each responsibility belongs. You will identify which file owns pricing, which operations the Orders service exposes, and
how a route reaches them. That chapter adds these maintained API-candidate sources to the certified
minimal starter; it does not require an uncertified creation tuple. Run commands from the app root.

> **Before you begin**
>
> Continue from the [Orders endpoint](/docs/learn/first-route), which supplies the function used
> below.

The endpoint chapter uses `relkit add function --create-service` to create the service and its
first operation together. To start a different domain, use
[`relkit add service`](/docs/modules/service/define#scaffold-a-service); to extend this one, use
[`relkit add function --service orders`](/docs/learn/concepts/functions#scaffold-a-callable-function).
Keep the existing Orders files while following this walkthrough.

1. ## Keep behavior in the Orders domain

    `src/services/orders/functions/create-order.function.ts` validates an order request and asks
    `priceOrder` to calculate the total. It does not parse an HTTP request:

    ```ts title="src/services/orders/functions/create-order.function.ts"
    /** Validates order input, invokes the service-local pricing function, and returns the calculated order. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    const orderInput = z.object({
      orderId: z.string().min(1),
      sku: z.string().min(1),
      quantity: z.number().int().positive(),
    });

    const orderOutput = z.object({
      orderId: z.string(),
      sku: z.string(),
      totalCents: z.number().int().nonnegative(),
    });

    const createOrder = defineFunction({
      input: orderInput,
      output: orderOutput,

      handler: async (input) => {
        const { totalCents } = await priceOrder.invoke({ quantity: input.quantity });
        const order = {
          orderId: input.orderId,
          sku: input.sku,
          totalCents,
        };

        return order;
      },
    });

    export default createOrder;
    ```

    The function can be called from HTTP, a job, or another function. Its input and output
    schemas apply on every invocation. Create `tests/unit/orders.function.test.ts` with this focused
    candidate test to invoke it without starting a server:

    ```ts title="tests/unit/orders.function.test.ts"
    /** Checks orders.function through the supported public RELKIT APIs. */
    import { expect, test } from "bun:test";
    import { invokeFunction } from "@relkit/testing";
    import orders from "@app/services/orders/service.js";

    test("createOrder invokes pricing", async () => {
      const result = await invokeFunction(orders.createOrder, {
        orderId: "order-1",
        sku: "book",
        quantity: 3,
      });

      expect(result).toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
    });
    ```

2. ## Expose only selected operations

    The existing `src/services/orders/service.ts` selects the functions that other parts of the app may
    call. `priceOrder` and `createOrder` remain separate operations, so changing a price rule
    does not require moving it into a route:

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import createOrder from "@app/services/orders/functions/create-order.function.js";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    export default defineService({
      functions: { createOrder, priceOrder },
    });
    ```

    The compiler discovers this service from source. You do not add it to a registration array.
    The route imports the service and selects `createOrder` for `POST /orders`:

    ```ts title="src/routes/orders/route.ts"
    /** Maps the HTTP endpoint to its owning service's public member. */
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { POST } = defineServiceRoutes(orders, {
      POST: { member: "createOrder", successStatus: 201 },
    });
    ```

    Exposing a service member does not itself create an endpoint or grant caller permission.
    The route provides HTTP exposure; the [auth chapter](/docs/learn/protect-orders) later enforces
    identity and ownership.

3. ## Verify the boundary

    From `relkit-orders`, run:

    Create `tests/integration/orders.route.test.ts` from the [HTTP route test](/docs/modules/http/first-route)
    before running its command below. These tests are Orders extensions, not files shipped by minimal.

    ```sh
    bun run check
    bun run typecheck
    bun test tests/unit/orders.function.test.ts
    bun test tests/integration/orders.route.test.ts
    ```

    Expect all four commands to succeed after adding the Orders sources and tests. The unit test checks the reusable
    operation; the HTTP test checks the public route's status and body. Continue with
    [the endpoint chapter](/docs/learn/first-route) to change pricing and verify the result.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/testing` API](/docs/api/testing)

- [`templates/default/v1/minimal/src/services/hello/service.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/minimal/src/services/hello/service.ts)
- [`templates/default/v1/minimal/tests/unit/hello.function.test.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/minimal/tests/unit/hello.function.test.ts)

---

# Move a flat application to grouped services
Source: https://relkit.dev/docs/modules/service/migration

Move to the grouped `src/services/<name>/service.ts` layout when it helps organize an existing application. New applications use
`src/services/<name>/service.ts`; `relkit add` preserves an existing app's detected layout.
Migration is optional and does not change service APIs, logical IDs, provider profiles, or task versions.

1. ## Preview before applying

    Run from the application root with installed dependencies:

    ```sh
    bun run relkit migrate layout
    bun run relkit --json migrate layout
    ```

    Preview inventories complete service roots, including helpers and assets, and reports exact moves,
    syntax-aware rewrites, conflicts, and manual-action references. It leaves source, lockfiles,
    generated output, database migration history, credentials, runtime state, and observability unchanged.
    An already grouped app has no moves.

    Static imports, re-exports, type-only imports, and literal dynamic imports use the effective
    TypeScript configuration and resolved target. Supported literal paths in tests, Drizzle configuration,
    package/operational scripts, code-generation configuration, Markdown code spans/links, and local agent
    guidance are planned explicitly. Comments and unrelated data strings remain intact. Ambiguous prose,
    interpolated paths, and computed affected references require manual review before write.

2. ## Apply a checked candidate

    Stop this application's development session and external watchers. Resolve occupied destinations,
    mixed/duplicate/nested service boundaries, case collisions, symlinks, and touched tracked changes.
    Unrelated dirty files and inventoried untracked service contents remain preserved.

    ```sh
    bun run relkit migrate layout --write
    ```

    Write uses separate owned staging directories with the installed dependency identity. Baseline and
    candidate must pass check and typecheck; logical graph and offline deployment comparisons must retain
    IDs, ownership, contracts, exposure, policies, bindings, and resources before publication. Missing
    validation is a refusal, not a compatibility pass. The operation does not install packages, run SQL
    migrations or seeds, acquire providers, provision cloud infrastructure, or edit global skills.

    Publication is coordinated across files. The restricted local receipt retains before/after bytes,
    permissions, and created-directory ownership for interruption or crash recovery; it does not promise
    cross-file atomicity. Keep the returned `.relkit/migrations/<id>/receipt.json` private. Failure recovery
    restores only matching transaction-owned states and preserves later edits.

## Roll back with the exact receipt

Use the path returned by the write result:

```sh
bun run relkit migrate layout --rollback .relkit/migrations/RECEIPT_ID/receipt.json
```

Rollback rejects foreign, redirected, tampered, or permissive receipts. Later edits and occupied original
locations are conflicts; it refuses to overwrite them. Inspect a retained recovery-required receipt and
resolve its reported conflict before retrying. Never delete runtime state or migration history to force
a rollback.

After migration or restoration, prepare a fresh development cohort:

```sh
bun run check
bun run typecheck
bun run relkit dev --prepare
bun run dev
```

Verify actual public responses and authorization before accepting the new cohort. Graph/build hashes
and source links can change; that physical provenance is distinct from the stable logical contracts.
Accepted jobs and agent threads can remain pinned to immutable older executable cohorts, so retain their
owned artifacts and test native recovery before claiming source-move continuity. Stable IDs alone do not
prove a provider can resume incompatible or unavailable historical executables.

CLI statuses are `0` for successful preview/write/no-op/rollback, `1` for operational refusal,
`2` for usage errors, and `130` for migration cancellation. JSON stdout contains one secret-safe result;
diagnostic logging uses stderr.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)

- [`packages/cli/tests/migration/layout.probe.ts`](https://github.com/rel-kit/relkit/blob/main/packages/cli/tests/migration/layout.probe.ts)

---

# Where to put your code
Source: https://relkit.dev/docs/modules/service/organization

Keep files with the service that owns their behavior, regardless of how callers reach them. For example, an order lookup belongs to
Orders whether it is reached from HTTP, another function, or an AI model. Its implementation stays in
`src/services/orders/functions/`; the entry points reference it.

## The placement map

The paths below are patterns, not files you must create in every domain. Replace `orders` with the owner.

| What you are adding                | Where it belongs                                                                                                           | Continue learning                                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Public domain boundary             | `src/services/orders/service.ts`                                                                                           | [Define a service](/docs/modules/service/define)                                                          |
| Business operation                 | `src/services/orders/functions/create-order.function.ts`                                                                   | [Functions](/docs/learn/concepts/functions)                                                               |
| Event contract                     | `src/services/orders/events/order-created.event.ts`                                                                        | [Events: getting started](/docs/modules/events)                                                           |
| Event subscriber                   | `functions/*.function.ts` in the **receiving** domain, such as `src/services/receipts/functions/order-receipt.function.ts` | [Consume an event](/docs/modules/events/consume)                                                          |
| Task and its job                   | `src/services/receipts/tasks/send-receipt.task.ts` and `src/services/receipts/jobs/send-receipt.job.ts`                    | [Jobs: getting started](/docs/modules/jobs) and [schedules](/docs/modules/jobs/schedules)                 |
| AI tool                            | `src/services/orders/tools/lookup-order.tool.ts`                                                                           | [AI: getting started](/docs/modules/ai), then [tools](/docs/modules/ai/tools)                             |
| AI agent                           | `src/services/orders/agents/order-support.agent.ts`                                                                        | [AI: getting started](/docs/modules/ai), then [your first agent](/guides/ai/build-an-offline-agent)       |
| Cache                              | `src/services/orders/cache/prices.cache.ts`                                                                                | [Caching: getting started](/docs/modules/caching)                                                         |
| Object bucket                      | `src/services/assets/buckets/assets.bucket.ts` in the domain that owns the files                                           | [Storage: getting started](/docs/modules/storage)                                                         |
| Database service                   | `src/services/database/service.ts` using `defineDrizzleService`                                                            | [Database: getting started](/docs/modules/database)                                                       |
| Database table                     | `src/services/database/schema/`, exported through its `index.ts`                                                           | [Define the schema](/docs/modules/database/schema)                                                        |
| Custom data-model method           | `src/services/database/models/*.model.ts`, registered in the database service                                              | [Custom models](/docs/modules/database/models)                                                            |
| Database migration                 | Tracked SQL/metadata under `src/services/database/migrations`; runner owned by installed tooling                           | [Migrations](/docs/modules/database/migrations)                                                           |
| Domain schema                      | Beside its sole consumer, or a domain module such as `src/services/orders/schemas.ts` when shared locally                  | [Schemas](/docs/learn/concepts/schemas)                                                                   |
| Declared domain error              | `src/services/orders/errors/order-not-found.error.ts`                                                                      | [Errors](/docs/learn/concepts/errors)                                                                     |
| Prompt, constant, or helper        | Beside its consumer or in a focused module within the same domain                                                          | [Agent instructions](/docs/modules/ai/agents), [domain boundaries](/docs/modules/service/define)          |
| URL and HTTP method                | `src/routes/orders/route.ts`                                                                                               | [Services and routes](/docs/modules/service/routes)                                                       |
| HTTP middleware or input transform | `src/routes/middleware/*.middleware.ts` or `src/routes/transforms/`                                                        | [Middleware](/docs/modules/http/middleware), [request mapping](/docs/modules/http/requests)               |
| Environment contract               | `src/platform/env.ts`                                                                                                      | [Environment](/docs/learn/concepts/environment)                                                           |
| Provider and server configuration  | `relkit.config.ts`, importing infrastructure support from Platform                                                         | [Integrations](/docs/modules/integrations), [application configuration](/docs/learn/concepts/application) |
| Function and application tests     | `tests/unit/` and `tests/integration/`                                                                                     | [Testing](/docs/modules/operations/testing)                                                               |

Default-export each ordinary descriptor from its own file, following its capability's guide. Route files
are different: they export named HTTP methods. Plain helper modules are ordinary TypeScript; they do not
need a RELKIT descriptor or their own service.

## One selected service root

New applications place boundaries at `src/services/<name>/service.ts`. Existing flat
applications keep `src/<name>/service.ts`, and `relkit add` preserves the detected layout.
Choose one root for the whole application, including Database and Auth. A directory alone,
an empty `services/` directory, or a folder containing only helpers does not select a layout.
Discovery uses authored service and descriptor evidence.

Each service is an immediate child of the selected root. Every descriptor belongs beneath
exactly one boundary. Nested boundaries, mixed flat/grouped services, missing boundaries,
and an aggregate `src/services/service.ts` are structural errors. A source-only move keeps
logical IDs, URLs, exposure, resource ownership and policies stable. Use the
[optional migration guide](/docs/modules/service/migration) for coordinated moves and rollback.

## Imports follow the boundary

Service implementation files can import their own files, Platform, and another service's
public `service.ts` boundary. Routes can import service boundaries and Platform. Platform
can import only Platform within application source; `relkit.config.ts` can import Platform
fragments. Application code cannot depend on tests, migrations, scripts or other tooling.
Tooling can import the application for testing and operational work.

The compiler follows helper modules, re-exports, type-only edges and literal dynamic imports
using the project's effective TypeScript aliases. A barrel cannot make a private cross-service
import public. Computed dynamic imports and unresolved dynamic targets produce analysis-limit
warnings; they are not proof that the target respects a boundary.

Keep prompt text, JSON assets, schemas and local helper modules beside their consumer.
Assets move with their service but do not become independently discovered descriptors.

## Functions own behavior; dependencies grant clients

A function is where validated business input becomes a result. Keep HTTP parsing in routes and model
instructions in agents. The function declares the provider-backed resources it uses; putting a cache or bucket
in the same folder does not grant access automatically.

```ts title="examples/commerce/src/services/orders/functions/create-order.function.ts"
/** Prices validated order input through the declared cache, records request tracing and derives its receipt key. */
import { defineFunction } from "@relkit/app/functions";
import prices from "../cache/prices.cache.js";
import { receiptObjectName } from "../../../platform/receipt-object.js";
import { createOrderOutput, orderInput } from "../../../platform/schemas.js";

const createOrder = defineFunction({
  // RELKIT validates these schemas before the handler runs.
  input: orderInput,
  output: createOrderOutput,
  dependencies: {
    cache: { prices },
  },
  timeoutMs: 10_000,
  concurrency: 100,
  handler: async (input, context) => {
    // Dependencies are accessed through the checked execution context.
    const unitPrice = await context.trace.span(
      "pricing.calculate",
      { attributes: { "pricing.strategy": "catalog" } },
      () => context.cache.prices.getOrSet({ sku: input.sku }, async () => 1_000),
    );
    context.trace.event("pricing.calculated", { "pricing.unit_cents": unitPrice });
    context.trace.setAttributes({ "pricing.quantity": input.quantity });
    const totalCents = unitPrice * input.quantity;
    return {
      orderId: input.orderId,
      receiptKey: receiptObjectName(input.orderId),
      totalCents,
    };
  },
});

export default createOrder;
```

Here, `dependencies.cache` supplies `context.cache.prices`. Event publishers separately declare
`publishes` before using `context.events`; see [publish an event](/docs/modules/events/publish).
Neither permission is configured in `service.ts`. The price cache is an
Orders implementation detail, while `createOrder` can be a public operation.

Use [functions](/docs/learn/concepts/functions) for the handler and validation model,
[context](/docs/learn/concepts/context) for execution resources, and
[your first cache](/guides/caching/cache-product-prices) for a complete resource-backed example.

## Tools and agents stay with their business domain

Put an order lookup tool in Orders, not in a separate application-wide AI domain just because a model
calls it. A tool points at a function with `defineTool({ target: ... })` or adapts that function with
`.asTool()`. The schemas and business behavior stay with the function. Start with
[defining a tool](/docs/modules/ai/tools) or [turning a function into a tool](/docs/modules/ai/function-tools).

An agent's `agents/` file owns its instructions, schemas, model, tool allowlist, and execution limits.
Store long instructions in a local prompt module if that makes them easier to maintain. Plain text does
not need a new service. See [defining an agent](/docs/modules/ai/agents).

Native execution requires [installing `@relkit/langchain` and its selected SDKs](/guides/ai/build-an-offline-agent)
and configuring the required runtime profiles. A folder or generic agent contract does not select that engine.

To let a browser run an agent, expose its `client` contract and select it with the generated
`useAgent` hook. Every run, observation, control, and continuation supplies the application's stable
business thread ID. Agents and tools remain compiler-discovered domain files; do not add an `agents` or
`tools` map to `defineService`. A tool in another domain can target a public function from the owning
service; it should not import that domain's private tool file.

“Internal to the domain” does not mean “hidden from MCP.” When the endpoint is explicitly enabled,
tools are eligible by default unless disabled. Complete the separate [MCP SDK/setup](/docs/modules/ai/mcp)
and review [tool approvals](/docs/modules/ai/approvals) before exposing them.

## Events and jobs belong to the work's owner

Put the fact in the producing domain's `events/` directory and the reaction in the receiving domain's
`functions/` directory. For example, Orders defines `orders.created`, while Receipts defines the
`defineEventFunction` that reacts to it. The subscriber stays out of `service.functions`: it runs through
event delivery or replay, not direct invocation.

A task and job belong to the domain responsible for completing the durable work. The task stays in that
domain's `tasks/` directory and the job owns its public name, admission, and schedules. A schedule is an
option on the job, not a separate service or a reason to move the task. Follow [your first event](/guides/events/react-to-order-events),
[jobs](/docs/modules/jobs), and [schedules](/docs/modules/jobs/schedules) for the complete workflows.

## Resources do not go in the service member list

Caches and buckets live under their owning domains. Functions declare `dependencies.cache` or
`dependencies.buckets`, and `relkit.config.ts` supplies provider bindings for the selected profiles.
Changing the provider does not require moving the domain's business code.

If another domain needs access, expose an operation on the owner—such as uploading or reading a file—
instead of publishing the raw cache or bucket as a service member. See the
[storage tutorial](/guides/storage/upload-product-images) for a bucket, function, service, and route working together.

Database and authentication integrations have specialized boundaries: `src/services/database/service.ts` uses
`defineDrizzleService`, with table schemas beneath that domain; `src/services/auth/service.ts` uses
`defineBetterAuthService`. They are not `database` or `auth` options on `defineService`. Start with
[Database](/docs/modules/database) for setup, schemas, queries, and model customization. The compiler supplies
`context.database`; functions do not add a `dependencies.database` entry. Ordinary business domains
still expose operations through `defineService`. See the
[Database](/docs/modules/database) and [Auth](/docs/modules/auth) guidance when replacing older adapters, or
[Integrate Better Auth](/docs/modules/database/better-auth)
to share the current database with authentication. Continue with [Auth](/docs/modules/auth) for service setup,
sessions, route protection, clients, and authentication customization.

## Shared code is not a shortcut around ownership

Keep domain-specific schemas, constants, errors, and helpers with their owner. Other domains consume
public service operations instead of importing those private modules. A public function's declared
errors are part of its checked contract; you do not add an `errors` member map to the service.

Use `src/platform/` for genuinely shared, domain-independent support, such as the environment contract
or common schema primitives. Platform cannot import domains or routes. If a “shared” helper knows how
Orders calculates a total, it belongs to Orders.

Tests live outside `src/` in the generated layout. Unit tests can import the specific function they
exercise; integration tests verify the application's routes and runtime behavior. Do not add a domain
service just to hold tests.

## Let the compiler check the organization

Run these commands from your generated application's root after adding or moving artifacts:

```sh
bun run check
bun run typecheck
```

Expect a successful graph check and type check. Fix missing services, invalid IDs, unresolved targets,
and boundary errors before continuing. Do not register every file manually in `relkit.config.ts` or edit
`.relkit/generated`; the compiler derives the model from source.

Naming and folder-placement suggestions remain nonfatal convention warnings. They are
distinct from ownership, missing-boundary, mixed-layout and forbidden-import errors.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/tools` API](/docs/api/tools)
- [`@relkit/agents` API](/docs/api/agents)
- [`@relkit/jobs` API](/docs/api/jobs)
- [`@relkit/events` API](/docs/api/events)
- [`@relkit/cache` API](/docs/api/cache)
- [`@relkit/buckets` API](/docs/api/buckets)

- [`examples/commerce/src/services/orders/functions/create-order.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/services/orders/functions/create-order.function.ts)
- [`templates/default/v1/agent/src/services/hello/agents/assistant.agent.ts`](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/agent/src/services/hello/agents/assistant.agent.ts)

---

# Expose a service through routes
Source: https://relkit.dev/docs/modules/service/routes

Use a service to expose application operations and a route to give an operation an HTTP method and URL. A route says which operation is
reachable at a particular URL and HTTP method. Adding a function to `service.ts` does not create a URL;
adding a domain does not create a server or a route prefix.

Keep the route files under `src/routes/`, outside the domains. This page covers the service-to-HTTP
boundary; [HTTP Routes getting started](/docs/modules/http) introduces request parsing, middleware, responses,
and client contracts.

## Assign each responsibility once

| Concern                                                     | Owner                                      |
| ----------------------------------------------------------- | ------------------------------------------ |
| Business input, output, errors, and behavior                | The domain function.                       |
| Which domain functions callers may use                      | The domain's `service.ts`.                 |
| URL path and HTTP method                                    | The route file path and its named exports. |
| Headers, cookies, query/body mapping, response status       | The route's transport configuration.       |
| HTTP middleware and request authentication                  | The Routes layer.                          |
| Rules that must also apply to jobs, tools, and direct calls | The function, not only HTTP middleware.    |

Routes import `@app/services/orders/service.js`, never Orders' private function files. Domain functions do not
import routes. That direction lets you add another transport without pulling HTTP concerns into the
business operation.

## Map methods to public functions

With an existing Orders service exposing `searchOrders` and `createOrder`, scaffold a new route:

```sh title="Terminal — application root"
bun run relkit add route /orders --mode service-route --service orders \
  --map GET=searchOrders --map POST=createOrder
```

This creates `src/routes/orders/route.ts` and maps both methods. If that file already exists,
edit it instead. The command uses inferred mapping and HTTP `200`; add the explicit request
mapping and `201` status in source as shown below. See the
[route command reference](/docs/api/cli#relkit-add-route-path) for all flags.

Use `defineServiceRoutes` when the methods in a route file belong to one service:

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * Maps order HTTP operations to public service members with the existing request
 * and rate-limit policies. The rate-limit reference addresses the declared cache
 * by its stable identity without importing a private service implementation.
 */
import { defineServiceRoutes, http } from "@relkit/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = defineServiceRoutes(orders, {
  GET: "searchOrders",
  POST: {
    member: "createOrder",
    request: http.input({
      orderId: http.header("idempotency-key"),
      customerEmail: http.header("x-customer-email"),
      sku: http.body("sku"),
      quantity: http.body("quantity"),
    }),
    rateLimit: {
      limit: 20,
      windowMs: 60_000,
      key: http.header("x-customer-email"),
      store: {
        ref: { kind: "cache", id: "orders.rate-limits" },
        key: z.string(),
        value: z.number().int().nonnegative(),
      },
    },
    successStatus: 201,
  },
});
```

The file supplies `/orders`. The exported `GET` and `POST` names supply the methods. `GET` selects the
public `searchOrders` function by member name. `POST` selects `createOrder`, explicitly maps headers
and body fields into its domain input, and sets the successful response status to `201`.

### Use the service routes from the frontend

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";

/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
 * @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
  const { status } = useRelkitClient();
  const orders = useRoute("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  return (
    <section>
      {orders.isPending && <p role="status">Loading orders…</p>}
      {orders.data && <p>{orders.data.count} orders</p>}
      {orders.isError && <p role="alert">{orders.error.message}</p>}
      <button
        disabled={status !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

Use a string member name when inferred request/response mapping fits. Use an object with `member` when
you need explicit mapping, status, limits, or other function-route options. Explicit request mappings
replace inference rather than partially extending it. See [request mapping](/docs/modules/http/requests).

Keep the exported destructuring form shown above. `defineServiceRoutes` does not support renamed
method bindings, rest bindings, a default export, or methods named after business operations. Supported
methods are `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS`.

## Choose the URL independently of the domain

| Route file                             | URL                | What it decides                                                    |
| -------------------------------------- | ------------------ | ------------------------------------------------------------------ |
| `src/routes/orders/route.ts`           | `/orders`          | Collection operations.                                             |
| `src/routes/orders/[orderId]/route.ts` | `/orders/:orderId` | Operations on a particular order.                                  |
| `src/routes/uploads/route.ts`          | `/uploads`         | A URL that calls the Assets service without using its domain name. |

The service does not own these URL prefixes. Several route files can use the same service, and a route
module can import multiple public services if necessary. Keep reusable cross-domain business
orchestration in a function instead of spreading it across HTTP handlers.

Follow [file-system routes](/docs/modules/http/routes) for dynamic segments, catch-all paths, matching precedence,
and route identities. Do not add `path` or `method` to a function-backed `defineRoute` descriptor.

## When to use defineRoute

For an individual mapping, use `defineRoute` with a public function as its `target`:

```ts title="templates/default/v1/minimal/src/routes/hello/route.ts"
/** Maps the HTTP endpoint to its owning service's public member. */
import { defineRoute } from "@relkit/app/routes";
import hello from "@app/services/hello/service.js";

export const GET = defineRoute({
  target: hello.hello,
});
```

Both factories produce route descriptors for the same routing pipeline. Neither can target an event
contract, an event-only subscriber, a tool, or an agent directly. To expose agent behavior, route to the
[ordinary function that calls it](/docs/modules/service/organization#tools-and-agents-stay-with-their-business-domain).

`defineRoute({ handler: ... })` also supports raw HTTP integrations. Keep business operations on the
function-backed path. Better Auth is a specialized raw-handler integration mounted on an `ALL`
catch-all route; `ALL` is not a method accepted by `defineServiceRoutes`.

## Use from the frontend

After [frontend setup and contract pull](/guides/frontend/connect-react), render the Hello route
through its generated `GET /hello` selector. `name` and `data.message` are inferred from the
backend function's schemas:

```tsx title="src/App.tsx — frontend"
"use client";

/** Renders the minimal backend's greeting through the pulled registry and a same-origin client provider. */
import { RelkitClientProvider, useRelkitClient, useRoute } from "@relkit/client/react";

/** Displays the typed Hello result after the provider resolves backend identity.
 * @returns Loading, connection failure, request failure, or the successful greeting. */
export function Greeting() {
  const { status } = useRelkitClient();
  const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

  if (status === "application-updated") {
    return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
  }
  if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
  if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
  if (greeting.isPending) return <p role="status">Loading greeting…</p>;
  return <h1>{greeting.data.message}</h1>;
}

/** Supplies the shared query cache and identity handshake to the frontend tree.
 * @returns The greeting inside a same-origin RELKIT provider. */
export default function App() {
  return (
    <RelkitClientProvider>
      <Greeting />
    </RelkitClientProvider>
  );
}
```

Keep `.invoke()` and service imports on the backend. A function or service needs a client-exposed
route before the browser can call it. The provider handles identity and query state; the
[Frontend guide](/guides/frontend/connect-react) also shows where this component belongs in Next.js.

Reference: [`useRoute`](/docs/api/client#useroute),
[`RelkitClientProvider`](/docs/api/client#relkitclientprovider).

`defineServiceRoutes` produces the same client contracts per exported method: `GET /orders` uses
[`useRoute`](/docs/modules/client/routes), while `POST /orders` uses
[`useRouteMutation`](/docs/modules/client/mutations). The input remains the target function's input;
explicit HTTP header or body mappings do not construct RPC input. Only exposing a service member
does not make it a browser operation: it needs a client-exposed route.

## Continue with the Routes topics

Choose the topic that matches the HTTP work you need to do:

[Your first HTTP route](/docs/modules/http/first-route): add a validated endpoint and
integration test.

[Define a route](/docs/modules/http/define): choose `defineRoute` or `defineServiceRoutes`.

[File-system routes](/docs/modules/http/routes): choose paths and methods.

[Requests](/docs/modules/http/requests) and [uploads](/docs/modules/http/uploads): map transport
values into input.

[Middleware](/docs/modules/http/middleware) and [rate limits](/docs/modules/http/rate-limits):
apply HTTP policy.

[Responses](/docs/modules/http/responses): map results and declared errors into HTTP responses.

[Raw handlers](/docs/modules/http/raw-handlers): mount adapters that own their HTTP protocol.

[OpenAPI](/docs/modules/http/openapi) and [generated
clients](/docs/modules/http/generated-clients): use the checked contracts outside the server,
with REST and RPC behavior distinguished.

These transport guides build on the same domain organization; they do not introduce a second place
for business handlers.

## Verify routing separately from behavior

From your application's root, run `bun run check` after adding a method. Expect the route to appear in
the checked graph and OpenAPI output. Test the function directly for its domain behavior, then use an
HTTP integration test for mapping, authentication, and status codes.

For a running app containing the Hello route above:

```sh
curl -i http://localhost:3000/hello\?name=RELKIT
```

Expect HTTP `200` and `{ "message": "Hello, RELKIT!" }`. Use your configured backend port if it differs.
The [first-service example](/docs/modules/service/first-service) includes the source and test steps.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/services` API](/docs/api/services)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/commerce/src/routes/orders/route.ts`](https://github.com/rel-kit/relkit/blob/main/examples/commerce/src/routes/orders/route.ts)

---

# Buckets
Source: https://relkit.dev/docs/modules/storage

A bucket stores files such as product images and invoices. Its definition gives the bucket a stable identity and sets its storage rules.

> **Start here**
>
> Start with **[Upload product images](/guides/storage/upload-product-images)** for installation, an
> HTTP endpoint, and verification. For the complete option contract, see
> [`defineBucket`](/docs/api/buckets#definebucket).

## Pre-setup

Use MinIO in local Docker for development. Start from an existing RELKIT app and a running Docker daemon.

1. **Install the storage integration**

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/s3@0.7.13
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. **Configure the assets profile**

    > **Merge with your application**
    >
    > The root configuration helper is [`defineApp`](/docs/learn/concepts/application), not
    > `defineConfig`. Merge the capability entries below into your existing `relkit.config.ts`; keep its
    > ID, environment, profiles, and other settings. The empty `defineEnv({})` in a standalone example
    > means this local provider needs no application variables. Keep your existing environment contract.

    ```ts title="relkit.config.ts"
    /** Local MinIO supplies connection values without application-owned credentials. */
    import { defineApp, defineEnv } from "@relkit/app/config";
    import { docker } from "@relkit/docker";
    import { s3 } from "@relkit/s3";

    export default defineApp({
      env: defineEnv({}),
      bucket: { assets: docker(s3()) },
      defaults: { bucket: "assets" },
    });
    ```

    Buckets with `profile: "assets"`, or no explicit profile, now select local MinIO.
    Docker supplies its endpoint and credentials; no S3 secrets belong in `defineEnv` for this local path.
    For an existing S3 service, follow [connected storage](/docs/modules/storage/local-storage) instead.

3. **Check and start after defining the bucket**

    Check Docker before continuing. After adding the resource and its service registration, run from the app root:

    ```sh title="Terminal — application root"
    docker version
    bun run check
    bun run typecheck
    bun run dev
    ```

    `check` validates the graph; it starts no containers. `dev` starts only Docker recipes used by
    that graph, waits for readiness, and binds their generated connection values. An unused profile
    alone does not start a container. Keep the server running and use `bun run relkit local status`
    in another terminal to inspect the services. [Local Docker](/docs/modules/integrations/local-docker)
    covers detached startup and stopping services while retaining their volumes.

<span id="the-storage-api"></span>

This bucket accepts images and JSON files, with a maximum size of 5 MB per object:

```ts title="src/services/assets/buckets/assets.bucket.ts"
/** Declares private JSON/image assets with a five-million-byte limit for validated upload handlers. */
import { defineBucket } from "@relkit/app/buckets";

const assets = defineBucket({
  id: "assets.objects",
  profile: "assets",
  visibility: "private",
  maxObjectBytes: 5_000_000,
  allowedContentTypes: ["application/json", "image/*"],
});

export default assets;
```

`id` identifies this bucket in RELKIT. Keep it stable when moving or renaming the file.

`profile` selects the storage connection named `assets` in your application configuration. That configuration determines which provider stores the files.

`visibility` controls object visibility. Authentication for an upload endpoint is configured separately.

## Configure storage

[Define or scaffold a bucket](/docs/modules/storage/define): provider selection, limits, and
validation.

[Configure local storage](/docs/modules/storage/local-storage): install the S3 integration and
run MinIO through Docker.

[Write objects](/docs/modules/storage/upload): dependencies, file validation, and storage
operations.

[Read files and create download links](/docs/modules/storage/read-delete): reads, listing,
deletion, and signed URLs.

<span id="try-it-in-your-app"></span>

Ready to configure your own provider? Continue with [Configure local storage](/docs/modules/storage/local-storage).

---

# Define a bucket
Source: https://relkit.dev/docs/modules/storage/define

Give a bucket a stable identity, choose a storage profile, and set the files it accepts.

> **Before you begin**
>
> Start with an [existing application](/docs/learn/create-an-app). Bucket definitions use the base
> app package; configure the selected storage integration before running file operations.

## Pre-setup

Complete [local Docker storage setup](/docs/modules/storage#pre-setup) before using the bucket.
It installs the S3/Docker integrations and adds `bucket.assets` plus `defaults.bucket` to
`defineApp`. Docker supplies the local credentials; keep your existing `defineEnv` contract.
If scaffolding creates a different profile, align it with the definition below.

## Scaffold a bucket

From the application root, with an existing `assets` service:

```sh
bun run relkit add bucket Uploads --service assets --provider s3 --source docker
```

Creates `src/services/assets/buckets/uploads.bucket.ts` and configures Docker MinIO/S3. Without provider
flags, scaffolding reuses an eligible default/unique profile or creates a Docker S3 profile.
A bucket profile can belong to only one bucket; an already-owned profile is rejected.

Edit the generated bucket's visibility and file limits. Keep its `id` and `profile`; the manual
example below defines a different bucket named `assets`. Choose one setup path rather than
adding a second bucket for the same files. For the complete HTTP workflow, follow
[Upload product images](/guides/storage/upload-product-images).

**Choose a different storage provider**

| Selection                               | Command options                               |
| --------------------------------------- | --------------------------------------------- |
| Unused compatible profile               | `--profile uploads`                           |
| Docker MinIO/S3                         | `--provider s3 --source docker`               |
| Connected S3                            | `--provider s3 --source connected`            |
| S3 on an existing AWS/Pulumi deployment | `--provider s3 --source aws`                  |
| Connected Cloudflare R2                 | `--provider cloudflare-r2 --source connected` |

Do not combine `--profile` with `--provider` or `--source`. Cloudflare R2 supports only
`connected`. AWS requires an existing AWS/Pulumi deployment and is not provisioned by this command.
Set connected-profile environment values yourself; the CLI never asks for credentials.
See [Docker startup after adding a resource](/docs/modules/cli/add-artifacts#start-local-resources).
The bucket remains internal; declare it as a function dependency to use it.

For every bucket scaffolding flag, see the [bucket command reference](/docs/api/cli#relkit-add-bucket-name).

The scaffold normally installs the selected owners and checks the app. With `--no-install`, finish
`bun install` and `bun run check`. For manual setup, complete [the selected adapter installation](/guides/storage/upload-product-images#configure-storage)
first. Connected Cloudflare uses [its own package](/docs/modules/integrations), and connected S3 does not
require a Docker materializer or local MinIO process.

## Define the bucket

Use `defineBucket` in your app's domain directory. For the manual path, create
`src/services/assets/buckets/assets.bucket.ts`. If you scaffolded `Uploads`, apply these policy
options to `uploads.bucket.ts` while retaining that bucket's identity and profile:

```ts title="src/services/assets/buckets/assets.bucket.ts"
/** Declares private JSON/image assets with a five-million-byte limit for validated upload handlers. */
import { defineBucket } from "@relkit/app/buckets";

const assets = defineBucket({
  id: "assets.objects",
  profile: "assets",
  visibility: "private",
  maxObjectBytes: 5_000_000,
  allowedContentTypes: ["application/json", "image/*"],
});

export default assets;
```

- `id` is the bucket's stable, unique name. Keep it unchanged when moving or renaming the file.
- `visibility` is required. Start with `"private"` for user uploads.
- `maxObjectBytes` sets the maximum size of one file: 5 MB here.
- `allowedContentTypes` lists accepted media types. `image/*` allows image types; `application/json` allows JSON files.
- `profile` selects a physical bucket configuration in `relkit.config.ts`. This example uses `"assets"`.

Size and content-type limits are optional. For HTTP uploads, also validate incoming files with `z.file()` as shown in [Upload files](/docs/modules/storage/upload).

## Check your bucket

Make sure the descriptor's bucket profile exists in `relkit.config.ts`. The scaffold already
adds its selected profile; the [tutorial's configuration step](/guides/storage/upload-product-images#configure-storage)
shows the `assets` profile used by the manual example.

Then, from your app's root, run:

```sh
bun run check
```

Next, [give a function access to the bucket](/docs/modules/storage/upload). For cloud storage, [configure an integration](/docs/modules/integrations).

---

# Configure local storage
Source: https://relkit.dev/docs/modules/storage/local-storage

Use MinIO when you want S3-compatible file storage on your development machine. You'll need an existing RELKIT application and a running Docker daemon.

1. ## Install the integration

    Run the installation commands from your application directory:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/s3@0.7.13
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

2. ## Add the provider profile

    In `relkit.config.ts`, import `s3` from `@relkit/s3`, `docker` from `@relkit/docker`, and `env as binding` from `@relkit/app/config`. Add this `assets` entry to the `bucket` configuration inside `defineApp()`:

    ```ts title="relkit.config.ts — bucket configuration"
    assets: docker(
      s3({
        endpoint: binding.url("ASSETS_S3_ENDPOINT"),
        bucketName: binding.string("ASSETS_S3_BUCKET"),
        region: binding.string("ASSETS_S3_REGION"),
        credentials: {
          accessKeyId: binding.secret("ASSETS_S3_ACCESS_KEY_ID"),
          secretAccessKey: binding.secret("ASSETS_S3_SECRET_ACCESS_KEY"),
        },
        forcePathStyle: true,
      }),
    ),
    ```

    A **provider profile** is a named connection to the service that stores your files. A bucket with `profile: "assets"` uses this connection.

    In development, `docker(s3(...))` starts the local MinIO recipe when the application needs this profile. It supplies binding-only credentials and loopback ports. Run `bun run check`, then `bun run dev`.

    With `--local=off`, recipes stay disabled and the configured connection values must exist. For connected S3 or Cloudflare R2, follow [provider selection](/docs/modules/storage/define).

3. ## Use the bucket

    Follow [Upload product images](/guides/storage/upload-product-images) to connect the profile to a bucket, function, service, and HTTP endpoint.

---

# Read and delete files
Source: https://relkit.dev/docs/modules/storage/read-delete

Read stored files, create download links, and delete objects through a function's declared bucket client.

> **Before you begin**
>
> Complete the [bucket adapter installation and
> binding](/guides/storage/upload-product-images#configure-storage) first. The upload tutorial
> supplies the selected local profile; connected storage is a separate choice.

## Read a stored file

Add your bucket to `dependencies.buckets`, just as in the [upload function](/docs/modules/storage/upload). Inside the handler, await the method you need:

| Call                                       | Result                                                                      |
| ------------------------------------------ | --------------------------------------------------------------------------- |
| `context.buckets.assets.get(key)`          | File bytes as a `Uint8Array`, or `undefined` if the file is missing.        |
| `context.buckets.assets.head(key)`         | Metadata such as size and content type, or `undefined` if missing.          |
| `context.buckets.assets.exists(key)`       | `true` if the file exists.                                                  |
| `context.buckets.assets.list("products/")` | Keys beginning with `products/`. Omit the prefix to list without filtering. |

Check for `undefined` before using a file. For text or JSON, decode the returned bytes with `new TextDecoder().decode(bytes)`. `get()` loads the file into memory, so use it for files your application can comfortably hold.

## Share a download link

With an S3-compatible provider, `await context.buckets.assets.createReadUrl(key)` creates a temporary download URL. `createWriteUrl(key)` creates a temporary upload URL. Local storage does not support these methods.

Check the current user's permission before issuing either URL. Anyone holding the URL can use it until it expires, so do not log it. Configure expiry through your storage provider, not as an argument to these methods.

## Delete a file

Call `await context.buckets.assets.delete(key)` after checking the user may delete that file. Deletion returns no value; use `exists(key)` if you need to check whether it remains.

Treat deletion as permanent unless you have configured recovery in your storage service. Remove or update any database record that refers to the deleted key.

After adding storage operations to your function, run from your app's root:

```sh
bun run check
bun run test
```

---

# Upload files
Source: https://relkit.dev/docs/modules/storage/upload

Give a function access to a bucket, then write file bytes under an object key.

> **Before you begin**
>
> Complete the [bucket adapter installation and
> binding](/guides/storage/upload-product-images#configure-storage) first. The upload tutorial
> supplies the selected local profile; connected storage is a separate choice.

## Save files from a function

Import your [bucket](/docs/modules/storage/define) and add it to `dependencies.buckets`. The name `assets` makes it available as `context.buckets.assets`.

This function accepts a primary image and attachments, writes their bytes, and returns their keys:

```ts title="src/services/assets/functions/upload-assets.function.ts"
/** Validates multipart image files, writes them through the declared assets bucket and returns their uploaded names. */
import { defineFunction } from "@relkit/app/functions";
import { z } from "@relkit/app/schema";
import assets from "../buckets/assets.bucket.js";

const uploadedFile = z.file({
  maxBytes: 1024 * 1024 * 10,
  mediaTypes: ["image/jpeg", "image/png"],
});

const uploadAssets = defineFunction({
  input: z.object({
    label: z.string().min(1),
    primary: uploadedFile,
    attachments: z.array(uploadedFile),
  }),

  output: z.object({
    label: z.string(),
    files: z.array(z.string()),
  }),

  dependencies: { buckets: { assets } },

  handler: async ({ label, primary, attachments }, context) => {
    const files = [primary, ...attachments];

    // This demo uses filenames as keys; uploading the same name replaces the file.
    await Promise.all(
      files.map(async (file) =>
        context.buckets.assets.put(file.name, new Uint8Array(await file.arrayBuffer()), {
          contentType: file.type,
        }),
      ),
    );

    return { label, files: files.map(({ name }) => name) };
  },
});

export default uploadAssets;
```

`put()` takes a key, a `Uint8Array`, and optional settings such as `contentType` and `metadata`. Await it before reporting a successful upload.

## Choose keys safely

This example uses filenames as keys. Uploading `cover.png` again replaces the existing file. In a multi-user app, generate keys on the server—for example, `users/<user-id>/<random-id>.png`—and save the original display name separately.

Authorize uploads before writing. A declared content type does not prove a file is safe; inspect its contents when your app requires it.

## Connect an upload endpoint

Use a route with `accept: "multipart/form-data"`. The [image-upload tutorial](/guides/storage/upload-product-images) includes the service, route, and curl request.

The HTTP body limit covers the whole request; file-schema and bucket limits apply to individual files. Keep uploads below all applicable limits. See [HTTP uploads](/docs/modules/http/uploads) for request validation details.

---

# Guides
Source: https://relkit.dev/guides

Choose the task you want to complete. Each guide names its prerequisites, shows the files to change, and gives you a command or test to verify the result.

If you haven't created an application yet, start with [Build your first API](/docs/learn).

**[Call your API from React](/guides/frontend/connect-react)**

Pull backend types, connect the client provider, and display your first response.

**[Create and build an API](/guides/cli/create-and-build-an-api)**

Use the CLI to add an endpoint, verify its response, and run a production build.

**[Upload product images](/guides/storage/upload-product-images)**

Accept multipart uploads, store two images, and verify their object keys.

**[Cache product prices](/guides/caching/cache-product-prices)**

Reuse a price lookup with a typed cache and a local Redis provider.

**[React to order events](/guides/events/react-to-order-events)**

Publish an order event and run an independent listener.

**[Register users in a transaction](/guides/database/register-users-in-a-transaction)**

Validate input and write related records as one operation.

**[Add email and password sign-in](/guides/auth/email-password-sign-in)**

Register a user, sign in, and check a protected endpoint.

**[Build an offline agent](/guides/ai/build-an-offline-agent)**

Add tools and test an agent without a model API key.

---

# Build an offline agent
Source: https://relkit.dev/guides/ai/build-an-offline-agent

Add a greeting assistant to your existing RELKIT app. It combines a native LangChain model, native
middleware and tool, and a RELKIT function-backed tool. The small example runs without a database,
network request, or paid model call.

> **Before you begin**
>
> You'll need an existing RELKIT application and Bun 1.3.10 or later. The example uses an offline
> model; no model API key is required.

Create the files below, or update them if they already exist. Run commands from your app's root.
The minimal app does not include the optional native execution packages. Install `@relkit/langchain`
and its selected SDK peers first; `@relkit/local` supplies the explicit profiles used below.

1. ## 1. Install the native packages [#install-the-native-packages]

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @langchain/core@1.2.9 @langchain/langgraph@1.4.14 @relkit/langchain@0.7.15 @relkit/local@0.7.14 langchain@1.5.10 langsmith@0.10.8
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    The minimal starter already has development-only `@relkit/testing`; its generic harness does not
    provide the native engine. The offline test below imports `invokeAgent` from `@relkit/langchain`.

2. ## 2. Configure the runtime [#configure-the-runtime]

    Extend the existing `relkit.config.ts` with the `localRealtime`/`localAgentState` imports, `realtime`
    and `agent-state` profiles, and matching entries in `defaults`. This small maintained example shows
    the required bindings. Preserve your existing environment, server settings, defaults and other
    provider profiles when merging it:

    ```ts title="relkit.config.ts — merge native agent bindings"
    /** Selects agent runtime bindings without enabling an inspector tool or bridge. */
    import { defineApp } from "@relkit/app/config";
    import { localAgentState, localRealtime } from "@relkit/local";
    import env from "@app/platform/env.js";
    // relkit:create:deployment-imports

    export default defineApp({
      env,
      realtime: localRealtime(),
      "agent-state": localAgentState(),
      defaults: { realtime: "default", "agent-state": "default" },
      telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
      server: { port: 3000, maxBodyBytes: 1_048_576, apiDocs: { ui: "scalar" } },
      // relkit:create:deployment
    });
    ```

    The two `default` profiles are explicit local choices for this exercise. They do not install or
    enable an Inspector, and they are not a production persistence/deployment selection.

3. ## 3. Add the greeting function [#add-the-greeting-function]

    ```ts title="src/services/hello/functions/hello.function.ts"
    /** Returns a validated named greeting and logs each invocation through RELKIT's request context. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const hello = defineFunction({
      id: "hello.greet",

      input: z.object({ name: z.string().min(1).default("world") }),
      output: z.object({ message: z.string() }),

      /**
       * Logs the greeting invocation and returns the validated greeting response.
       * @param input - Validated name from the function schema.
       * @param context - RELKIT invocation context owning structured logging.
       * @returns Greeting response matching the output schema.
       */
      handler: async ({ name }, context) => {
        context.log.info("hello invoked", { name });

        return { message: `Hello, ${name}!` };
      },
    });

    export default hello;
    ```

4. ## 4. Make it a tool [#make-it-a-tool]

    ```ts title="src/services/hello/tools/lookup.tool.ts"
    /** Exposes the hello function as a read-only greeting tool with its existing two-second timeout. */
    import hello from "@app/services/hello/functions/hello.function.js";

    export default hello.asTool({
      id: "hello.lookup",
      description: "Read a greeting for a supplied name",

      sideEffect: "read",
      approval: "never",
      timeoutMs: 2_000,
    });
    ```

    The tool tells the model what the function does. Its input and output come from the function.

5. ## 5. Add the agent [#add-the-agent]

    ```ts title="src/services/hello/agents/assistant.agent.ts"
    /** Runs an offline greeting agent with RELKIT/native tools, todo middleware and public state observation. */
    import { defineAgent } from "@relkit/langchain";
    import { z } from "@relkit/app/schema";
    import { FakeToolCallingModel, todoListMiddleware, tool } from "langchain";
    import lookup from "@app/services/hello/tools/lookup.tool.js";

    export const uppercase = tool(async ({ text }: { readonly text: string }) => text.toUpperCase(), {
      name: "uppercase",
      description: "Uppercase text without leaving the process",
      schema: z.object({ text: z.string() }),
    });

    export default defineAgent({
      id: "hello.assistant",

      input: z.object({ message: z.string().min(1) }),
      output: z.object({ answer: z.string() }),

      model: new FakeToolCallingModel({
        toolCalls: [
          [
            {
              name: "write_todos",
              args: { todos: [{ content: "Answer the greeting", status: "completed" }] },
              id: "todo-1",
            },
          ],
          [
            {
              name: "relkit_output",
              args: { value: { answer: "Hello from the offline LangChain model." } },
              id: "output-1",
            },
          ],
        ],
      }),
      instructions: "Answer greeting questions with the available tools.",
      tools: [lookup, uppercase],
      middleware: [todoListMiddleware()],
      stateProfile: "default",
      client: {
        public: true,
        state: ["todos"],
        events: { notice: z.object({ message: z.string() }) },
      },
      chat: { input: "message", output: "answer" },
      controls: ["stop"],

      limits: {
        maxSteps: 4,
        maxToolCalls: 4,
        timeoutMs: 10_000,
      },
    });
    ```

    The agent can use the RELKIT `hello.lookup` tool and native `uppercase` tool. Its real
    `todoListMiddleware()` state is selected for the typed client, and each run has limits on steps, calls,
    and time.

6. ## 6. Test without a model key [#test-without-a-model-key]

    The test scripts a tool call and a final answer, while running the real greeting function:

    ```ts title="tests/unit/assistant.agent.test.ts"
    /** Checks assistant.agent through the supported public RELKIT APIs. */
    import { expect, test } from "bun:test";
    import { invokeAgent } from "@relkit/langchain";
    import assistant, { uppercase } from "@app/services/hello/agents/assistant.agent.js";
    import lookup from "@app/services/hello/tools/lookup.tool.js";

    test("assistant runs native tools and todo middleware without a paid provider", async () => {
      expect(assistant.tools).toEqual([expect.objectContaining({ ref: lookup.ref }), uppercase]);
      expect(assistant.middleware.map((middleware) => middleware.name)).toEqual(["todoListMiddleware"]);
      expect(assistant.client?.state).toEqual(["todos"]);
      expect(assistant.limits).toEqual({ maxSteps: 4, maxToolCalls: 4, timeoutMs: 10_000 });

      await expect(
        invokeAgent({
          agent: assistant,
          input: { message: "Greet Ada" },
          threadId: "test:assistant",
          tools: [lookup],
          engine: { invoke: async () => ({ message: "Hello, Ada!" }) },
        }),
      ).resolves.toEqual({ answer: "Hello from the offline LangChain model." });
    });
    ```

    ```sh
    bun test ./tests/unit/assistant.agent.test.ts
    ```

    Expect a passing test with the answer `Hello from the offline LangChain model.` This checks native model
    execution, todo middleware, and RELKIT tool registration; it does not measure how a production model
    interprets questions.

## Optional: call it from a typed client [#call-it-from-a-typed-client]

This frontend is optional. Complete [React client installation](/docs/modules/client) in a separate frontend
package before copying its code. The fullstack sources are a maintained reference, not an offered
creation tuple; the backend tutorial continues to use your existing app.

Keep caller-owned thread IDs separate from internal execution IDs:

```ts title="web/app/agent-config.ts"
export const agentThreadIds = {
  assistant: "demo:assistant",
  review: "demo:review",
} as const;

export const agentTransports = ["sse", "websocket"] as const;
export type AgentTransport = (typeof agentTransports)[number];
```

The fullstack example uses that identity for every run, reconnect, stop, and resume call:

[Complete typed-agent UI](https://github.com/rel-kit/relkit/blob/main/templates/default/v1/fullstack/web/app/page.tsx)

## Optional: use a production model [#use-a-production-model]

Skip this step if you only want the offline example. Install the LangChain model package for your
provider, construct its compatible chat model in server code, and pass that instance or a lazy factory to
`model`. Provider credentials remain server-only and live calls may cost money. For
[MCP only](/docs/modules/ai/mcp), use the function-backed tool without adding an agent.

Do not put a key in the agent's instructions or commit it to source control. Tests should continue to
inject or declare deterministic native models explicitly; no environment name silently selects a paid
provider.

```sh
bun run check
bun run dev
```

Optionally follow the separate [Inspector installation and bridge setup](/docs/modules/operations/inspector).
After starting that tool independently, open its UI, normally at `http://localhost:3210`. Under **Agents**, select
`hello.assistant` to inspect its tools, middleware state, and execution. To let an external AI client call
the greeting function directly, follow [Tools over MCP](/docs/modules/ai/mcp).

## Related tasks

[Expose a tool over MCP](/docs/modules/ai/mcp), or [require approval for sensitive
actions](/docs/modules/ai/approvals).

---

# Add email and password sign-in
Source: https://relkit.dev/guides/auth/email-password-sign-in

Add authentication to an existing RELKIT app using the executable `examples/auth-drizzle` application.
The result is a public auth API, a small session operation, and an application route that requires
sign-in. This local tutorial uses Bun and SQLite, with no external identity or email provider.

> **Before you begin**
>
> You'll need an existing RELKIT application, Bun 1.3.10 or later, and a new local SQLite database
> for this example. Keep any existing database and migration history intact.

Use the standard `@app/*` alias. If needed, follow [Create an app](/docs/learn/create-an-app) first.
Preserve existing environment fields, service members, routes, and table exports. If your app already
has a Drizzle or Better Auth service, extend it rather than adding a second one.

1. ## 1. Scaffold the auth baseline [#scaffold-the-auth-baseline]

    The CLI can create the default email/password Better Auth service and `/api/auth` catch-all route:

    ```sh
    bun run relkit add auth --adapter better-auth --database-dialect sqlite
    ```

    It reuses the single statically discoverable Drizzle service. When none exists, it creates one with the
    Better Auth tables instead of the generic `items` table; PostgreSQL and MySQL are also supported. The
    command adds blank `BETTER_AUTH_SECRET` and safe `BETTER_AUTH_URL` examples, but never generates a secret
    or runs migrations. Complete the reported environment and migration next steps before starting auth.

    It normally installs the selected SDKs, declaration peers, Drizzle patch and Better Fetch override,
    then checks the project. If you use `--no-install`, finish with `bun install` and `bun run check`
    before continuing. Installing only the RELKIT wrapper does not supply the native SDK or its repairs.

    `--adapter` accepts only `better-auth`. `--database-dialect` chooses SQLite (the default),
    PostgreSQL, or MySQL when creating the database; an existing Drizzle service must be compatible.
    The default `--base-path /api/auth` produces
    `src/routes/api/auth/[[...auth]]/route.ts`. Use `--base-path /session-auth` for a different mount.

    Auth is a singleton under the detected service root: `src/services/auth` in grouped apps and
    `src/auth` in existing flat apps. `--service` and `--create-service` do not select its location.
    A second auth service or conflicting schema exports are rejected without overwriting them.
    The scaffold enables email/password only; add other providers and protection rules in source.

    For every scaffolding flag, see the [CLI reference](/docs/api/cli).

2. ## 2. Prepare the database and environment [#prepare-the-database-and-environment]

    The scaffold above already handles installation. If you are creating these files manually, use
    [Better Auth service](/docs/modules/auth/better-auth#install-compatible-packages) as the alternative setup path.
    Add the environment fields to your existing configuration:

    ```ts title="relkit.config.ts"
    /** Declares auth/database environment requirements without selecting inspection. */
    import { defineApp, defineEnv, env } from "@relkit/app/config";

    export default defineApp({
      env: defineEnv({
        DATABASE_PATH: env.string().default("./auth.sqlite"),
        BETTER_AUTH_SECRET: env.secret(),
        BETTER_AUTH_URL: env.url().default(new URL("http://127.0.0.1:3000")),
      }),
      server: { port: 3000 },
    });
    ```

    From your application root, choose a fresh local database and supply a local secret:

    ```sh
    export DATABASE_PATH=./auth.sqlite
    export BETTER_AUTH_URL=http://127.0.0.1:3000
    export BETTER_AUTH_SECRET="$(openssl rand -base64 32)"
    ```

    Keep these values for the server commands below. The generated secret starts a fresh local exercise;
    store a stable secret securely for subsequent runs. Do not commit it or the SQLite file.

    Add the authentication tables to the database schema:

    ```ts title="src/services/database/schema/index.ts"
    /** Declares native Better Auth SQLite user/session/account/verification tables, retaining timestamp modes and account uniqueness. */
    import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";

    const timestamps = {
      createdAt: integer({ mode: "timestamp" }).notNull(),
      updatedAt: integer({ mode: "timestamp" }).notNull(),
    };

    export const user = sqliteTable("user", {
      id: text().primaryKey(),
      name: text().notNull(),
      email: text().notNull().unique(),
      emailVerified: integer({ mode: "boolean" }).notNull(),
      image: text(),
      ...timestamps,
    });

    export const session = sqliteTable("session", {
      id: text().primaryKey(),
      expiresAt: integer({ mode: "timestamp" }).notNull(),
      token: text().notNull().unique(),
      ipAddress: text(),
      userAgent: text(),
      userId: text().notNull(),
      ...timestamps,
    });

    export const account = sqliteTable(
      "account",
      {
        id: text().primaryKey(),
        accountId: text().notNull(),
        issuer: text().notNull(),
        providerId: text().notNull(),
        userId: text().notNull(),
        accessToken: text(),
        refreshToken: text(),
        idToken: text(),
        accessTokenExpiresAt: integer({ mode: "timestamp" }),
        refreshTokenExpiresAt: integer({ mode: "timestamp" }),
        scope: text(),
        password: text(),
        ...timestamps,
      },
      (table) => [uniqueIndex("account_issuer_account_id").on(table.issuer, table.accountId)],
    );

    export const verification = sqliteTable("verification", {
      id: text().primaryKey(),
      identifier: text().notNull(),
      value: text().notNull(),
      expiresAt: integer({ mode: "timestamp" }).notNull(),
      ...timestamps,
    });
    ```

    Keep the direct `user`, `session`, `account`, and `verification` exports. These definitions match the
    example's installed Better Auth version, including the account `issuer` field. They are not a drop-in
    replacement for an existing business `users` table. Read [Database integration](/docs/modules/database/better-auth)
    before adapting IDs, custom fields, or existing accounts. The example does not declare foreign keys.

    Add or extend the database service:

    ```ts title="src/services/database/service.ts"
    /** Lazily opens the configured SQLite client for native auth tables and closes that owned client on disposal. */
    import { Database } from "bun:sqlite";
    import { defineDrizzleService } from "@relkit/drizzle";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import * as schema from "./schema/index.js";

    export default defineDrizzleService({
      schema,
      client: ({ env }) => {
        const sqlite = new Database(env.DATABASE_PATH);
        return drizzle({ client: sqlite });
      },
      dispose: (database) => database.$client.close(),
    });
    ```

    This service opens and closes the connection. Table creation belongs to migration tooling, not startup.

3. ## 3. Generate and apply migrations [#generate-and-apply-migrations]

    Add the Drizzle Kit configuration, or merge its schema entry point into your existing configuration:

    ```ts title="drizzle.config.ts"
    /** Points native Drizzle tooling at grouped auth tables and requires an explicit persistent SQLite target before migration. */
    import { defineConfig } from "drizzle-kit";

    const path = process.env.DATABASE_PATH;
    if (path === undefined || path.trim() === "" || path === ":memory:") {
      throw new Error("Set DATABASE_PATH to the persistent SQLite file you intend to migrate");
    }

    export default defineConfig({
      schema: "./src/services/database/schema/index.ts",
      dialect: "sqlite",
      out: "./src/services/database/migrations",
      dbCredentials: { url: path },
    });
    ```

    From your app root, with `DATABASE_PATH` still set:

    ```sh
    bun --bun drizzle-kit generate --name=auth
    ```

    Review the generated migration before applying it:

    ```sh
    bun run relkit db migrate
    ```

    Commit SQL and required metadata under `src/services/database/migrations`, shared
    by auth and business tables, with your schema. The installed command owns the runner;
    scaffolding does not apply SQL or generate secrets. If running the repository's existing example,
    the initial migration is already present: use `bun run db:migrate` without generating another one.
    See [Migrations](/docs/modules/database/migrations) for changes to an existing database and deployment sequencing.

4. ## 4. Add the auth service and mount [#add-the-auth-service-and-mount]

    Create `src/services/auth/service.ts`:

    ```ts title="src/services/auth/service.ts"
    /** Configures email/password Better Auth against the sole database, borrowing URL and secret from server configuration. */
    import { defineBetterAuthService } from "@relkit/better-auth";

    export default defineBetterAuthService({
      baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
      // Better Auth reads BETTER_AUTH_SECRET from the server process environment.
      emailAndPassword: { enabled: true },
    });
    ```

    Mount its raw handler:

    ```ts title="src/routes/api/auth/[[...auth]]/route.ts"
    /** Mounts native Better Auth once for all methods and protects the declared account, order and MCP paths. */
    import { defineRoute } from "@relkit/app/routes";
    import auth from "@app/services/auth/service.js";

    export const ALL = defineRoute({
      handler: auth.handler,
      auth: { protected: ["/account/*", "/orders/*", "/mcp"] },
    });
    ```

    This creates the auth mount at `/api/auth` and requires sessions on the listed application paths.
    `/orders/*` and `/mcp` are examples of additional protected paths; they do not create those endpoints.
    Do not set `database` or `basePath` on the service itself.

    Run `bun run check` now to generate auth/database context types before adding the consuming function.

5. ## 5. Add a session operation and application routes [#add-a-session-operation-and-application-routes]

    Create the function in the Account domain:

    ```ts title="src/services/account/functions/session.function.ts"
    /** Reads the invocation's native session and returns validated authentication and user identity fields. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      input: z.object({}),
      output: z.object({ authenticated: z.boolean(), userId: z.string().optional() }),
      handler: async (_input, context) => {
        const session = await context.auth.getSession();
        return session === null
          ? { authenticated: false }
          : { authenticated: true, userId: session.user.id };
      },
    });
    ```

    Expose it through the owning service:

    ```ts title="src/services/account/service.ts"
    /** Exposes native session observation as the account boundary used by profile and session routes. */
    import { defineService } from "@relkit/app/services";
    import session from "./functions/session.function.js";

    export default defineService({ functions: { session } });
    ```

    Add the public optional-session route:

    ```ts title="src/routes/session/route.ts"
    /** Maps session GET requests to account session observation, including the explicit anonymous result. */
    import { defineRoute } from "@relkit/app/routes";
    import account from "@app/services/account/service.js";

    export const GET = defineRoute({ target: account.session });
    ```

    Add a protected route targeting the same operation:

    ```ts title="src/routes/account/profile/route.ts"
    /** Maps protected profile GET requests to the account service's native session observation. */
    import { defineRoute } from "@relkit/app/routes";
    import account from "@app/services/account/service.js";

    export const GET = defineRoute({ target: account.session });
    ```

    The operation handles `null`; HTTP admission makes `/account/profile` require a session while `/session`
    remains public. This example reports identity only. Add [business permission checks](/docs/modules/auth/protect-routes#enforce-permissions-in-the-business-operation)
    before exposing real account or other protected data.

6. ## 6. Check and run the application [#check-and-run-the-application]

    Use [Auth testing](/docs/modules/auth/testing) to add the executable test to your app; it already exists in the
    repository example. Then run from the app root:

    ```sh
    bun run check
    bun run typecheck
    bun test tests/auth.test.ts
    bun run dev
    ```

    The test uses its own migrated temporary database; it does not create accounts in the running server.
    Use the backend's actual port if it differs from `3000`, and keep `BETTER_AUTH_URL` consistent.

7. ## 7. Verify sign-up, protected access, and sign-out [#verify-sign-up-protected-access-and-sign-out]

    In a second terminal, start a temporary cookie jar and check the signed-out state:

    ```sh
    auth_cookies=$(mktemp -t relkit-auth-cookies)
    curl -i http://127.0.0.1:3000/account/profile
    curl http://127.0.0.1:3000/session
    ```

    Expect HTTP `401` for the profile and `{ "authenticated": false }` for the public operation.
    Create an account and save the response cookie:

    ```sh
    curl -i -c "$auth_cookies" http://127.0.0.1:3000/api/auth/sign-up/email \
      -H 'content-type: application/json' \
      -H 'origin: http://127.0.0.1:3000' \
      --data '{"name":"Demo","email":"demo@example.com","password":"local-demo-password-123"}'
    curl -b "$auth_cookies" http://127.0.0.1:3000/account/profile
    ```

    Expect sign-up HTTP `200` with a session cookie, then a profile containing `authenticated: true` and
    the generated user ID. This tutorial does not require email verification. The account persists across
    restarts; use a new email for another sign-up or sign in to the existing account.

    Sign out and confirm that the same previously issued cookie no longer admits the protected request:

    ```sh
    curl -i -b "$auth_cookies" http://127.0.0.1:3000/api/auth/sign-out \
      -H 'content-type: application/json' \
      -H 'origin: http://127.0.0.1:3000' --data '{}'
    curl -i -b "$auth_cookies" http://127.0.0.1:3000/account/profile
    ```

    Expect sign-out HTTP `200`, then profile HTTP `401`. Sign in again and replace the cookie jar:

    ```sh
    curl -i -c "$auth_cookies" http://127.0.0.1:3000/api/auth/sign-in/email \
      -H 'content-type: application/json' \
      -H 'origin: http://127.0.0.1:3000' \
      --data '{"email":"demo@example.com","password":"local-demo-password-123"}'
    curl -b "$auth_cookies" http://127.0.0.1:3000/account/profile
    rm "$auth_cookies"
    ```

    Expect an authenticated profile again. The final command removes only this exercise's temporary cookie
    jar, not the account or database. These credentials and raw response displays are for an isolated local
    exercise; do not print real users' tokens in shared terminals or logs.

    For the browser flow, see [Clients](/docs/modules/auth/clients). The repository example also serves a small
    page at `http://127.0.0.1:3000` with sign-up, sign-in, sign-out, and session buttons. Finish with
    [Customization](/docs/modules/auth/customization) before deploying: configure delivery, providers, cookies,
    rate limiting, persistent storage, and the permission rules your product needs.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/better-auth` API](/docs/api/better-auth)
- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/auth-drizzle/README.md`](https://github.com/rel-kit/relkit/blob/main/examples/auth-drizzle/README.md)

## Related tasks

Use the session to [protect application routes](/docs/modules/auth/protect-routes), then try
[Upload product images](/guides/storage/upload-product-images).

---

# Cache product prices
Source: https://relkit.dev/guides/caching/cache-product-prices

Add a product-price lookup to your application. You'll load a price, reuse it for one minute, and verify that it loads again after expiration. This example uses a fixed price, so it needs no database.

> **Before you begin**
>
> Continue from the [Orders endpoint](/docs/learn/first-route), so the Orders service already
> exists. Create the two files below, or update them if they already exist. Run commands from your
> app's root. This selected local profile requires a running Docker daemon and uses Redis.

1. ## 1. Configure caching [#configure-caching]

    Install the local Redis integration from your app root:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/redis@0.8.3
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    In `relkit.config.ts`, import `redis` from `@relkit/redis`, `docker` from `@relkit/docker`, and
    `env as binding` from `@relkit/app/config`. Create a `cache` object inside `defineApp()` if the
    app has none, then add this `requests` entry. It is the only cache profile needed here:

    ```ts title="relkit.config.ts — cache configuration"
    requests: docker(redis({ url: binding.secret("REQUESTS_REDIS_URL") })),
    ```

    The excerpt is from the larger commerce example, which also has a `timeline` profile. Do not add
    that second profile here. `requests` starts a Docker Redis recipe during local development;
    `orders.prices` selects it explicitly. Connected or cloud-owned profiles are covered in
    [Define a cache](/docs/modules/caching/define).

2. ## 2. Define the prices cache [#define-the-prices-cache]

    ```ts title="src/services/orders/cache/prices.cache.ts"
    /** Declares integer SKU prices in the requests cache profile with a one-minute default and five-minute maximum TTL. */
    import { defineCache } from "@relkit/app/cache";
    import { z } from "@relkit/app/schema";

    const prices = defineCache({
      id: "orders.prices",
      profile: "requests",
      key: z.object({ sku: z.string() }),
      value: z.number().int().nonnegative(),

      defaultTtlMs: 60_000,
      maxTtlMs: 300_000,
    });

    export default prices;
    ```

    Each product code has its own cached price, which expires one minute after it is saved.

3. ## 3. Add the lookup function [#add-the-lookup-function]

    ```ts title="src/services/orders/functions/get-price.function.ts"
    /** Exercises the real prices dependency with a logged cache-miss producer and validated SKU/price results. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import prices from "@app/services/orders/cache/prices.cache.js";

    const getPrice = defineFunction({
      id: "orders.get-price",

      input: z.object({ sku: z.string().min(1) }),
      output: z.object({ sku: z.string(), unitPriceCents: z.number().int().nonnegative() }),

      dependencies: { cache: { prices } },

      handler: async ({ sku }, context) => {
        const unitPriceCents = await context.cache.prices.getOrSet({ sku }, async () => {
          // Runs on a cache miss. Replace the demo price with your database lookup.
          context.log.info("price.loaded", { sku });
          return 1_000;
        });

        return { sku, unitPriceCents };
      },
    });

    export default getPrice;
    ```

    The `price.loaded` log runs only when the callback loads a price.

4. ## 4. Expose a price endpoint [#expose-a-price-endpoint]

    In `src/services/orders/service.ts`, import the function and add `getPrice` to the existing
    `functions` object. Keep the service's other members:

    ```ts title="src/services/orders/service.ts — new import"
    import getPrice from "./functions/get-price.function.js";
    ```

    Create `src/routes/prices/route.ts`:

    ```ts title="src/routes/prices/route.ts"
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { GET } = defineServiceRoutes(orders, {
      GET: { member: "getPrice" },
    });
    ```

5. ## 5. Try a miss and a hit [#try-a-miss-and-a-hit]

    Check and start the app:

    ```sh
    bun run check
    ```

    ```sh
    bun run dev
    ```

    Docker is contacted only after the checked plan exists. To prove there is no hidden fallback, use
    `bun run dev --local=off`; startup then requires the named connected/infrastructure values.

    In a second terminal, send the same request twice:

    ```sh
    curl http://localhost:3000/prices\?sku=book-demo
    curl http://localhost:3000/prices\?sku=book-demo
    ```

    Expect this output:

    ```json
    { "sku": "book-demo", "unitPriceCents": 1000 }
    ```

    Look for `price.loaded` with `sku=book-demo` in the app terminal. The second request within one minute returns the same output without another `price.loaded` log. Use a new SKU if this key was already cached from an earlier run.

6. ## 6. Inspect expiration [#inspect-expiration]

    Optionally complete [Inspector setup](/docs/modules/operations/inspector). Open **Cache**, select `orders.prices`, and find the key containing `book-demo`. Its remaining TTL is the time before the cached value expires. Click **View value** to see `1000`.

    Once the minute has passed, repeat the curl request with the same SKU. A new `price.loaded` log confirms the price was loaded again. The next request performs the reload; nothing refreshes in the background.

    Tests must pass an explicit replacement for the `requests` profile; no test environment selects
    a fake for you. In your app, replace the fixed price with a database lookup and
    [invalidate the cached price after updates](/docs/modules/caching/expiration). Before deploying, review which
    profiles are connected and which are infrastructure-owned in [Integrations](/docs/modules/integrations).

## Related tasks

[Invalidate prices after an update](/docs/modules/caching/expiration), or [react to order
events](/guides/events/react-to-order-events).

---

# Create and build an API
Source: https://relkit.dev/guides/cli/create-and-build-an-api

Create an application, add `GET /ping`, and call the same endpoint in development and from a production build. You will use the CLI installed in the application.

> **Before you begin**
>
> You need Bun **1.3.10 or later**, an internet connection to install packages, two terminals, and
> port **3000** available. This example needs no Docker services or cloud credentials.

1. ## 1. Create the application [#create-the-application]

    From the directory where you keep projects, run:

    ```sh title="Terminal 1 — projects directory"
    bunx create-relkit@latest relkit-cli-demo
    cd relkit-cli-demo
    cp .env.example .env
    ```

    The generator installs the minimal starter and its local CLI. If prompted, confirm the new destination. Keep this terminal in `relkit-cli-demo` for the remaining commands. For an existing minimal application, use its root directory and keep its current `.env`.

    [Creation options](/docs/modules/cli/create-an-app) explains deferred installation, Git initialization, and supported starter choices.

2. ## 2. Add an endpoint [#add-an-endpoint]

    Inspect the command, then create a new route:

    ```sh title="Terminal 1 — relkit-cli-demo"
    bun run relkit add route --help
    bun run relkit add route /ping --mode route
    ```

    The second command creates `src/routes/ping/route.ts` with a `GET` handler that returns `{ "ok": true }`. The directory determines the URL. `--mode route` selects a standalone HTTP handler, which is useful for this small response. For business operations with input and output schemas, use a [service-backed route](/docs/modules/http/first-route).

    If `/ping` already exists, choose a new path and use that path in the requests below. Scaffolding rejects collisions instead of overwriting existing files.

3. ## 3. Check the application [#check-the-application]

    Run these checks from the same directory:

    ```sh title="Terminal 1 — relkit-cli-demo"
    bun run check
    bun run typecheck
    bun run test
    ```

    All three commands should finish successfully. `check` validates the application's structure, `typecheck` checks TypeScript, and `test` runs the starter tests. Adding a route does not generate tests for that route; you will verify its response next. See [Testing](/docs/modules/operations/testing) when adding behavior of your own.

4. ## 4. Run and call the endpoint [#run-and-call-the-endpoint]

    Start development:

    ```sh title="Terminal 1 — relkit-cli-demo"
    bun run dev
    ```

    Keep it running. When the server is ready, send a request from the second terminal:

    ```sh title="Terminal 2"
    curl -i http://localhost:3000/ping
    ```

    Expect **HTTP 200** and this JSON body:

    ```json
    { "ok": true }
    ```

    If connection fails, wait for readiness and check Terminal 1 for diagnostics. If the response is `404`, check the route directory and whether validation succeeded. [Troubleshooting](/docs/modules/operations/troubleshooting) explains how to follow diagnostics back to the file to repair.

5. ## 5. Build and run production output [#build-and-run-production-output]

    In Terminal 1, press **Ctrl+C** to stop development. Build and start from the same application directory:

    ```sh title="Terminal 1 — relkit-cli-demo"
    bun run build
    bun run start
    ```

    The build writes `.relkit/build`; `start` runs that output. When it is ready, repeat the request in Terminal 2:

    ```sh title="Terminal 2"
    curl -i http://localhost:3000/ping
    ```

    Expect **HTTP 200** and `{ "ok": true }` again. Production does not watch source changes: rebuild after editing. Press **Ctrl+C** in Terminal 1 when finished. Building and starting locally do not deploy the application.

## Related tasks

Add business behavior with [Your first service](/docs/modules/service/first-service).

Choose another capability in [Add application files](/docs/modules/cli/add-artifacts).

Follow the full [Orders tutorial](/docs/learn) for persistence, authentication, and tests.

Look up flags in the [command reference](/docs/api/cli), including
[`dev`](/docs/api/cli#relkit-dev), [`check`](/docs/api/cli#relkit-check),
[`build`](/docs/api/cli#relkit-build), and [`start`](/docs/api/cli#relkit-start).

---

# Register users in a transaction
Source: https://relkit.dev/guides/database/register-users-in-a-transaction

Add a Users database to an existing RELKIT app using the executable data-model example. You will define
tables, generate migrations, add a custom query and an override, and use the generated CRUD schemas
in a member-registration transaction. You will expose a read operation and verify the result.

> **Before you begin**
>
> You'll need an existing RELKIT application, Bun 1.3.10 or later, and a new local SQLite database.
> The final test verifies that registration writes both records and rolls back on failure.

Use an installed app with the standard `@app/*` alias. If needed, follow [Create an app](/docs/learn/create-an-app).
If a database service already exists, extend it instead of adding a second one. Preserve existing schema,
environment fields, public service members, and routes.

1. ## 1. Scaffold the database baseline [#scaffold-the-database-baseline]

    From an existing application root, the CLI can create the Drizzle service, dialect-specific `items`
    table, migration configuration, environment contract, ignore rules, dependencies, and database scripts:

    ```sh
    bun run relkit add database --orm drizzle --dialect sqlite
    ```

    Use `postgresql` or `mysql` for the other Bun-native Drizzle clients. The command installs packages and
    runs `relkit check`, but deliberately does not create or apply a migration. Run the reported
    `db:generate` and `db:migrate` next steps only after reviewing the schema and setting `DATABASE_PATH` or
    `DATABASE_URL`. To follow the richer Users tutorial below, replace the generated `items` placeholder with
    the shown Users and Memberships schema instead of adding a second database service.

    The scaffold also registers the application-owned Drizzle declaration patch. If you selected
    `--no-install`, run `bun install` and `bun run check` before continuing. A skipped installation
    has not verified the project. The separate [manual setup](/docs/modules/database/define) is for apps
    where you are creating the service yourself; it is not an extra prerequisite after this scaffold.

    SQLite is the headless default and uses `bun:sqlite`; PostgreSQL and MySQL use
    `drizzle-orm/bun-sql`. `--orm` accepts only `drizzle`. Database is a singleton under
    the detected service root: `src/services/database` in grouped apps or `src/database` in existing flat
    apps. `--service` and `--create-service` do not select its location.

    For every scaffolding flag, see the [CLI reference](/docs/api/cli).

2. ## 2. Prepare SQLite and the environment [#prepare-sqlite-and-the-environment]

    The scaffold has already installed the compatible adapter, ORM and migration tooling. For a manual
    installation, complete [Define a Drizzle service](/docs/modules/database/define) instead. This tutorial uses
    Bun's built-in SQLite driver and requires no external server.

    Add `DATABASE_PATH` to your environment contract:

    ```ts title="src/platform/env.ts"
    import { defineEnv, env } from "@relkit/app/config";

    export default defineEnv({ DATABASE_PATH: env.string().default("./data-model.sqlite") });
    ```

    Keep that contract referenced by `relkit.config.ts`. Do not overwrite an existing configuration with a
    new minimal one. This example defaults to `./data-model.sqlite`, which retains data after restart.
    Start with a new local file, not an existing database with unrelated tables or data.

3. ## 3. Define tables and a custom model [#define-tables-and-a-custom-model]

    Create or extend `src/services/database/schema/index.ts`:

    ```ts title="src/services/database/schema/index.ts"
    /** Registers SQLite users and organization memberships with unique email and organization/user membership identities. */
    import { integer, sqliteTable, text, uniqueIndex } from "drizzle-orm/sqlite-core";

    export const users = sqliteTable("users", {
      id: integer().primaryKey({ autoIncrement: true }),
      email: text().notNull().unique(),
      active: integer({ mode: "boolean" }).notNull().default(true),
    });

    export const memberships = sqliteTable(
      "memberships",
      {
        id: integer().primaryKey({ autoIncrement: true }),
        organizationId: text().notNull(),
        userId: integer().notNull(),
        role: text().notNull(),
      },
      (table) => [uniqueIndex("membership_identity").on(table.organizationId, table.userId)],
    );
    ```

    Users has an integer identity, unique email, and active flag. Memberships has its own identity and a
    composite unique key. Its `userId` is not a foreign-key constraint in this demonstration; add the
    [relationships and constraints](/docs/modules/database/schema) your application needs.

    Add `src/services/database/models/users.model.ts`:

    ```ts title="src/services/database/models/users.model.ts"
    /** Extends the native users model with email-domain selection and an update that conceals missing or inactive rows. */
    import { defineModel, type UpdateArgs } from "@relkit/drizzle/sqlite";
    import { eq, like } from "drizzle-orm";
    import { users } from "../schema/index.js";

    export default defineModel({
      table: users,
      extend: {
        byEmailDomain: ({ table, database }, domain: string) =>
          database
            .select()
            .from(table)
            .where(like(table.email, `%@${domain}`)),
        findOneAndUpdate: async ({ table, database }, args: UpdateArgs<typeof users>) => {
          const id = args.where.id;
          if (id === undefined) return null;
          const [existing] = await database.select().from(table).where(eq(table.id, id));
          if (existing === undefined || existing.active === false) return null;
          const [updated] = await database
            .update(table)
            .set(args.data)
            .where(eq(table.id, id))
            .returning();
          return updated ?? null;
        },
      },
    });
    ```

    The custom methods receive `{ table, database }` automatically. Read [Custom models](/docs/modules/database/models)
    for the sample's pattern-matching, pagination, and atomicity limits before adapting it for public search.

4. ## 4. Register the database service [#register-the-database-service]

    Create or merge `src/services/database/service.ts`:

    ```ts title="src/services/database/service.ts"
    /** Owns lazy SQLite registration and disposal, supplying users-model extensions and an inactive-user lookup override. */
    import { Database } from "bun:sqlite";
    import { defineDrizzleService } from "@relkit/drizzle";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import * as schema from "./schema/index.js";
    import usersModel from "./models/users.model.js";

    export default defineDrizzleService({
      schema,
      client: ({ env }) => drizzle({ client: new Database(env.DATABASE_PATH) }),
      models: { users: usersModel },
      overrides: {
        users: {
          findOne: async ({ args, base }) => {
            const user = await base(args);
            return user?.active === false ? null : user;
          },
        },
      },
      dispose: (database) => database.$client.close(),
    });
    ```

    This connects the schema and model, adds an inactive-user override for `findOne`, and closes SQLite on
    disposal. It does not create tables. The `findOne` override is not a global soft-delete policy.

5. ## 5. Generate and apply the initial migration [#generate-and-apply-the-initial-migration]

    The scaffold installed the compatible Drizzle Kit version. Add this configuration:

    ```ts title="drizzle.config.ts"
    /** Points native Drizzle tooling at grouped model tables and rejects empty or in-memory migration targets. */
    import { defineConfig } from "drizzle-kit";

    const path = process.env.DATABASE_PATH;
    if (path === undefined || path.trim() === "" || path === ":memory:") {
      throw new Error("Set DATABASE_PATH to the persistent SQLite file you intend to migrate");
    }

    export default defineConfig({
      schema: "./src/services/database/schema/index.ts",
      dialect: "sqlite",
      out: "./src/services/database/migrations",
      dbCredentials: { url: path },
    });
    ```

    From your application's root, generate the migration from the table definitions and apply it:

    ```sh
    export DATABASE_PATH=./data-model.sqlite
    bun --bun drizzle-kit generate --name=initial
    bun run relkit db migrate
    ```

    Review the generated migration before applying it. In the repository example, the initial migration
    already exists, so set `DATABASE_PATH` and run `bun run db:migrate` instead of creating another one.
    Keep this environment value for the server, and commit generated SQL and required metadata under
    `src/services/database/migrations` with the schema. The installed command owns execution;
    scaffolding and service startup do not apply SQL.

    Run the compiler now so the database context is available to the next function:

    ```sh
    bun run check
    ```

6. ## 6. Create a member with generated CRUD [#create-a-member-with-generated-crud]

    Add the registration workflow:

    ```ts title="src/services/users/functions/register-member.function.ts"
    /** Validates native user data and creates the user/membership in one borrowed database transaction, retaining rollback failures. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      input: z.object({ email: z.string().email(), organizationId: z.string().min(1) }),
      output: z.object({ userId: z.number(), membershipId: z.number() }),
      handler: async ({ email, organizationId }, context) => {
        const data = context.database.zodSchemas.users.insert.parse({ email });
        return context.database.transaction(async (tx) => {
          const user = await tx.users.insert({ data });
          const membership = await tx.memberships.insert({
            data: { organizationId, userId: user.id, role: "member" },
          });
          return { userId: user.id, membershipId: membership.id };
        });
      },
    });
    ```

    The table service provides `users.insert`, `memberships.insert`, and the insert validator without
    requiring a custom model for either operation. The transaction commits both records together.
    See [Generated CRUD and schemas](/docs/modules/database/generated-schemas) and
    [Transactions](/docs/modules/database/transactions) for their contracts.

    Add the email-change workflow, which uses the generated update/select schemas:

    ```ts title="src/services/users/functions/update-user-email.function.ts"
    /** Validates native update/select data and returns the changed user's email or null when its row is unavailable. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      input: z.object({ userId: z.number().int().positive(), email: z.string().email() }),
      output: z.object({ userId: z.number(), email: z.string() }).nullable(),
      handler: async ({ userId, email }, context) => {
        const data = context.database.zodSchemas.users.update.parse({ email });
        const row = await context.database.users.update({ where: { id: userId }, data });
        if (row === null) return null;
        const user = context.database.zodSchemas.users.select.parse(row);
        return { userId: user.id, email: user.email };
      },
    });
    ```

    These are trusted internal examples, not authorized public write APIs. Add ownership/organization
    checks before exposing them to callers. This tutorial mounts only a read route.

7. ## 7. Expose a Users operation [#expose-a-users-operation]

    Add `src/services/users/functions/list-users.function.ts`:

    ```ts title="src/services/users/functions/list-users.function.ts"
    /** Lists validated user fields through the database model's email-domain extension. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    export default defineFunction({
      input: z.object({ domain: z.string() }),
      output: z.array(z.object({ id: z.number(), email: z.string(), active: z.boolean() })),
      handler: ({ domain }, context) => context.database.users.byEmailDomain(domain),
    });
    ```

    Add it to the Users service:

    ```ts title="src/services/users/service.ts"
    /** Exposes user listing, transactional registration and email updates through the immediate users service boundary. */
    import { defineService } from "@relkit/app/services";
    import listUsers from "./functions/list-users.function.js";
    import registerMember from "./functions/register-member.function.js";
    import updateUserEmail from "./functions/update-user-email.function.js";

    export default defineService({ functions: { listUsers, registerMember, updateUserEmail } });
    ```

    Connect the public operation to HTTP if you want an endpoint:

    ```ts title="src/routes/users/route.ts"
    /** Maps users GET requests to the service's email-domain model query through the inferred HTTP contract. */
    import { defineRoute } from "@relkit/app/routes";
    import users from "@app/services/users/service.js";

    export const GET = defineRoute({ target: users.listUsers });
    ```

    The route invokes the Users service, not the private database model. Function validation and output
    contracts remain the public boundary; the database service does not automatically expose CRUD routes.

8. ## 8. Verify database behavior [#verify-database-behavior]

    Create `tests/registration.test.ts`. It uses a separate in-memory SQLite database and the migrations
    you generated above. The second case makes membership creation fail after its insert, then checks
    that the transaction removes both writes. Your application's database is untouched.

    ```ts title="tests/registration.test.ts"
    /** Verifies the guide's registration commits both records or rolls both back. */
    import { expect, test } from "bun:test";
    import { Database } from "bun:sqlite";
    import { activateDrizzleService, defineDrizzleService } from "@relkit/drizzle";
    import { invokeFunction } from "@relkit/testing";
    import { drizzle } from "drizzle-orm/bun-sqlite";
    import { migrate } from "drizzle-orm/bun-sqlite/migrator";
    import * as schema from "@app/services/database/schema/index.js";
    import usersModel from "@app/services/database/models/users.model.js";
    import registerMember from "@app/services/users/functions/register-member.function.js";

    for (const failMembership of [false, true]) {
      test(
        failMembership ? "registration rolls back both records" : "registration saves both records",
        async () => {
          const definition = defineDrizzleService({
            schema,
            client: () => drizzle({ client: new Database(":memory:") }),
            models: { users: usersModel },
            overrides: {
              memberships: {
                insert: async ({ args, base }) => {
                  const membership = await base(args);
                  if (failMembership) throw new Error("membership unavailable");
                  return membership;
                },
              },
            },
            dispose: (database) => database.$client.close(),
          });
          const handle = await activateDrizzleService(definition, {});
          try {
            migrate(handle.client, { migrationsFolder: "src/services/database/migrations" });
            const registration = invokeFunction(
              registerMember,
              {
                email: "member@example.com",
                organizationId: "bookshop",
              },
              { context: ({ signal }) => ({ signal, database: handle.context }) },
            );
            if (failMembership) {
              await expect(registration).rejects.toThrow();
              expect(await handle.context.users.findMany()).toEqual([]);
              expect(await handle.context.memberships.findMany()).toEqual([]);
            } else {
              const result = await registration;
              expect(
                await handle.context.users.findOne({ where: { id: result.userId } }),
              ).toMatchObject({ email: "member@example.com" });
              expect(
                await handle.context.memberships.findOne({ where: { id: result.membershipId } }),
              ).toMatchObject({ userId: result.userId, organizationId: "bookshop", role: "member" });
            }
          } finally {
            await handle.close();
          }
        },
      );
    }
    ```

    From your application root:

    ```sh
    bun test tests/registration.test.ts
    bun run check
    bun run typecheck
    export DATABASE_PATH=./data-model.sqlite
    bun run dev
    ```

    Tests use an independent in-memory connection; they do not seed the running server. In a second
    terminal, query the migrated application:

    ```sh
    curl http://localhost:3000/users\?domain=example.com
    ```

    Use the actual backend port if different. An empty, migrated database returns HTTP `200`
    with `[]`. If you also complete the separate [Inspector setup](/docs/modules/operations/inspector),
    you can invoke `registerMember` (function ID `users.register-member`) with
    `{ "email": "member@example.com", "organizationId": "demo" }`, then repeat the request. Expect a row
    containing that email, its generated numeric ID, and `active: true`. Use a different email for another
    registration; email uniqueness is enforced by the database.

    Inspect the checked `database` service and Users function in the Inspector, normally at
    `http://localhost:3210`, and inspect `.relkit/generated/context-registry.d.ts` for the typed table methods.
    The `listUsers` function is also directly invokable from the Inspector with `{ "domain": "example.com" }`.

    Before deployment, add application-specific authorization, bounded queries, driver configuration,
    and tested backup and migration procedures. Continue with [Integrate Better Auth](/docs/modules/database/better-auth)
    to plan authentication tables and session wiring.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/drizzle` API](/docs/api/drizzle)
- [`@relkit/functions` API](/docs/api/functions)
- [`@relkit/routes` API](/docs/api/routes)

- [`examples/data-model/src/services/users/functions/register-member.function.ts`](https://github.com/rel-kit/relkit/blob/main/examples/data-model/src/services/users/functions/register-member.function.ts)

## Related tasks

Continue with [Add email and password sign-in](/guides/auth/email-password-sign-in). Review
[transaction limits](/docs/modules/database/transactions) when adapting the registration workflow.

---

# React to order events
Source: https://relkit.dev/guides/events/react-to-order-events

Create an order, publish its details, and run a confirmation function. This example logs the reaction without sending email or writing to a database.

> **Before you begin**
>
> You'll need an [existing RELKIT application](/docs/learn/create-an-app) and Bun 1.3.10 or later.

Create the files shown below. If your app already has the Orders example, update those files instead. Run all commands from your app's root.

1. ## 1. Install and bind the selected event runtime [#install-and-bind-the-selected-event-runtime]

    The manual path below uses the file-backed local event integration, which is not selected by the
    minimal app. Install its owner first; no Docker or model SDK is needed:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/local@0.7.14
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    Create `src/platform/events.ts` from this descriptor:

    ```ts title="src/platform/events.ts"
    /**
     * Describes the explicit file-backed event profile used by the manual tutorial.
     * The app config imports this value; the selected runtime activates it after
     * checking, without adding a Docker dependency or enabling inspection.
     */
    import { localEvent } from "@relkit/local";

    export const event = localEvent();
    ```

    Import `event` from `@app/platform/events.js` into the existing `relkit.config.ts`. Add it as the
    singular `event` option and merge `event: "default"` into `defaults`, preserving other profiles and
    settings. The event scaffold can install/configure this selected baseline automatically; manual
    source copying does not. With `--no-install`, complete `bun install` and `bun run check` first.

2. ## 2. Add the event and its callers [#add-the-event-and-its-callers]

    ### Define the event

    ```ts title="src/services/orders/events/order-created.event.ts"
    import { defineEvent } from "@relkit/app/events";
    import { z } from "@relkit/app/schema";

    const orderCreated = defineEvent({
      id: "orders.created",
      version: 1,
      input: z.object({
        orderId: z.string().min(1),
        sku: z.string().min(1),
        totalCents: z.number().int().nonnegative(),
      }),
    });

    export default orderCreated;
    ```

    `orders.created` carries the order ID, product code, and total.

    ### Publish after creating the order

    Add a pricing function. For this example, each item costs 100 cents:

    ```ts title="src/services/orders/functions/price-order.function.ts"
    /** Calculates integer order totals at 100 cents per item for the create-order function. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const priceOrder = defineFunction({
      input: z.object({ quantity: z.number().int().positive() }),
      output: z.object({ totalCents: z.number().int().nonnegative() }),
      handler: ({ quantity }) => ({ totalCents: quantity * 100 }),
    });

    export default priceOrder;
    ```

    Create the order and publish its details:

    ```ts title="src/services/orders/functions/create-order.function.ts"
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";

    const createOrder = defineFunction({
      input: z.object({
        orderId: z.string().min(1),
        sku: z.string().min(1),
        quantity: z.number().int().positive(),
      }),
      output: z.object({
        orderId: z.string(),
        sku: z.string(),
        totalCents: z.number().int().nonnegative(),
      }),
      publishes: ["orders.created"],
      handler: async (input, context) => {
        const order = { orderId: input.orderId, sku: input.sku, totalCents: input.quantity * 100 };
        await context.events["orders.created"].publish(order);
        return order;
      },
    });

    export default createOrder;
    ```

    `publishes` allows this function to send `orders.created`. The handler returns the order without waiting for the confirmation.

    ### Consume the event

    ```ts title="src/services/orders/functions/order-confirmation.function.ts"
    import { defineEventFunction } from "@relkit/app/events";

    const orderConfirmation = defineEventFunction({
      id: "orders.confirmation",
      event: "orders.created",
      handler: async (order, context) => {
        context.log.info("order.confirmation.requested", { orderId: order.orderId });
      },
    });

    export default orderConfirmation;
    ```

    `event: "orders.created"` subscribes this function to the event. Its handler receives the order details.

    ### Add an endpoint

    Expose the order-creating function through an Orders service. If you already have this service, add these members alongside your existing ones:

    ```ts title="src/services/orders/service.ts"
    /** Declares the orders service boundary and its public members. */
    import { defineService } from "@relkit/app/services";
    import createOrder from "@app/services/orders/functions/create-order.function.js";
    import priceOrder from "@app/services/orders/functions/price-order.function.js";

    export default defineService({
      functions: { createOrder, priceOrder },
    });
    ```

    Connect it to `POST /orders`:

    ```ts title="src/routes/orders/route.ts"
    /** Maps the HTTP endpoint to its owning service's public member. */
    import { defineServiceRoutes } from "@relkit/app/routes";
    import orders from "@app/services/orders/service.js";

    export const { POST } = defineServiceRoutes(orders, {
      POST: { member: "createOrder", successStatus: 201 },
    });
    ```

    ### Check and test delivery

    Configure a compatible event adapter under singular `event`, then check the graph:

    ```sh
    bun run check
    bun run typecheck
    ```

    No environment mode silently substitutes an event provider. For a credential-free behavior test, use
    the deterministic event harness:

    [Event-harness regression test](https://github.com/rel-kit/relkit/blob/main/packages/testing/tests/compatibility/events.test.ts)

    Start the application with `bun run dev`. In a second terminal, create an order:

    ```sh
    curl -i -X POST http://localhost:3000/orders \
      -H 'content-type: application/json' \
      -d '{"orderId":"order-100","sku":"book","quantity":2}'
    ```

    Expect HTTP `201` and `totalCents: 200`. In the application terminal, look for
    `order.confirmation.requested` with `orderId=order-100`. The response confirms publication was
    accepted; the log separately confirms that the consumer ran.

3. ## 3. Add another reaction [#add-another-reaction]

    In a second terminal, open your app's root directory and copy the consumer:

    ```sh
    cp src/services/orders/functions/order-confirmation.function.ts src/services/orders/functions/order-analytics.function.ts
    ```

    Change the copy's `id` to `orders.analytics` and its log message to `order.analytics.recorded`. Keep `event: "orders.created"`.

    After configuring an event binding and starting the app, call the publishing route with `orderId` set to
    `order-101`. Look for both `order.confirmation.requested` and `order.analytics.recorded` with that ID. You
    added a reaction without changing the publishing function.

    Optionally complete the separate [Inspector setup](/docs/modules/operations/inspector), then open
    `orders.created` in its UI at `http://localhost:3210` to see both subscribers under **Consumer functions**.

## Related tasks

[Run a durable task](/docs/modules/jobs/quickstart) when follow-up work must survive a process
restart. For transactional database changes, follow [Register users in a
transaction](/guides/database/register-users-in-a-transaction).

---

# Call your API from React
Source: https://relkit.dev/guides/frontend/connect-react

Show **Hello, RELKIT!** in a React page using the same `GET /hello` operation you ran in
[Create and run an API](/docs/learn/create-an-app). Your backend owns its input and output
schemas; the frontend receives generated types and calls it through RPC.

> **Before you begin**
>
> Keep that backend running on `http://127.0.0.1:3000`. You'll also need an existing Vite React or
> Next.js App Router TypeScript app with its dependencies installed. Run frontend commands in that
> app's root. This guide adds RELKIT to it; it does not require the fullstack or agent starter.

Select your framework in the tabs below. Your selection carries through the remaining steps.

1. ## 1. Install the frontend client

    Install the React client and its selected peers, preserving compatible versions already
    used by your app:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @opentelemetry/api@1.9.1 @orpc/tanstack-query@2.0.0-beta.31 @relkit/client@0.8.4 '@tanstack/query-core@>=5.80.2' '@tanstack/react-query@>=5.80.2' 'react@>=18.0.0'
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    Install the CLI as frontend development tooling so it can pull and check the contract:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add --dev @relkit/cli@0.8.8
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    Keep your existing React DOM and TypeScript tooling. The frontend does not need the backend's
    database, storage, or model-provider packages.

2. ## 2. Pull the backend contract

    From the backend root, run `bun run check` after changing a route. With the backend running,
    run this in the **frontend root**:

    ```sh title="Terminal — frontend root"
    bun run relkit client pull http://127.0.0.1:3000 --out .relkit/generated
    ```

    This writes `contract.ts`, `client.ts`, `client-registry.d.ts`, and `client-manifest.json`.
    Keep them together and regenerate them with the command; do not edit them or import backend
    `service.ts` files into the browser.

    Include the generated declarations in the TypeScript project that checks your React source.

    **Vite**

    In a Vite app this is usually `tsconfig.app.json`. Merge these `include` entries into your existing
    configuration, keeping its compiler options:

    ```json title="tsconfig.app.json"
    {
      "compilerOptions": {
        "target": "ES2022",
        "lib": ["ES2022", "DOM", "DOM.Iterable"],
        "module": "ESNext",
        "moduleResolution": "Bundler",
        "jsx": "react-jsx",
        "strict": true,
        "skipLibCheck": true,
        "noEmit": true
      },
      "include": ["src", ".relkit/generated/**/*.ts"]
    }
    ```

    **Next.js**

    Merge these `include` entries into your existing `tsconfig.json`. Keep your compiler options,
    Next.js plugin, and any additional entries your application already uses:

    ```json title="tsconfig.json — merge the include list"
    {
      "include": [
        "next-env.d.ts",
        "**/*.ts",
        "**/*.tsx",
        ".next/types/**/*.ts",
        ".next/dev/types/**/*.ts",
        ".relkit/generated/**/*.ts"
      ]
    }
    ```

    Your editor should now offer `GET /hello` as a selector and an optional `name` string as its input.
    If the selector is missing, check the backend URL, the pull output, and the TypeScript `include` list.

3. ## 3. Connect the local frontend

    The build helper reads the fingerprint from the frontend's `.relkit/generated/client-manifest.json`.
    It does not pull a contract, generate types, or configure forwarding on its own.

    **Vite**

    Add `relkit()` to your existing Vite plugins and merge these proxy entries into `server.proxy`.
    Keep your framework's existing plugins:

    ```ts title="vite.config.ts — merge with your existing config"
    /** Adds the pulled fingerprint and a local same-origin proxy to an existing Vite React project. */
    import { relkit } from "@relkit/client/build/vite";

    export default {
      plugins: [relkit()],
      server: {
        host: "127.0.0.1",
        port: 5173,
        strictPort: true,
        proxy: {
          "/rpc": { target: "http://127.0.0.1:3000", ws: true },
          "/_relkit": { target: "http://127.0.0.1:3000" },
        },
      },
    };
    ```

    The browser sends `/rpc` calls and the `/_relkit/v1/client/identity` handshake to the frontend
    origin; Vite forwards them to the backend. This lets the provider use the current page's origin.
    Keep `127.0.0.1` consistent in these local URLs.

    The development proxy is not part of the production build. Before publishing, configure equivalent
    paths at your production gateway, or set the provider's public `baseUrl` and configure
    [credentialed CORS and cookies](/docs/modules/client/authentication) for separate origins.

    **Next.js**

    Wrap your existing Next.js configuration with `withRelkit` and merge these forwarding rules into
    its `rewrites`. Keep the other options and any existing rules:

    ```ts title="next.config.ts — merge with your existing config"
    /** Embeds the pulled fingerprint and forwards local browser requests to the backend. */
    import { withRelkit } from "@relkit/client/build/next";

    export default withRelkit({
      /** Keeps RPC and identity requests on the frontend origin.
       * @returns Local forwarding rules; replace their destinations for production. */
      async rewrites() {
        return [
          { source: "/rpc/:path*", destination: "http://127.0.0.1:3000/rpc/:path*" },
          { source: "/_relkit/:path*", destination: "http://127.0.0.1:3000/_relkit/:path*" },
        ];
      },
    });
    ```

    [`withRelkit`](/docs/api/client#withrelkit) embeds the pulled contract fingerprint.
    The [Next.js rewrites](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites)
    forward `/rpc` calls and the `/_relkit/v1/client/identity` handshake to RELKIT. The browser stays
    on the frontend origin, so the provider needs no separate `baseUrl`.

    Keep RELKIT running as a separate backend on port `3000`; run Next.js on port `3002` in step 5.
    These rewrites also run in production: replace their local destinations with your backend's server URL
    before deploying. Static exports cannot run rewrites; use your gateway or a public backend URL with
    [credentialed CORS and cookies](/docs/modules/client/authentication) instead.

    If your app adds sign-in, forward its [auth mount](/docs/modules/client/authentication) too.

4. ## 4. Render the typed response

    `RelkitClientProvider` owns the connection and query cache; `useRoute` calls the generated
    operation with domain input. Both frameworks use the same component.

    **Vite**

    Replace the starter `src/App.tsx` with this component. Keep your existing entry point rendering `App`:

    ```tsx title="src/App.tsx"
    "use client";

    /** Renders the minimal backend's greeting through the pulled registry and a same-origin client provider. */
    import { RelkitClientProvider, useRelkitClient, useRoute } from "@relkit/client/react";

    /** Displays the typed Hello result after the provider resolves backend identity.
     * @returns Loading, connection failure, request failure, or the successful greeting. */
    export function Greeting() {
      const { status } = useRelkitClient();
      const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

      if (status === "application-updated") {
        return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
      }
      if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
      if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
      if (greeting.isPending) return <p role="status">Loading greeting…</p>;
      return <h1>{greeting.data.message}</h1>;
    }

    /** Supplies the shared query cache and identity handshake to the frontend tree.
     * @returns The greeting inside a same-origin RELKIT provider. */
    export default function App() {
      return (
        <RelkitClientProvider>
          <Greeting />
        </RelkitClientProvider>
      );
    }
    ```

    **Next.js**

    Create `app/relkit-app.tsx` with this component. If your project uses `src/app`, place both files
    there instead. The [top-level `"use client"` directive](https://nextjs.org/docs/app/api-reference/directives/use-client)
    allows the provider and hooks to run inside a Client Component:

    ```tsx title="app/relkit-app.tsx"
    "use client";

    /** Renders the minimal backend's greeting through the pulled registry and a same-origin client provider. */
    import { RelkitClientProvider, useRelkitClient, useRoute } from "@relkit/client/react";

    /** Displays the typed Hello result after the provider resolves backend identity.
     * @returns Loading, connection failure, request failure, or the successful greeting. */
    export function Greeting() {
      const { status } = useRelkitClient();
      const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

      if (status === "application-updated") {
        return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
      }
      if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
      if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
      if (greeting.isPending) return <p role="status">Loading greeting…</p>;
      return <h1>{greeting.data.message}</h1>;
    }

    /** Supplies the shared query cache and identity handshake to the frontend tree.
     * @returns The greeting inside a same-origin RELKIT provider. */
    export default function App() {
      return (
        <RelkitClientProvider>
          <Greeting />
        </RelkitClientProvider>
      );
    }
    ```

    Render it from your page. Keep your existing `app/layout.tsx`, including its `<html>` and `<body>`:

    ```tsx title="app/page.tsx"
    /** Renders the shared Hello example from a Next.js App Router server page. */
    import RelkitApp from "./relkit-app";

    /** Keeps provider hooks inside the imported Client Component.
     * @returns The greeting within the application's existing root layout. */
    export default function Page() {
      return <RelkitApp />;
    }
    ```

    Keep React hooks in the Client Component. For calls from a Node.js Server Component or Route Handler,
    use [`createClient`](/docs/modules/client/transports) with an explicit backend URL and the appropriate
    request identity. The `/server` and `/server/react` helpers require Bun; see
    [server rendering](/docs/modules/client/ssr) before selecting a server-side API.

    `greeting.data.message` is inferred from the backend function's output schema. No shared handwritten
    response interface is needed. The `GET /hello` selector identifies that route, but the client sends
    RPC over `/rpc`; it does not construct a REST query string. Raw handlers are not generated operations.

5. ## 5. Verify the page and contract

    From the frontend root:

    **Vite**

    ```sh title="Terminal — frontend root"
    bun run tsc --noEmit -p tsconfig.app.json
    bun run relkit client check http://127.0.0.1:3000 --out .relkit/generated
    bun run dev
    ```

    Open `http://127.0.0.1:5173`. Expect a loading message followed by **Hello, RELKIT!**. In the browser's
    Network panel, the identity request and the RPC request should succeed. Stop the backend and reload
    to check the connection error message.

    **Next.js**

    With your existing `dev` script running `next dev`, run:

    ```sh title="Terminal — frontend root"
    bun run tsc --noEmit
    bun run relkit client check http://127.0.0.1:3000 --out .relkit/generated
    bun run dev --hostname 127.0.0.1 --port 3002
    ```

    Open `http://127.0.0.1:3002`. Expect a loading message followed by **Hello, RELKIT!**. In the browser's
    Network panel, the identity and RPC requests should use port `3002` and succeed through the rewrites.
    Stop the backend and reload to check the connection error message.

    After changing the public backend contract, run `client pull` again, typecheck, and restart the
    frontend dev server so the plugin loads the new fingerprint. Use `client check` before a frontend
    build. A fingerprint mismatch blocks new typed work with `application-updated`; coordinate frontend
    and backend releases instead of bypassing the check.

## Connect another capability

Each module documents its backend declaration next to the corresponding frontend usage:

| Backend capability                    | Frontend entry point                                             | Continue with                                                                                             |
| ------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `defineRoute` / `defineServiceRoutes` | `useRoute`, `useRouteMutation`, or `createClient`                | [Call a defined route](/docs/modules/http/define#use-from-the-frontend)                                   |
| `streamOf` route output               | `useStream`                                                      | [Consume a response stream](/docs/modules/http/streaming#use-from-the-frontend)                           |
| `defineJob` with a client policy      | `useJobTrigger`, `useJobRun`, or the generated `client.jobs` API | [Trigger and observe a job](/docs/modules/jobs/quickstart#use-this-job-from-the-frontend)                 |
| Agent with a client policy            | `useAgent`                                                       | [Run an agent](/docs/modules/ai/agents#use-this-agent-from-the-frontend)                                  |
| `defineGraph` with a client policy    | `useAgent` with typed initial input and resume replies           | [Run and resume a graph](/docs/modules/ai/graphs-persistence#run-and-resume-this-graph-from-the-frontend) |
| `defineChannel` with browser access   | `useChannel`, `useRealtime`                                      | [Subscribe to a channel](/docs/modules/realtime#subscribe-from-the-frontend)                              |
| Better Auth mount                     | Better Auth's browser client and the RELKIT identity provider    | [Sign-in clients](/docs/modules/auth/clients)                                                             |

Buckets, caches, database models, and backend events have no direct generated browser API.
Expose an authorized function through a route when the frontend needs that operation. File uploads
use the route's [multipart HTTP contract](/docs/modules/http/uploads), rather than treating files
as ordinary RPC JSON.

## Related tasks

- [Add sign-in](/guides/auth/email-password-sign-in) before exposing private application data.
- [Upload product images](/guides/storage/upload-product-images) when the frontend sends files.

**[Typed Client module](/docs/modules/client)**

Choose transports, queries, mutations, streams, server rendering, and recovery APIs.

**[Client API reference](/docs/api/client)**

Look up signatures, options, return values, and import paths.

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

**Reference and source**

- [`@relkit/client` API](/docs/api/client)
- [`@relkit/routes` API](/docs/api/routes)
- [`@relkit/functions` API](/docs/api/functions)

- [`apps/docs/examples/frontend/app.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/app.tsx)
- [`apps/docs/examples/frontend/vite.config.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/vite.config.ts)
- [`apps/docs/examples/frontend/next.config.ts`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/next.config.ts)
- [`apps/docs/examples/frontend/next-page.tsx`](https://github.com/rel-kit/relkit/blob/main/apps/docs/examples/frontend/next-page.tsx)

---

# Upload product images
Source: https://relkit.dev/guides/storage/upload-product-images

Add `POST /uploads` to an existing application. You'll send two images, store them in the assets bucket, and check the returned object keys.

> **Before you begin**
>
> You'll need a running RELKIT application, Docker for local MinIO, and two PNG images.

Create the four files below. If your app already has an Assets service or an uploads route, merge these members into it. Run commands from your app's root.

1. ## 1. Configure storage [#configure-storage]

    This local S3-compatible selection uses MinIO and requires a running Docker daemon. Install its
    adapter and Docker materializer from your app root:

    {/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

    From this guide's application/package root, install only its selected requirements:

    ```sh
    bun add @relkit/docker@0.7.13 @relkit/s3@0.7.13
    ```

    Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in `dependencies`; build/type tooling belongs in `devDependencies`. Installing an adapter does not supply its optional SDK peers or enable the feature's configuration.

    In `relkit.config.ts`, import `s3` from `@relkit/s3`, `docker` from `@relkit/docker`, and
    `env as binding` from `@relkit/app/config`. Create a `bucket` object inside `defineApp()` if the
    app has none, then add this `assets` entry:

    ```ts title="relkit.config.ts — bucket configuration"
    assets: docker(
      s3({
        endpoint: binding.url("ASSETS_S3_ENDPOINT"),
        bucketName: binding.string("ASSETS_S3_BUCKET"),
        region: binding.string("ASSETS_S3_REGION"),
        credentials: {
          accessKeyId: binding.secret("ASSETS_S3_ACCESS_KEY_ID"),
          secretAccessKey: binding.secret("ASSETS_S3_SECRET_ACCESS_KEY"),
        },
        forcePathStyle: true,
      }),
    ),
    ```

    `assets` starts a local MinIO recipe in development. The complete commerce application also has
    other bucket profiles; this first upload needs only `assets`. Connected and cloud ownership
    choices are described in [Define a bucket](/docs/modules/storage/define).

2. ## 2. Define the bucket [#define-the-bucket]

    ```ts title="src/services/assets/buckets/assets.bucket.ts"
    /** Declares private JSON/image assets with a five-million-byte limit for validated upload handlers. */
    import { defineBucket } from "@relkit/app/buckets";

    const assets = defineBucket({
      id: "assets.objects",
      profile: "assets",
      visibility: "private",
      maxObjectBytes: 5_000_000,
      allowedContentTypes: ["application/json", "image/*"],
    });

    export default assets;
    ```

3. ## 3. Add the upload function [#add-the-upload-function]

    The function validates the upload, saves each image, and returns the stored keys:

    ```ts title="src/services/assets/functions/upload-assets.function.ts"
    /** Validates multipart image files, writes them through the declared assets bucket and returns their uploaded names. */
    import { defineFunction } from "@relkit/app/functions";
    import { z } from "@relkit/app/schema";
    import assets from "../buckets/assets.bucket.js";

    const uploadedFile = z.file({
      maxBytes: 1024 * 1024 * 10,
      mediaTypes: ["image/jpeg", "image/png"],
    });

    const uploadAssets = defineFunction({
      input: z.object({
        label: z.string().min(1),
        primary: uploadedFile,
        attachments: z.array(uploadedFile),
      }),

      output: z.object({
        label: z.string(),
        files: z.array(z.string()),
      }),

      dependencies: { buckets: { assets } },

      handler: async ({ label, primary, attachments }, context) => {
        const files = [primary, ...attachments];

        // This demo uses filenames as keys; uploading the same name replaces the file.
        await Promise.all(
          files.map(async (file) =>
            context.buckets.assets.put(file.name, new Uint8Array(await file.arrayBuffer()), {
              contentType: file.type,
            }),
          ),
        );

        return { label, files: files.map(({ name }) => name) };
      },
    });

    export default uploadAssets;
    ```

    For this local example, filenames are the keys. Reusing a filename replaces that object. Use server-generated keys and authorize requests before accepting real users' uploads.

4. ## 4. Expose the endpoint [#expose-the-endpoint]

    Add the function to your Assets service:

    ```ts title="src/services/assets/service.ts"
    /** Declares the assets service boundary without acquiring native clients. */
    import { defineService } from "@relkit/app/services";
    import uploadAssets from "./functions/upload-assets.function.js";

    export default defineService({ functions: { uploadAssets } });
    ```

    Connect it to `POST /uploads`:

    ```ts title="src/routes/uploads/route.ts"
    /** Admits bounded multipart upload requests to the assets service's validated image handler. */
    import { defineRoute } from "@relkit/app/routes";
    import assets from "../../services/assets/service.js";

    export const POST = defineRoute({
      target: assets.uploadAssets,
      accept: "multipart/form-data",
      maxBodyBytes: 10 * 1024 * 1024,
    });
    ```

5. ## 5. Upload two images [#upload-two-images]

    Check and start the app:

    ```sh
    bun run check
    ```

    ```sh
    bun run dev
    ```

    The local MinIO recipe supplies generated binding-only credentials and loopback ports. Keep the app running
    and open a second terminal in the app's root. `bun run dev --local=off` disables recipes and requires the
    named connected/infrastructure values instead.

    Place two small PNG images named `cover.png` and `detail.png` there. Keep their combined size below 1 MB for this request, then send:

    ```sh
    curl -i http://localhost:3000/uploads \
      -F label=book-photos \
      -F 'primary=@cover.png;type=image/png' \
      -F 'attachments=@detail.png;type=image/png'
    ```

    Use your app's configured port if it differs from `3000`. Expect HTTP 200:

    ```json
    { "label": "book-photos", "files": ["cover.png", "detail.png"] }
    ```

6. ## 6. Check the stored files [#check-the-stored-files]

    Optionally complete the separate [Inspector installation, bridge and tool setup](/docs/modules/operations/inspector).
    Open its UI, normally at `http://localhost:3210`. Select **Buckets**, open `assets.objects`, and look
    for `cover.png` and `detail.png`. Click **Preview** beside either key to view its image.

    Tests must provide explicit replacements for profile `assets`; no environment name installs a file fake.
    You can now [read the files or create download links](/docs/modules/storage/read-delete). Before deploying, review
    ownership in [Integrations](/docs/modules/integrations) and add authentication to the upload endpoint.

## Related tasks

[Read files and create download links](/docs/modules/storage/read-delete), or [add
sign-in](/guides/auth/email-password-sign-in) before accepting uploads from users.