@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

package/README.md

@@ -2,29 +2,293 @@
 
 The Aventara framework itself: the framework factory (`createFramework`), configuration and its resolution, the
 adapter interfaces an ORM adapter implements, Contract compilation and identity, validation, operation semantics, the
-pipeline runtime, transactions and execution. Its HTTP protocol — passive data and pure functions; it mounts nothing —
-is the separate entry point `@aventara/core/protocol`, which hosts such as `@aventara/nest` serve.
+pipeline runtime, transactions and execution. Its HTTP protocol is the separate entry point `@aventara/core/protocol`,
+which hosts such as `@aventara/nest` serve. The protocol is passive data and pure functions, and it mounts nothing.
 
-Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An application uses it through an adapter
-(`@aventara/prisma7-adapter`) and a host (`@aventara/nest`), and the usual way to set that up is the CLI.
+Core imports neither Prisma nor NestJS. An application uses it through an adapter (`@aventara/prisma7-adapter`) and a
+host (`@aventara/nest`), and the usual way to set that up is the CLI.
 
 ## Install
 
 ```bash
-npx @aventara/cli@pilot new my-api     # a new NestJS project with Prisma and Aventara
-npx @aventara/cli@pilot init           # or: add Aventara to an existing NestJS 12 project
-npm install @aventara/core@pilot       # the package on its own
+npx @aventara/cli@rc new my-api     # a new NestJS project with Prisma and Aventara
+npx @aventara/cli@rc init           # or: add Aventara to an existing NestJS 12 project
+npm install @aventara/core@rc       # the package on its own
 ```
 
 Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
 
 ## Documentation
 
-Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting a `Framework`)
-and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step); each package's README ships in its
+Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting an `AvFramework`)
+and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step). Each package's README ships in its
 tarball and shows on its npm page.
 
+## Typed Json fields
+
+A `Json` field is any JSON by default. To give it a shape, build one with `AvZ` from `@aventara/core/avz` and declare
+it as the field's `definition.json` in the configuration's `resources` tree:
+
+```ts
+import { AvZ } from "@aventara/core/avz";
+
+const postMeta = AvZ.object({
+  seo: AvZ.object({ title: AvZ.string(), keywords: AvZ.array(AvZ.string()) }),
+  status: AvZ.enum(["draft", "published"]),
+  rating: AvZ.optional(AvZ.int()),
+  cover: AvZ.nullable(AvZ.string()),
+});
+
+export type PostMeta = AvZ.infer<typeof postMeta>;
+
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  resources: { Post: { fields: { meta: { definition: { json: postMeta } } } } },
+});
+```
+
+`framework.application`, `framework.client`, `appTx` and `clientTx` read and write `Post.meta` as `PostMeta` instead
+of generic JSON. So does a client generated with `avclient`, which emits the type and needs no Zod.
+
+The shape is also one of `meta`'s validators. Every write of `meta` is checked against it before the database is
+asked: a create, update, upsert, nested write or transaction step, including a value a transaction step takes from an
+earlier step. It is checked where validators run, after every pipe and before any interceptor or hook, and its issues
+come in field order with the other validators'. A value out of shape is refused with `A2004`, one issue per problem at its
+exact path:
+
+```json
+{ "code": "V1001", "path": ["arguments", "data", "meta", "seo", "title"], "message": "Value must be a string." }
+```
+
+A missing key is `V1000`, a value outside an enum or a literal `V1002`, an integer outside the safe range `V1004`,
+and a key the shape does not declare `V1005`, once per key. Reads and filters are never checked against a shape, so
+rows written before the shape existed stay readable.
+
+`AvZ` has `string`, `number`, `int`, `boolean`, `null`, `literal`, `enum`, `object`, `array`, `tuple`, `record`,
+`union`, `discriminatedUnion`, `optional` and `nullable`. A shape node takes checks with `.check(...)`: a string takes
+length, pattern and format checks, a number or an integer takes bounds and `multipleOf`, and an array takes
+`AvZ.minItems`/`AvZ.maxItems`, as in `AvZ.string().check(AvZ.maxLength(80))`. There are no refinements, transforms or
+defaults. Objects are closed: a key the shape does not declare is refused. `optional` marks an object key that may be
+left out.
+
+Only a field the adapter discovered as `Json` takes a shape. The shape cannot admit `null` or absence at its top
+level; whether the field may be `null` comes from your schema. A shape is built with `AvZ` only. A Zod schema is
+refused, both as a type error and when the framework starts.
+
+The shape is part of the ClientContract, as JSON Schema. Adding or changing one changes the ClientContract hash, so
+regenerate the client.
+
+The shape types `AvZShape`, `AvZObject`, `AvZOptional` and `AvZNullable` are exported so a project that emits
+declarations can name the shapes it exports.
+
+`@aventara/core/avz` is the only entry that loads Zod (`zod/mini`); an application that declares no shape never loads
+it.
+
+## Server-side calls resolve their data and throw their failures
+
+`framework.application`, `framework.client`, `framework.transaction([...])` and a pipeline's `ctx` calls settle the way
+a generated client does: they resolve the data (a row, a list, a count, `null` for a `first` that matched nothing; a
+committed transaction its steps' results in order) and throw every failure as the `AvError` subclass of its code's
+class, exported from `@aventara/core`:
+
+```ts
+import { AvNotFoundError, AvValidationError } from "@aventara/core";
+
+try {
+  const post = await framework.application.Post.update.unique({ where: { id }, data: { title } });
+} catch (error) {
+  if (error instanceof AvNotFoundError) return null;        // A2003
+  if (error instanceof AvValidationError) throw badRequest(error.cause.issues);
+  throw error;
+}
+```
+
+| Class                     | Codes                                       |
+| ------------------------- | ------------------------------------------- |
+| `AvProtocolError`         | A2000, A2001, A2002, A2006, A2010–A2012     |
+| `AvNotFoundError`         | A2003                                       |
+| `AvValidationError`       | A2004, A2007, A2009                         |
+| `AvContractMismatchError` | A2005                                       |
+| `AvConflictError`         | A2008, A2013, A2014                         |
+| `AvInternalError`         | A3000–A3004                                 |
+| `AvAuthError`             | A4000–A4002                                 |
+
+`error.code` and `error.cause` are the envelope's (a transaction's `cause.operation` names the failing step). The
+generated client throws the same classes by the same table. `framework.execute` and `framework.executeTransaction`, the
+entries a transport calls, still answer the envelope.
+
+## Required create fields are typed
+
+Each Resource's Contract states what a create cannot do without (`createRequirements`), as the adapter reads it off
+the database schema: the fields every create must write, and each required relation, which a create writes either as
+the relation or through the fields that hold its reference, never both. The façades, `appTx`/`clientTx`, a stage's
+`ctx` and the generated client type every create payload by it:
+
+```ts
+await framework.application.Post.create.one({ data: { title: "Hi", authorId } });          // ok
+await framework.application.Post.create.one({ data: { title: "Hi", author: { $connect: { id: authorId } } } }); // ok
+// @ts-expect-error neither `author` nor `authorId`
+await framework.application.Post.create.one({ data: { title: "Hi" } });
+// @ts-expect-error `author` and `authorId` both
+await framework.application.Post.create.one({ data: { title: "Hi", authorId, author: { $connect: { id: authorId } } } });
+```
+
+It covers `create.one`'s `data`, every `create.many` record, `upsert`'s `create`, and nested `$create`,
+`$connectOrCreate` and `$upsert` payloads, where the relation the create is nested through is supplied by its parent.
+A `$ref` satisfies a field. Each layer's Contract states only what that layer lets a caller write: hide `authorId` and
+`author` alone is required; hide `author` and `authorId` is. A field a `compute.create` stage fills is not required,
+whether the stage is written inline in `createFramework({...})`, in a `defineResource` block or in a typed config.
+The runtime still refuses what the types refuse (`A2004`, `V1000` or `V1012`).
+
+A `create.many` or `create.count` record cannot write a relation, so there `authorId` is required. A layer that hides
+`authorId` while it keeps those variants fails at startup (`COMPILER_HIDDEN_REQUIRED_FIELD`): expose `authorId`, give
+it a `compute.create`, or exempt `create.many` and `create.count` in that layer
+(`exemptions: { resources: { Post: { fields: { authorId: true }, operations: { create: ["many", "count"] } } } }`).
+
+A field your operation pipe fills server-side is now required of the caller. Give it a `compute.create` stage (or a
+database default) so callers can leave it out, or have them pass it.
+
+## Returning a façade from a method
+
+A Nest project emits declarations (`declaration: true`), so a method without a return type has its type written out.
+Every node of the typed façades has a name for that: a whole surface (`AvApplicationFacade`), one Resource
+(`AvApplicationResourceFacade`), one family (`AvApplicationFamilyFacade`), and the same three for `client`, `appTx` and
+`clientTx` (`AvClientFacade`, `AvAppTxResourceFacade`, …). The declaration writes the name, with the Contract view as
+its argument, so this compiles:
+
+```ts
+@Injectable()
+export class PostsService {
+  constructor(@InjectFramework() private readonly framework: AppFramework) {}
+
+  posts() {
+    return this.framework.application.Post;
+  }
+}
+```
+
+The view is written out in full, about 400 KB of declaration per such method over 50 Resources. Give the method a
+return type to keep it small: `AppFramework["application"]["Post"]` is written as that reference, about 0.2 KB.
+
+```ts
+posts(): AppFramework["application"]["Post"] {
+  return this.framework.application.Post;
+}
+```
+
+A variant (`this.framework.application.Post.find.many`) is a call type the declaration cannot name: give that method a
+return type, or return the call's result, whose row type is small. An application that publishes no declarations can
+set `"declaration": false` and skip the question.
+
+An exported `defineResource(...)` result, and an exported configuration or Framework builder holding typed stages,
+need no annotation: their stages are written by their public types (`readonly AvGuard[]`, `readonly AvPipe[]`, …),
+never with the model the inline stages were typed from.
+
+## Server-side calls copy their input
+
+`framework.application`, `framework.client`, `framework.execute`, `framework.executeTransaction`, and the `appTx` /
+`clientTx` builders read what you pass them once, when you call them, and copy it into plain data the framework owns.
+Validation, your guards and pipes, computed values and the adapter all see only the copy, and your stages see it
+frozen: only a pipe changes the arguments, by returning new ones, so what the validators checked is what the adapter
+writes. In practice:
+
+- Changing your object afterwards changes nothing. An Immer draft revoked after `produce`, or a reactive store that
+  moves on, is safe to pass, because the call already has its own copy.
+- A live Proxy (Vue `reactive`, MobX) works: it is read through its traps once.
+- `Date`, `AvDecimal` and `Uint8Array` (a Node `Buffer` too) are copied as themselves; `bigint` and other primitives
+  are values.
+- Arrays and plain objects (`{}` or `Object.create(null)`) are copied with their own enumerable string keys, like JSON:
+  inherited, non-enumerable and symbol keys are dropped. Any other object, such as a class instance or a `Map`, is
+  refused.
+- A value that cannot be read (a revoked Proxy, a getter that throws) is refused too. Both refusals are errors in your
+  request, not the server's: `A2004` with one `V1001` at the value's path (`["arguments", …]`, or
+  `["operations", i, "args", …]` with `cause.operation` in a transaction), before any guard, pipe or adapter runs:
+
+  ```json
+  { "code": "V1001", "path": ["arguments", "where", "id"], "message": "Value could not be read." }
+  ```
+
+  A builder never throws: `appTx`/`clientTx` keep the refusal, and `framework.transaction([...])` throws it as an
+  `AvValidationError`.
+
+To count these refusals, set `misuse` at the root of the configuration, beside `diagnostics`:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  adapter,
+  misuse: (event) => metrics.increment("aventara.misuse", { kind: event.kind }),
+});
+```
+
+It receives one `AvMisuseEvent` per refusal, never the value itself. The event has `kind` (`"unreadable-value"` or
+`"non-plain-value"`), the `path` the caller received, and `origin`, `resource`, `family`, `variant` and the
+transaction step (`operation`) when they could be read. It cannot change the response: an error it throws, or a
+promise it rejects, is ignored. `diagnostics` keeps receiving the server's own unexpected failures, and nothing is
+reported to both.
+
+HTTP requests are not copied twice. A body that `protocol.handleOperation` / `handleTransaction` parse from raw content
+(as `@aventara/nest` hands it to them) is already plain data. A body your host parsed itself, passed as
+`{ kind: "parsed" }`, is copied like any server-side input.
+
+## Developer SQL in an application transaction
+
+`framework.appTx.$sql` adds a SQL statement to an application transaction. It is written only as a tagged template, and
+every interpolated value is a bound parameter, never part of the SQL text:
+
+```ts
+const post = framework.appTx.Post.create.one({ data: { title, authorId }, select: ["id"] });
+const job = framework.appTx.$sql<{ msg_id: bigint }>`
+  select pgmq.send('jobs', jsonb_build_object('postId', ${post.$ref("id")}))`;
+
+const [created, rows] = await framework.transaction([post, job]);
+// rows is { msg_id: bigint }[]; without <Row> it is unknown[]
+```
+
+- The statement runs in plan order, in the same database transaction as the other steps. If it fails, or a later step
+  fails, everything rolls back.
+- A value is a string, number, boolean, `bigint`, `null`, `Date`, `AvDecimal`, `Uint8Array`, a JSON value (a plain
+  object or array, bound as JSON text, so cast it: `${value}::jsonb`), or a `$ref` to an earlier step's field, which
+  is read after that step ran and then bound. Values are copied like every other input (see above).
+- The SQL text is static. A table or column name cannot come from a value.
+- A later step cannot `$ref` a SQL step's rows (`A2007`/`V1010`).
+- No guard, pipe, hook, interceptor or filter runs around a SQL step. A SQL error is answered as the adapter
+  classifies it (a uniqueness or reference violation is `A2008`, anything else `A3001`).
+- A stage's `ctx.$sql` runs the same bound template at once. Inside a transaction it joins it; outside one it is a plain
+  statement, with no transaction opened around it.
+- It exists only here. `clientTx` has no `$sql`, the ClientContract carries nothing of it, and `/_transactions` cannot
+  express it. The adapter must support it (`@aventara/prisma7-adapter` does wherever it runs transactions); otherwise a
+  plan holding one is refused with `A2002`.
+
+Aventara itself never writes raw SQL. This tagged template is the only way SQL reaches the database, and the SQL is
+yours.
+
+## The agent layer
+
+`agent` is a layer for calls an AI agent makes, served over MCP. It narrows the view of the layer it `extends`
+(`"client"` when left out, or `"application"`, or `"root"`) and never widens it; its stages run after that layer's, and
+each one sees `ctx.$origin === "agent"`:
+
+```ts
+const framework = await createFramework({
+  api: "/api",
+  mcp: "/mcp",
+  adapter,
+  agent: {
+    exposed: true,
+    exemptions: { resources: { Post: { operations: { delete: true } } } },
+    pipelines: { guards: [(ctx) => ctx.$state.user !== undefined] },
+  },
+});
+```
+
+It compiles to `framework.contracts.agent`, identified by its own hash, and `framework.mcp` is the resolved MCP
+endpoint. A host runs agent calls through `AvProtocol.bind(framework, { origin: "agent" })`, which validates them
+exactly as client calls are validated, against the Agent Contract.
+
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/adapters/adapter-discovery-diagnostic.d.ts

@@ -1,8 +1,8 @@
-/** Codes of {@link AdapterDiscoveryDiagnostic}. */
-export type AdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
+/** Codes of {@link AvAdapterDiscoveryDiagnostic}. */
+export type AvAdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
 /** A problem found in what the adapter discovered, reported at framework construction. */
-export type AdapterDiscoveryDiagnostic = {
-    readonly code: AdapterDiscoveryDiagnosticCode;
+export type AvAdapterDiscoveryDiagnostic = {
+    readonly code: AvAdapterDiscoveryDiagnosticCode;
     readonly path: "adapter.transactions";
     readonly message: string;
 };

package/dist/adapters/adapter-field.d.ts

@@ -1,29 +1,29 @@
-import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
-import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvRelationFieldCapabilities, AvScalarFieldCapabilities, AvScalarFormat } from "../contracts/field.js";
+import type { AvLifecycleTrait } from "../contracts/lifecycle-trait.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** Provider-observable lifecycle facts available during adapter discovery. */
-export type AdapterLifecycleTrait = Extract<LifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
+export type AvAdapterLifecycleTrait = Extract<AvLifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
 /** Scalar-shaped provider field expressed only in Aventara vocabulary. */
-export type AdapterScalarField<M extends AdapterModel> = {
+export type AvAdapterScalarField<M extends AvAdapterModel> = {
     readonly kind: "scalar";
     readonly type: {
         readonly scalar: Extract<keyof M["scalars"], string>;
     } | {
         readonly enum: Extract<keyof M["enums"], string>;
     };
-    readonly format?: ScalarFormat;
+    readonly format?: AvScalarFormat;
     readonly nullable: boolean;
     readonly list: boolean;
-    readonly lifecycle: readonly AdapterLifecycleTrait[];
-    readonly capabilities: ScalarFieldCapabilities;
+    readonly lifecycle: readonly AvAdapterLifecycleTrait[];
+    readonly capabilities: AvScalarFieldCapabilities;
 };
 /** A discovered relation field; the `target` Resource describes the related row. */
-export type AdapterRelationField<M extends AdapterModel> = {
+export type AvAdapterRelationField<M extends AvAdapterModel> = {
     readonly kind: "relation";
     readonly target: Extract<keyof M["resources"], string>;
     readonly cardinality: "one" | "many";
     readonly nullable: boolean;
-    readonly capabilities: RelationFieldCapabilities;
+    readonly capabilities: AvRelationFieldCapabilities;
 };
 /** One field the adapter discovered: a scalar or a relation. */
-export type AdapterField<M extends AdapterModel> = AdapterScalarField<M> | AdapterRelationField<M>;
+export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

package/dist/adapters/adapter-identifier.d.ts

@@ -1,7 +1,7 @@
-import type { AdapterField } from "./adapter-field.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvAdapterField } from "./adapter-field.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** Keys of `TFields` whose discovered field can be scalar-shaped. */
-export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = Extract<{
+export type AvAdapterScalarFieldKey<TFields extends Readonly<Record<string, AvAdapterField<AvAdapterModel>>>> = Extract<{
     [K in keyof TFields]: [
         Extract<TFields[K], {
             readonly kind: "scalar";
@@ -9,7 +9,7 @@ export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, Adapte
     ] extends [never] ? never : K;
 }[keyof TFields], string>;
 /** Non-empty scalar-field tuple discovered as provider uniqueness. */
-export type AdapterIdentifier<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = readonly [
-    AdapterScalarFieldKey<TFields>,
-    ...AdapterScalarFieldKey<TFields>[]
+export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapterField<AvAdapterModel>>>> = readonly [
+    AvAdapterScalarFieldKey<TFields>,
+    ...AvAdapterScalarFieldKey<TFields>[]
 ];

package/dist/adapters/adapter-model.d.ts

@@ -1,18 +1,26 @@
-import type { EnumDefinition } from "../contracts/enum-definition.js";
-import type { ScalarRegistry } from "../contracts/scalar.js";
-import type { TransactionCapability } from "../contracts/transaction-capability.js";
-import type { AdapterResource } from "./adapter-resource.js";
+import type { AvEnumDefinition } from "../contracts/enum-definition.js";
+import type { ReferenceWriteLimit } from "../contracts/reference-write-limit.js";
+import type { AvScalarRegistry } from "../contracts/scalar.js";
+import type { AvTransactionCapability } from "../contracts/transaction-capability.js";
+import type { AvAdapterResource } from "./adapter-resource.js";
 /**
  * Canonical provider-discovery facts before framework configuration or
  * Contract compilation is applied.
  */
-export interface AdapterModel {
+export interface AvAdapterModel {
     /** The scalar types the data source supports. */
-    readonly scalars: ScalarRegistry;
+    readonly scalars: AvScalarRegistry;
     /** The enums the data source declares, by name. */
-    readonly enums: Readonly<Record<string, EnumDefinition>>;
+    readonly enums: Readonly<Record<string, AvEnumDefinition>>;
     /** The discovered Resources, by name. */
-    readonly resources: Readonly<Record<string, AdapterResource<this>>>;
+    readonly resources: Readonly<Record<string, AvAdapterResource<this>>>;
     /** Whether the adapter can run interactive transactions. */
-    readonly transactions: TransactionCapability;
+    readonly transactions: AvTransactionCapability;
+    /**
+     * `"uniform"` when the data source takes one record's references only one
+     * way at a time: every relation that holds a reference written as a
+     * relation, or every one through its reference fields. Absent: each relation
+     * either way. Compiled into every Contract.
+     */
+    readonly referenceWrites?: ReferenceWriteLimit;
 }

package/dist/adapters/adapter-operation-executor.interface.d.ts

@@ -1,10 +1,10 @@
-import type { AdapterModel } from "./adapter-model.js";
-import type { AdapterOperation } from "./adapter-operation.js";
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperation } from "./adapter-operation.js";
 /**
  * Executes one operation against the provider, directly or inside a provider
  * transaction.
  */
-export interface AdapterOperationExecutor<M extends AdapterModel = AdapterModel> {
+export interface AvAdapterOperationExecutor<M extends AvAdapterModel = AvAdapterModel> {
     /** Runs one validated operation and resolves its raw result. */
-    execute(operation: AdapterOperation<M>): Promise<unknown>;
+    execute(operation: AvAdapterOperation<M>): Promise<unknown>;
 }

package/dist/adapters/adapter-operation.d.ts

@@ -1,12 +1,12 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /**
  * Provider execution request after framework semantic validation.
  * Operation identity and arguments remain provider-neutral; adapters receive
  * only validated semantic argument objects, never raw transport input.
  */
-export type AdapterOperation<M extends AdapterModel = AdapterModel> = OperationIdentity & {
+export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;
     readonly arguments: SemanticOperationArguments;
 };

package/dist/adapters/adapter-resource.d.ts

@@ -1,20 +1,29 @@
-import type { ResourceOperations } from "../contracts/resource-operations.js";
-import type { AdapterField } from "./adapter-field.js";
-import type { AdapterIdentifier } from "./adapter-identifier.js";
-import type { AdapterModel } from "./adapter-model.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
+import type { AvResourceOperations } from "../contracts/resource-operations.js";
+import type { AvAdapterField } from "./adapter-field.js";
+import type { AvAdapterIdentifier } from "./adapter-identifier.js";
+import type { AvAdapterModel } from "./adapter-model.js";
 /** A discovered Resource's fields, by name. */
-export type AdapterFieldMap<M extends AdapterModel> = Readonly<Record<string, AdapterField<M>>>;
+export type AvAdapterFieldMap<M extends AvAdapterModel> = Readonly<Record<string, AvAdapterField<M>>>;
 /**
  * The field names the adapter discovered for Resource `R`, before any
  * configuration adds to them.
  */
-export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
+export type AvAdapterFieldKey<M extends AvAdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
 /** Provider-discovered facts for one Aventara Resource candidate. */
-export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
+export type AvAdapterResource<M extends AvAdapterModel, TFields extends AvAdapterFieldMap<M> = AvAdapterFieldMap<M>> = {
     /** The Resource's fields, by name. */
     readonly fields: TFields;
     /** The field tuples that identify at most one row. */
-    readonly identifiers: readonly AdapterIdentifier<TFields>[];
+    readonly identifiers: readonly AvAdapterIdentifier<TFields>[];
     /** The standard operations the data source can run for this Resource. */
-    readonly operations: ResourceOperations;
+    readonly operations: AvResourceOperations;
+    /**
+     * What a create cannot do without, in the store's own terms: every field it
+     * requires, every required to-one relation with its reference fields, and
+     * the relation (`parentSupplies`) through which a nested create gets them
+     * from its parent. Absent when it requires nothing, or when the adapter
+     * cannot say; nothing is then checked or typed before the store.
+     */
+    readonly createRequirements?: AvCreateRequirements;
 };

package/dist/adapters/adapter-sql-statement.d.ts

@@ -0,0 +1,19 @@
+import type { AvDecimal } from "../runtime/decimal.js";
+import type { AvJsonValue } from "../runtime/json-value.js";
+/**
+ * One value a developer SQL statement binds, after every `$ref` in it was
+ * resolved: a primitive, a `Date`, a {@link AvDecimal}, a `Uint8Array`, or a
+ * plain object or array, which is a JSON value and is bound as JSON text. Never
+ * spliced into the statement's text.
+ */
+export type AvAdapterSqlValue = string | number | boolean | bigint | null | Date | AvDecimal | Uint8Array | AvJsonValue;
+/**
+ * One developer SQL statement, as `framework.appTx.$sql` wrote it: the static
+ * text of its tagged template, and the values written between those pieces, in
+ * order. `strings` holds exactly one entry more than `values`. The adapter binds
+ * every value as a parameter of the statement; no value ever becomes SQL text.
+ */
+export type AvAdapterSqlStatement = {
+    readonly strings: readonly string[];
+    readonly values: readonly AvAdapterSqlValue[];
+};

package/dist/adapters/adapter-transaction-executor.interface.d.ts

@@ -0,0 +1,19 @@
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterSqlStatement } from "./adapter-sql-statement.js";
+/**
+ * What an Adapter's `transaction` callback is handed: the transaction-scoped
+ * operation executor, and — when the Adapter declares `sqlStatements` — the
+ * statement runner `framework.appTx.$sql` steps run through.
+ */
+export interface AvAdapterTransactionExecutor<M extends AvAdapterModel = AvAdapterModel> extends AvAdapterOperationExecutor<M> {
+    /**
+     * Runs one developer SQL statement on the open transaction, every value bound
+     * as a parameter, and resolves the rows it returned (none for a statement that
+     * returns no rows). Present exactly when the Adapter declares `sqlStatements`.
+     *
+     * A failure is thrown like an operation's: a deliberate `AvError` for
+     * an outcome the Adapter classified, anything else to be answered `A3001`.
+     */
+    executeSql?(statement: AvAdapterSqlStatement): Promise<readonly unknown[]>;
+}

package/dist/adapters/adapter.interface.d.ts

@@ -1,46 +1,70 @@
-import type { CreateRequirementTable } from "../runtime/create-requirement.js";
 import type { ReferentialActionTable } from "../runtime/referential-action.js";
-import type { AdapterModel } from "./adapter-model.js";
-import type { AdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterModel } from "./adapter-model.js";
+import type { AvAdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+import type { AvAdapterSqlStatement } from "./adapter-sql-statement.js";
+import type { AvAdapterTransactionExecutor } from "./adapter-transaction-executor.interface.js";
 /** Provider-specific implementation of Aventara discovery and execution. */
-export interface Adapter<M extends AdapterModel = AdapterModel> extends AdapterOperationExecutor<M> {
+export interface AvAdapter<M extends AvAdapterModel = AvAdapterModel> extends AvAdapterOperationExecutor<M> {
     /**
      * What the adapter discovered about the data source, in Aventara's vocabulary.
      * Read once, synchronously, when the framework is constructed.
      */
     readonly model: M;
     /**
-     * Optional referential actions: for each Resource that holds a reference,
-     * what deleting a referenced row does to its rows. Read once when the
-     * framework is constructed; never part of a Contract or its hash.
+     * Optional referential actions: for each Resource that holds a reference, every
+     * relation holding one: the fields that hold it (`references`) and what deleting a
+     * referenced row does to its rows. Read once when the framework is constructed;
+     * never part of a Contract or its hash.
+     *
+     * An edge listed under Resource `R` says that deleting a `target` row does
+     * `onDelete` to rows of `R`, and that `R`'s `references` fields hold the relation
+     * `field`'s reference.
      *
-     * An edge listed under Resource `R` says **deleting a `target` row does
-     * `onDelete` to rows of `R`**.
+     * The same edges say which side of a relation holds its key: a nested `$connect`,
+     * `$disconnect` or `$set` on a to-one relation the parent holds runs none of the
+     * target's stages, and otherwise runs the target's `update` guards.
      *
-     * When absent, no cascade is planned and no transaction plan is refused
-     * because of one (`V1019`).
+     * When absent, no cascade is planned and no transaction plan is refused because of
+     * one (`V1019`); a write that sets a relation and a field holding its reference
+     * both is not refused before the store; and every nested `$connect`, `$disconnect`
+     * or `$set` runs the target's `update` guards.
      */
     readonly referentialActions?: ReferentialActionTable;
     /**
-     * Optional create requirements: for each Resource, the values its store
-     * cannot create a row without. Read once when the framework is constructed;
-     * never part of a Contract or its hash.
+     * Optional: `true` when the Adapter runs developer SQL statements: standalone
+     * through its own {@link executeSql}, and, when it has `transaction`, inside a
+     * transaction through the `executeSql` of the executor that callback is handed
+     * (`AvAdapterTransactionExecutor.executeSql`). `framework.appTx.$sql` steps and
+     * `ctx.$sql` need it. Read once when the framework is constructed; never part
+     * of a Contract or its hash.
+     *
+     * When absent, a plan holding an `appTx.$sql` step is refused before the
+     * transaction opens (`A2002`/`V1006` at the step), and so is every `ctx.$sql`.
+     */
+    readonly sqlStatements?: boolean;
+    /**
+     * Runs one developer SQL statement outside any transaction, as a plain
+     * statement, every value bound as a parameter, and resolves the rows it
+     * returned (none for a statement that returns no rows). Present exactly when
+     * the Adapter declares `sqlStatements`. `ctx.$sql` outside a transaction runs
+     * through it.
      *
-     * When absent, creates are not checked for missing values before they reach
-     * the store.
+     * A failure is thrown like an operation's: a deliberate `AvError` for an
+     * outcome the Adapter classified, anything else to be answered `A3001`.
      */
-    readonly createRequirements?: CreateRequirementTable;
+    executeSql?(statement: AvAdapterSqlStatement): Promise<readonly unknown[]>;
     /**
      * Optional callback transaction capability, required exactly when the
      * discovered model declares `transactions: "interactive"`. The callback
-     * receives only a transaction-scoped operation executor, never the provider
-     * client itself, and every operation of a plan executes through it.
+     * receives only a transaction-scoped executor, never the provider client
+     * itself, and every step of a plan executes through it.
      *
-     * The implementation must reject with the exact value `work` threw — by identity,
-     * never a wrapper — and must not resolve after `work` rejected; rollback is
-     * implied by that rejection. Guards, pipes, hooks and interceptors of every plan
-     * operation run inside `work` while the provider transaction is open, so they must
-     * not perform network I/O or unrelated slow work.
+     * The implementation must reject with the exact value `work` threw (by identity,
+     * never a wrapper) and must not resolve after `work` rejected; rollback is
+     * implied by that rejection. Every step's interceptors and hooks, and the touched
+     * Resources' transaction stages, run inside `work` while the provider transaction
+     * is open, so they must not perform network I/O or unrelated slow work. A step's
+     * guards, pipes and validators run before it opens.
      */
-    transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
+    transaction?<T>(work: (executor: AvAdapterTransactionExecutor<M>) => Promise<T>): Promise<T>;
 }