Configuration reference

A lookup table for everything you can put in the object exported from src/aventara.config.ts (the AvConfig; the scaffold leaves adapter out of it and joins it where the framework is created), plus the options of describePrismaAdapter and createPrismaAdapter. For a walkthrough with explanations, see Configuration. For how layers combine, see Contract layers.

All types below are exported from @aventara/core (AvConfig, AvConfigLayer, AvConfigResource, AvConfigExemptions, AvPipeline, AvContractLimits, ...). Keep as const on the object you export so TypeScript can check Resource and field names against your schema. @aventara/core/avz is a separate entry that holds AvZ, the builder for Json shapes and field validators (JSON fields, Field validators). @aventara/core/internal exists for Aventara's own packages and is not public API; do not import from it.

Where a key can go

The object has a root, two overlays, application (your server-side code) and client (remote callers: HTTP and the generated frontend client), and the agent layer (AI agents over MCP), which narrows the layer it extends.

A key that is not in this table is refused at startup with CONFIG_UNKNOWN_PROPERTY, and a moved key (entrypoint at the root; restrictions, fields, behaviors, transactions in any layer) with CONFIG_MOVED_PROPERTY, whose message names the new location. In a configuration TypeScript checks against your model (inline in createFramework({ ... }) or AventaraModule.forRoot), a misplaced key is a type error at that key first.

An override wins when it is present, not when it is truthy: false overrides. An explicit undefined is refused (CONFIG_INVALID_VALUE or CONFIG_INVALID_TYPE); leave the key out instead.

Root-only keys

api

The mount path of the protocol (before rc.1, entrypoint; that key is refused with CONFIG_MOVED_PROPERTY: "entrypoint moved in rc.1: use api"). Read it back as framework.api. It is normalized to one canonical form: one leading slash, no trailing slash, no empty segment. api, /api/ and //api// are all /api; "" and / mean the root. Everything else that is not a plain path is refused (CONFIG_INVALID_VALUE): whitespace, ://, a query, a fragment, . or .. segments, backslashes, non-ASCII characters, percent-encoding, and characters a path segment may not carry unencoded.

api: "/api",                   // GET /api/_contract, POST /api/_resources/User/find/many
api: "/v1/data",               // nested paths are fine

api: "api/v1?x=1"
-> CONFIG_INVALID_VALUE at "api": api carries a query; a mount path is /-separated segments of ASCII letters, digits and -._~!$&'()*+,;=:@ only

api alone decides where the protocol is mounted; a Nest global prefix does not move it. See NestJS host.

mcp

Turns MCP on: the mount path of the MCP endpoint, normalized as api is. The object form adds OAuth: servers lists the authorization servers a caller's token comes from (absolute https URLs, at least one), and verify(token) resolves the caller for a good token and null for a bad one. A verify that throws is answered like a bad token (401) and also reported to diagnostics. The resolved endpoint is framework.mcp (AvMcpEndpoint), undefined when MCP is off. The tools are built from the agent layer.

mcp: "/mcp",
mcp: { path: "/mcp", authorization: { servers: ["https://auth.example.com"], verify } },

mcp: "/api"
-> CONFIG_INVALID_VALUE at "mcp": mcp is the mount path api already has; mount the MCP endpoint at a path of its own
mcp: { path: "/mcp", authorization: { servers: [], verify } }
-> CONFIG_INVALID_VALUE at "mcp.authorization.servers": mcp.authorization.servers must name at least one authorization server
mcp: { path: "/mcp", authorization: { servers: ["http://auth.example.com"], verify } }
-> CONFIG_INVALID_VALUE at "mcp.authorization.servers[0]": mcp.authorization.servers[0] must be an absolute https URL

A path inside the protocol's _ routes under api (/api/_mcp) is refused too, and so are an unknown key (CONFIG_UNKNOWN_PROPERTY), a missing path, servers or verify (CONFIG_REQUIRED) and a verify that is not a function (CONFIG_INVALID_TYPE).

adapter

What the framework runs against. For Prisma 7 it is the result of createPrismaAdapter({ ...description, client }) (below). The scaffold does not write it in src/aventara.config.ts, which aventara-build runs without a database client: app.module.ts spreads the configuration and adds adapter beside it. A configuration that still builds its adapter inside keeps working; the framework compiles its Contracts at startup. The adapter advertises what it can perform; your configuration can only narrow that. A model whose name starts with $ is refused (COMPILER_RESERVED_RESOURCE_NAME): $ names belong to the framework.

prebuilt

The four Contracts compiled ahead of time by aventara-build, exported as aventaraContracts from contracts.generated.ts. For serverless and edge platforms, where every cold start would otherwise compile them (Deploying).

import { aventaraContracts } from "./generated/aventara/contracts.generated.js";

const framework = await createFramework({
  ...aventaraConfig,
  adapter: await createPrismaAdapter({ ...adapter, client: prisma }),
  prebuilt: aventaraContracts,
});

The file is used only when this @aventara/core compiled it, for this protocol version, from the same configuration and adapter model. The Contracts, hashes and GET /api/_contract bytes are then the ones compiling would give. Any other file is ignored whole: the framework compiles at startup and prints one warning, AVENTARA_PREBUILT_STALE, naming the Resources whose configuration or model changed, or the version that differs. A value that is not an object is CONFIG_INVALID_TYPE.

diagnostics

A sink for unplanned failures (responses with an A3xxx code), so you can log the real error that the response deliberately hides. It receives the original error object, which never reaches the response. Besides the unexpected failures of your adapter, pipelines and compute stages, it receives these reports, each with the A3xxx code the caller got:

What the caller receives is unchanged in every case. A2xxx and A4xxx outcomes are not reported.

import type { AvDiagnostic } from "@aventara/core";

diagnostics: (d: AvDiagnostic) => {
  logger.error({ code: d.code, requestId: d.requestId, resource: d.kind === "operation" ? d.resource : undefined }, String(d.error));
},

type AvDiagnostic =
  | { kind: "operation";   error: unknown; code: AvOperationErrorCode; origin: "application" | "client";
      resource: string; family: AvOperationFamily; variant: string; requestId: string; operation?: number;
      deliberate?: true }
  | { kind: "transaction"; error: unknown; code: AvOperationErrorCode; origin: "application" | "client";
      requestId: string; operation?: number; deliberate?: never }
  | { kind: "mcp"; error: unknown; code: "A3000"; origin: "agent"; requestId: string };

deliberate is readable on every diagnostic without checking kind first. Only an operation diagnostic ever carries it.

A guard that throws a plain Error("secret boom") yields {"code":"A3000","cause":{"message":"Internal framework error."}} to the caller and the Error to the sink. A pipe that throws new AvError("A3001", "billing service is down") gives the caller {"code":"A3001","cause":{"message":"Adapter execution failed."}} and the sink a diagnostic with code: "A3001", deliberate: true and your error, message included.

A message you put in an AvError with any code outside A3xxx (for example A4002) is sent to the caller exactly as written, so it must not carry database text, SQL, a stack, a path or a secret.

misuse

Counts the values server-side calls refused because they could not be read or were not plain data (Server-side usage). It sits beside diagnostics and cannot change a response: an error it throws or a promise it rejects is ignored.

import type { AvMisuseEvent } from "@aventara/core";

misuse: (event: AvMisuseEvent) => metrics.increment("aventara.misuse", { kind: event.kind }),

In a configuration written as an as const object, the parameter has no contextual type, so annotate it as shown (otherwise TypeScript reports Parameter 'event' implicitly has an 'any' type).

type AvMisuseEvent = {
  kind: "unreadable-value" | "non-plain-value";
  path: readonly (string | number)[];       // the issue path the caller received
  origin?: "application" | "client";
  resource?: string;
  family?: AvOperationFamily;
  variant?: string;
  operation?: number;                        // the step, in a transaction
};

One event per refused value, never the value itself. The operation members are present when they could be read. Nothing is reported to both misuse and diagnostics. A real event, for a revoked Proxy passed as where:

{"kind":"unreadable-value","path":["arguments","where"],"origin":"application","resource":"User","family":"find","variant":"unique"}

policy

The policy engine that client and agent requests are checked against, and the function that derives a request's principal from its ctx.$state. Core never imports an engine: any object with the right shape satisfies AvPolicyEngine. The guide is Policies.

const framework = await createFramework({
  api: "/api",
  adapter,
  policy: {
    engine,                                   // satisfies AvPolicyEngine
    principal: ({ $state }) => $state.user ?? null,   // null: an anonymous caller
  },
});

engine has three questions, each answered now or as a promise, and three passive lists:

governed, paths and afterChecks are checked against the Core Contract when the framework is constructed. A name or path the Contract does not have is CONFIG_INVALID_VALUE, naming the Resource or the rule. A missing policy.engine or policy.principal is CONFIG_REQUIRED. Only governed reaches a Contract (a governed: true mark on each such field and relation), so the Contract hash changes only when that set changes. Policies never reach the ClientContract.

A refusal answers 403 A4002 (Error codes).

application and client

The two overlays. Each holds the six layer keys below and nothing else: no api, mcp, adapter, diagnostics, misuse or extends. An application call sees the root plus application; a remote call the root plus client.

agent

The layer an AI agent's calls run under, over MCP. It holds the six layer keys and extends:

Without an agent key the layer is the client's view exactly. It compiles to framework.contracts.agent, which carries its own hash; an agent view equal to the client's has the client's hash. agent is allowed without mcp.

Layer keys

exposed and exemptions

exposed: true exposes everything the layer above offers and exemptions lists what to hide; exposed: false exposes nothing and exemptions lists what to expose. The root's layer above is the adapter's model; an overlay's is the root's final view.

type AvConfigExemptions = {
  resources?: {
    [Resource]?: boolean | {
      operations?: boolean | AvOperationFamily[] | {
        [family]?: boolean | variant[] | { [variant]?: boolean };
      };
      fields?: {
        [field]?: boolean | capability[] | { [capability]?: boolean | token[] };
      };
    };
  };
};

select, include, order and orderNulls take only true or false.

Filter operators: equals, not, in, notIn, lt, lte, gt, gte, contains, startsWith, endsWith, mode, has, hasEvery, hasSome, isEmpty, path, stringContains, stringStartsWith, stringEndsWith, arrayContains, arrayStartsWith, arrayEndsWith; only the ones the adapter offers for the field's type can be named. Scalar directives: $increment, $decrement, $multiply, $divide, $push, $unset. Relation directives: $create, $connect, $connectOrCreate, $disconnect, $set, $update, $delete, $upsert.

Which operators a field type offers (SQLite, in the served contract):

Which mode values a field takes (filterModes, pathFilterModes) is the adapter's fact about the database, not configuration: exempting mode removes it, but an exemption cannot name a single mode (COMPILER_UNAVAILABLE_CAPABILITY). See Filtering.

Numeric fields offer $increment, $decrement, $multiply, $divide on update. Where a relation may be projected or written (at the top of a record, in a bulk write) is the adapter's fact and is not configurable.

Example: write-only passwordHash everywhere, no User deletes for remote callers:

exemptions: {
  resources: { User: { fields: { passwordHash: ["select", "filter", "order"] } } },
},
client: {
  exposed: true,
  exemptions: { resources: { User: { operations: { delete: true } } } },
},

The client contract then has no delete family on User, passwordHash carries capabilities: { create: [], update: [] } (no select, filter or order), and framework.client.User.find.many({ select: ["id", "passwordHash"] }) answers A2004 / V1008: Field "passwordHash" is not selectable. The whole guide: Exposure.

transactionsStyle

"interactive" mounts POST <api>/_transactions and gives the generated client avClient.tx and avClient.transaction, and allows forceTransaction. "none" removes them for that layer. Any other value fails startup: transactionsStyle must be "none" or "interactive". A layer cannot offer transactions the adapter cannot perform.

client: { transactionsStyle: "none" },   // remote callers cannot run transaction plans

See Transactions.

limits

Each must be a finite non-negative integer (maxAllConcurrency: a whole number of at least 1); otherwise startup fails (CONFIG_INVALID_VALUE at limits.maxListLimit). An unknown name fails with CONFIG_UNKNOWN_PROPERTY (unknown limit property: foo).

limits: { maxListLimit: 100 },
client: { limits: { maxListLimit: 25 } },

With this configuration the served contract has "limits": { ..., "maxListLimit": 25, ... } and the application layer keeps 100. Client limits are part of the client contract, so changing them changes the contract hash.

pipelines

Stages around every operation of the layer. The same AvPipeline shape goes on a Resource, a family and a variant under resources. See Pipelines.

pipelines.cache is the one stage that does not add up: cache({ for, maxAge }) (from @aventara/core) on reads, at the root or client layer, a Resource, the find family or a find variant. The most specific level wins, and at one level client's replaces the root's. Anywhere else it is CONFIG_INVALID_VALUE. See Caching reads.

resources

Everything about one Resource. Keyed by your model names.

type AvConfigResource = {
  pipelines?: AvPipeline;                         // every operation of the Resource
  operations?: {
    [family]?: {
      pipelines?: AvPipeline;                     // every variant of the family
      forceTransaction?: boolean;
      [variant]?: { pipelines?: AvPipeline; forceTransaction?: boolean };
    };
  };
  transactions?: { pipelines?: AvTransactionPipeline };   // once per transaction with a top-level step on it
  fields?: {
    [field]?: {
      definition?: AvConfigFieldDefinition;       // root only
      pipelines?: {
        validators?: AvZCheck[];                  // scalar fields
        pipes?: AvFieldPipe[];                    // scalar fields
        compute?: { create?: AvComputeCreate; update?: AvComputeUpdate; read?: AvComputeRead };   // scalar fields
        guards?: AvFieldGuard[];                  // scalar and relation fields
      };
    };
  };
};

A relation field takes guards only: pipes or compute on one is COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED, validators COMPILER_INVALID_VALIDATOR. Every name must exist: an unknown Resource (COMPILER_UNKNOWN_RESOURCE), family or variant (COMPILER_UNAVAILABLE_OPERATION) or field (COMPILER_UNKNOWN_FIELD) stops startup. Configuring a level never exposes it.

defineResource<Model>()(name, rootBlock, { application?, client? }) from @aventara/core returns { root, application?, client? }, each { [name]: block }, typed exactly as resources.<name> in place at that layer, to spread into each layer's resources (resources: { ...post.root }, client: { resources: { ...post.client } }); a layer given no block is left out (Configuration).

Fields

resources.<Resource>.fields.<field>.definition describes a field. On a field the adapter discovered you may restate its own type, nullable and list, and give a Json field its json shape; anything else is refused. A field the adapter did not discover is added, as a virtual scalar field: it must state type, nullable and list, and its lifecycle is ["VIRTUAL"]. Only scalar fields can be added.

import { AvZ } from "@aventara/core/avz";

resources: {
  User: {
    fields: {
      displayName: {
        definition: { type: { scalar: "string" }, nullable: false, list: false, lifecycle: ["VIRTUAL"], capabilities: { select: true } },
        pipelines: { compute: { read: ({ record }: { record: Readonly<Record<string, unknown>> }) => `${record.name ?? "?"} <${record.email}>` } },
      },
    },
  },
  Post: {
    fields: { meta: { definition: { json: AvZ.object({ title: AvZ.string() }) } } },
  },
},

framework.application.User.find.many({ select: ["id", "displayName"], limit: 2 }) then returns [{"id":1,"displayName":"Ada <ada@example.com>"}, ...], and the field appears in the client contract with lifecycle: ["COMPUTED_ON_READ","VIRTUAL"].

Compute

Returning undefined keeps the current value. ctx is AvComputeContext: the $ facts and read operations only. A stage may be async.

Pipelines reference

type AvPipeline = {
  guards?:       AvGuard[];
  pipes?:        AvPipe[];
  hooks?:        { before?: AvBeforeHook[]; after?: AvAfterHook[] };
  interceptors?: AvInterceptor[];
  filters?:      AvFilter[];
  cache?:        { for: "user" | "anonymous" | "everyone"; maxAge: number };   // cache({ for, maxAge }), reads only
};

// resources.<R>.transactions.pipelines
type AvTransactionPipeline = {
  guards?:       AvTransactionGuard[];
  pipes?:        AvTransactionPipe[];
  hooks?:        { before?: AvTransactionBeforeHook[]; after?: AvTransactionAfterHook[] };
  interceptors?: AvTransactionInterceptor[];
  filters?:      AvTransactionFilter[];
};

before and after sit under hooks; written directly in a pipelines object they are refused (CONFIG_MOVED_PROPERTY).

Order: guards (layer, Resource, family, variant, then field write guards, then nested targets' guards), pipes (the operation's, then field pipes), write compute, the re-check (Aventara's own checks on what pipes and compute produced, then the validators on every value, computed ones included), interceptors entering outer to inner, before hooks outer to inner, the adapter call, read compute, after hooks inner to outer, interceptors unwinding inner to outer; filters on a failure. A refusal by a guard, a pipe's output or a validator runs no interceptor or hook. In a transaction, a guard, a pipe or a validator on a literal value no compute changes refuses before it opens; write compute and the re-check of computed and $ref values run inside it, and a refusal there rolls it back. At each level the root's stages run, then the overlay's. Full detail: Pipelines.

AvContext is what each operation stage receives:

import { AvError, type AvGuard } from "@aventara/core";

const requireSignIn: AvGuard = (ctx) => {
  if (ctx.$operation.family !== "find" && !ctx.$transport?.headers["authorization"]) {
    throw new AvError("A4000", "Sign in first.");
  }
  return true;
};
// client: { pipelines: { guards: [requireSignIn] } }

Denial answers (client layer): return false gives {"code":"A4001","cause":{"message":"Operation denied by a framework guard."}}; throw new AvError("A4002", "Deletes are policy-denied.") gives {"code":"A4002","cause":{"message":"Deletes are policy-denied."}}.

A non-framework error thrown from a stage becomes A3000 with the generic message Internal framework error.; the original goes to diagnostics. A pipe that returns arguments the server's own contract refuses becomes A3004 with the generic message A server pipeline produced invalid arguments. (Pipelines). In the Nest host, either one also writes one line to the server log (Request IDs and diagnostics).

Annotate a stage with its exported type (AvGuard, AvPipe, AvBeforeHook, AvAfterHook, AvInterceptor, AvFilter, ...), as above, when the configuration is an as const object (as the scaffold's is), or the parameter has no contextual type. Details: Pipelines.

describePrismaAdapter

From @aventara/prisma7-adapter. It takes discovery, provider and driver (the same three options as createPrismaAdapter, below) and returns the adapter's passive facts: the model, the driver's transaction capability, the referential actions and the computed fields. It takes no client and connects to nothing, so aventara-build can compile the Contracts from it. The scaffold's src/aventara.adapter.ts default-exports it:

// src/aventara.adapter.ts
import { describePrismaAdapter } from "@aventara/prisma7-adapter";
import { discovery } from "./generated/aventara/discovery.artifact.js";

export default describePrismaAdapter({
  discovery,
  provider: "postgresql",
  driver: "@prisma/adapter-pg",
});

createPrismaAdapter

From @aventara/prisma7-adapter. It is async and returns the adapter. Spread the description into it: createPrismaAdapter({ ...description, client }). It still checks the client against the discovery artifact; the description cannot, because it has no client.

isolationLevel values: "ReadUncommitted", "ReadCommitted", "RepeatableRead", "Snapshot", "Serializable". SQLite supports Serializable only; PostgreSQL supports all of them except Snapshot.

import adapter from "./aventara.adapter.js";

await createPrismaAdapter({
  ...adapter,                       // discovery, provider, driver and the rest of the description
  client: prisma,
  transactionOptions: { timeout: 10_000, isolationLevel: "Serializable" },
});

aventara-prisma7-generate

The aventara:prepare script runs this bin to write the discovery artifact, then runs aventara-build (CLI reference). Run it again whenever the Prisma schema changes (the scaffold also runs it on postinstall).

It needs a Prisma 7 CLI and typescript (below 7) resolvable from your project.

aventara-prisma7-generate --schema prisma/schema.prisma --client src/generated/prisma --provider sqlite --driver @prisma/adapter-better-sqlite3 --out src/generated/aventara/discovery.artifact.ts --config src/aventara.config.ts
resources: User, Category, Post

Refusals are one line on stderr:

aventara-prisma7-generate: --provider postgresql contradicts the schema's datasource `db` (/home/you/app/prisma/schema.prisma:6), which names provider "sqlite"; pass --provider sqlite.
aventara-prisma7-generate: the artifact file /app/src/generated/aventara/discovery.artifact.ts (--out) cannot be written: permission denied (EACCES).

Startup diagnostics

Every mistake is thrown as one AvConstructionError with stage ("configuration", "discovery" or "contract-compilation") and diagnostics, each { code, path, message, docs }; docs is the URL of the code's entry on Error codes. The complete table of codes, with examples, is on Error codes. The usual ones:

A stale prebuilt file is not an error. It prints one warning, AVENTARA_PREBUILT_STALE, and the framework compiles at startup (prebuilt).

Startup safety checks

A compiler diagnostic's path starts with the layer it is about: root., application. or client..

See also

• Configuration: the guided version.
• Exposure, Pipelines, Computed fields, Field validators
• Contract layers: how the root and overlays combine.
• Error codes: the codes a caller sees at runtime, and every startup code.
• NestJS API reference: handing the configuration to AventaraModule.
• Limits and safety