@aventara/core 1.0.0-rc.4 → 1.0.0-rc.8

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # @aventara/core
 
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- 1c8e4ee: Helpers typed off the façades compile again in projects that emit declarations. In 1.0.0-rc.7 a function that took
+  `Parameters<AppFramework["application"]["Post"]["find"]["many"]>[0]` and returned its `where` (or built a new one
+  from it, `{ AND: [args.where ?? {}, { published: { equals: true } }] }`) without a return type failed `nest build`
+  (and `tsc` with `"declaration": true`) with `TS4023: ... has or is using name 'ScalarFilterOperands' ... but cannot be
+  named`, usually beside `TS7056`. A nested write's data could fail the same way, or name `NO_ADVERTISED_MEMBER`, and a
+  nested `$update`'s `where` was written into the `.d.ts` as `any`. The declaration now names the argument types
+  `@aventara/core` exports (`AvWhereInput`, `AvUpdateDataInput`, `AvCreateDataInput`, ...), and these new exports cover
+  the rest:
+
+  - `AvScalarFilterOperands`: one field's filter operators, which a filter's `not` holds again.
+  - `AvScalarWhereInput`: the `where` of a nested `$update` or `$delete` that only takes plain fields.
+  - `AvNoAdvertisedMember`: a write member that advertises nothing; it takes `{}` and refuses every key.
+  - `AvSqlStatementBuilder` and `AvSqlStatementValue`: the type of `framework.appTx.$sql` and the values it binds.
+    A method returning `framework.appTx.$sql` failed with `TS2883`/`TS2742` before.
+
+  `framework.execute` and `framework.executeTransaction` take request types that `@aventara/core` exports:
+  `AvOperationRequest` (`AvApplicationOperationRequest`, `AvClientOperationRequest`, `AvAgentOperationRequest`),
+  `AvTransactionRequest` (`AvApplicationTransactionRequest`, `AvClientTransactionRequest`,
+  `AvAgentTransactionRequest`) and `AvRequestProtocol` (a remote request's `protocol`). They were named from
+  `@aventara/core/internal` (`FrameworkOperationRequest`, `FrameworkTransactionRequest`, ...), so a declaration that
+  spelled them reached into the package's internal entry. Those names are gone from `@aventara/core/internal`.
+
+  An adapter's `referentialActions` edges name the fields that hold the reference `referenceFields`, as a relation of
+  the Core Contract does. They were called `references`, which the Core Contract uses for the target's fields.
+
+  Reading a projecting variant's argument type (`Parameters<…["find"]["many"]>[0]`) also type-checks faster: about
+  6,000 type instantiations over a three-field model, where rc.7 took about 29,000. The part of the argument other than
+  `select`/`include` is now marked `NoInfer` in the call's parameter, so an editor shows that parameter as
+  `NoInfer<Omit<…>> & …`. What it accepts is unchanged.
+
+  A create's `data` type now states each required field once, as a required member (`Readonly<{ title: string; } & {
+  body?: ... }>` in an editor's expanded hover). Before, a required field appeared as an optional member beside a
+  separate `{ readonly title: WrittenValue }`, and a declaration file wrote both. What a create accepts and refuses is
+  unchanged.
+
+- Operation results read as their value types in an editor and in emitted declarations. A result field that is nullable,
+  an enum or a `boolean` (such as a `Boolean @default(false)` column) was shown as `AvScalarValueType<…>`, with the
+  whole Contract view as its argument, and a project with `"declaration": true` wrote that view into its `.d.ts` once
+  per such field: a Nest service of five methods with no return types came out at 524 lines. Those fields now read
+  `body: string | null`, `published: boolean`, `publishedAt: Date | null`, and that service's declaration is 44 lines.
+  A result, and a relation included in it, is shown as its fields rather than as `ProjectedFields<…>`. This covers
+  `framework.application` and `framework.client` results, the same fields in a write's `data`, and clients generated
+  by `avclient`. What each type accepts is unchanged.
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- f917c1c: A helper that reads `framework.contracts.core` compiles again in projects that emit declarations. In 1.0.0-rc.6 a
+  function returning a Resource or a field of the Core Contract without a return type, such as
+  `core.resources[resource]?.fields[relation]`, failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'relationOf' cannot be named without a reference to
+  'AvCoreField'` under TypeScript 6 (`TS2742` under 5.9), or with `TS4058`/`TS4023` naming `AvCoreResource`.
+  `@aventara/core` now exports the three types the Core Contract is written with: `AvCoreResource` (a Resource),
+  `AvCoreField` (one of its fields) and `AvCoreRelationField` (a relation field, with the target fields its reference
+  names in `references`).
+
+  A policy's startup check states the path once: `CONFIG_INVALID_VALUE at policy.engine.governed.Nope: "Nope" is no
+  Resource of the Core Contract`, where rc.6 repeated `policy.engine.governed.Nope:` inside the message. Each
+  diagnostic's `message` no longer starts with its `path`; read the path from `path`.
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- 1cf72e0: Typed policy engines compile again in projects that emit declarations. In 1.0.0-rc.5 an engine written
+  `as const satisfies AvPolicyEngine` failed `nest build` (and `tsc` with `"declaration": true`, which Nest's
+  `tsconfig.json` sets) with `TS2883: The inferred type of 'policyEngine' cannot be named without a reference to
+  'PolicyFieldsAccess'` under TypeScript 6, or `TS2742` under 5.9, and so did the configuration and the framework holding
+  it. `fieldsOf`'s question is now written out in full in `AvPolicyEngine`, so a declaration can spell it.
+
+  A read question's `action` is now typed `undefined`, so an engine can destructure it from either question:
+  `fieldsOf({ resource, access, action })`. A write question's `action` is `"create"` or `"update"`, as before.
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- 4795ff1: Two additions for policy engines. A Framework without a policy, and every Contract a caller is served, are unchanged.
+
+  - A policy engine can check a create whose row reaches another Resource through a relation. Discovery now states, on the end of a relation that holds the reference, which of the target's fields its reference fields name, pair by pair (`Note.campaign`: `referenceFields: ["campaignId"]`, `references: ["id"]`). An engine reads them from the model it is built from (a Prisma discovery artifact's `model`) or from `framework.contracts.core`, and asks one `exists` about the row they name: "a player creates a note only in a campaign they play in". Only the adapter's model and the Core Contract carry them. The Application, Client and Agent Contracts, `/_contract`, the MCP tools and every ClientContract hash are unchanged. The discovery artifact's model hash, and so a prebuilt Contracts file's fingerprint, change: regenerate the artifact and rebuild the prebuilt file.
+  - `fieldsOf({ access: "write" })` also names the action that writes the record, `action: "create" | "update"` (an upsert's branches each their own, a nested record its directive's), so an engine can lock a field on update and still let a create write it. A read question names none. An engine that ignores it keeps working.
+
+- 9e178ca: Fixes for applications that check requests with a policy engine. A Framework without a policy behaves as before.
+
+  - A cursor on a row the caller cannot read is answered exactly as a cursor on a row that does not exist, at the root and in a to-many relation, whatever values the caller sends beside the identifier. Before, the page started at the hidden row, so it told that the row exists and where its values sort. The Prisma adapter reads the cursor's row under the read scope first: one statement more for a cursor on a readable row, and only that read for one on a row the caller cannot read.
+  - A unique update with a nested write (`$create`, `$connect`, …) on a row the caller can read but not change answers `A4002`, as the same update without one does. It answered `A2003`. A row the caller cannot read still answers `A2003`.
+  - The `exists` questions a policy asks select the Resource's primary identifier, never another unique field such as a governed `email`.
+  - `policy.principal` may answer with a promise. A synchronous principal works as before; a rejection answers `A3000`, as a throw does.
+  - `AvConstructionError.message` names the first problem and how many more there are, for example `Aventara framework configuration validation failed: CONFIG_INVALID_TYPE at adapter.execute: adapter.execute must be a function (+2 more)`. `stage` and `diagnostics` are unchanged.
+
 ## 1.0.0-rc.4
 
 ### Patch Changes

package/ERRORS.md

@@ -1,6 +1,6 @@
 # Aventara error codes
 
-Every code `@aventara/core` 1.0.0-rc.4 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
+Every code `@aventara/core` 1.0.0-rc.8 answers, reports in a validation issue, or refuses to start with. Generated from `AvErrorCatalog` (exported by `@aventara/core`); do not edit.
 
 Branch on the code, never on the message. In code, `AvErrorCatalog[code]` gives the same entry: `{ code, kind, message, cause, fix, docs }`.
 

package/README.md

@@ -357,7 +357,11 @@ projection; name it to get it, `select: ["$defaults", "email"]`. A refusal answe
 Writes are checked too. A create asks `can` about each new row, whose rules may look rows up through `exists`. An
 update or delete acts only on rows the caller may change and read; a single-row one that misses answers `A4002` when
 the caller can read the row and `A2003` when it cannot. A field the write sends must be in
-`fieldsOf({ access: "write" })`. An update that moves a row out of what the caller reads, or fails an `after` condition
+`fieldsOf({ access: "write", action })`, `action` being `"create"` or `"update"` (an upsert's branches and a nested
+record's directive each their own), so a field can be locked on update and still written at create. A rule that
+reaches another Resource through a relation (a note only in a campaign its author plays in) reads which of the
+target's fields the reference names from the Core Contract (`framework.contracts.core`, a relation's `references`
+beside its `referenceFields`); no Contract a caller is served states them. An update that moves a row out of what the caller reads, or fails an `after` condition
 (`can` asked about the row the update returned), is rolled back. Where `transactionsStyle` is `"interactive"`, a
 checked write with a check after it (an update, a nested write) runs in a transaction of its own, and a create or
 delete checked before it runs is one statement; where it is `"none"`, a write that could only be checked after it runs

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

@@ -38,6 +38,14 @@ export type AvAdapterRelationField<M extends AvAdapterModel> = {
      * one. Absent on the end that holds no reference (`User.posts`); never empty.
      */
     readonly referenceFields?: readonly [string, ...string[]];
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in
+     * the same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`, so `Post.authorId` holds `User.id`). Stated only
+     * beside `referenceFields`, with as many entries; absent on the end that
+     * holds no reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
 };
 /** One field the adapter discovered: a scalar or a relation. */
 export type AvAdapterField<M extends AvAdapterModel> = AvAdapterScalarField<M> | AvAdapterRelationField<M>;

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

@@ -13,3 +13,12 @@ export type AvAdapterIdentifier<TFields extends Readonly<Record<string, AvAdapte
     AvAdapterScalarFieldKey<TFields>,
     ...AvAdapterScalarFieldKey<TFields>[]
 ];
+/**
+ * The Resource's identifier as the Adapter states it first: in the Adapter's
+ * own order (an ORM adapter's is its schema's, so the primary key). The Core
+ * Contract sorts identifiers for its hash, so its first one is the
+ * alphabetically first (`email` before `id`) and says nothing about which is
+ * the primary key; the model keeps the order it declared. Empty for a Resource
+ * the model does not hold or that has no identifier.
+ */
+export declare function adapterPrimaryIdentifier(model: AvAdapterModel, resource: string): readonly string[];

package/dist/adapters/adapter-identifier.js

@@ -1 +1,6 @@
-export {};
+export function adapterPrimaryIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}

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

@@ -6,12 +6,18 @@ import type { AvAdapterModel } from "./adapter-model.js";
  * Operation identity and arguments remain provider-neutral; adapters receive
  * only validated semantic argument objects, never raw transport input.
  *
- * One shape exists here only: the flat unique selector of an `update.unique` or
- * a `delete.unique` may carry `AND`, a list of conditions in the general
- * `where` grammar the selected row must also meet. A row the selector names
- * that misses them is a miss (the same `null` as a row that is not there). An
- * adapter must honour it or refuse the operation, never drop it: dropping it
- * would write a row the conditions exclude.
+ * Two shapes exist here only, both an `AND`: a list of conditions in the
+ * general `where` grammar the addressed row must also meet.
+ *
+ * - The flat unique selector of an `update.unique` or a `delete.unique` may
+ *   carry it. A row the selector names that misses them is a miss (the same
+ *   `null` as a row that is not there).
+ * - A `cursor` may carry it, at the root of a `find.many` and in a to-many
+ *   relation's arguments. A row the cursor names that misses them is a cursor
+ *   that names no row: the same answer as a cursor on a row that is not there.
+ *
+ * An adapter must honour it or refuse the operation, never drop it: dropping it
+ * would write a row the conditions exclude, or position a page at one.
  */
 export type AvAdapterOperation<M extends AvAdapterModel = AvAdapterModel> = AvOperationIdentity & {
     readonly resource: Extract<keyof M["resources"], string>;

package/dist/compiler/contract.compiler.js

@@ -81,15 +81,28 @@ function cloneAdapterField(field) {
         ...(Array.isArray(field.referenceFields) && field.referenceFields.length > 0
             ? { referenceFields: [...field.referenceFields] }
             : {}),
+        ...(Array.isArray(field.referenceFields) &&
+            Array.isArray(field.references) &&
+            field.references.length > 0 &&
+            field.references.length === field.referenceFields.length
+            ? { references: [...field.references] }
+            : {}),
     };
 }
-function pruneHiddenPairings(projection) {
+function pruneHiddenPairings(projection, references) {
     const resources = projection.resources;
     for (const [name, resource] of Object.entries(resources)) {
         for (const field of Object.values(resource.fields)) {
             if (field.kind !== "relation") {
                 continue;
             }
+            if (Array.isArray(field.references) &&
+                (references === "none" ||
+                    !wholePairing(resource.fields, Object.hasOwn(resources, String(field.target))
+                        ? resources[String(field.target)]?.fields
+                        : undefined, field.referenceFields, field.references))) {
+                delete field.references;
+            }
             if (Array.isArray(field.referenceFields)) {
                 const shown = field.referenceFields.filter((reference) => typeof reference === "string" &&
                     Object.hasOwn(resource.fields, reference) &&
@@ -113,6 +126,16 @@ function pruneHiddenPairings(projection) {
         }
     }
 }
+function wholePairing(fields, targetFields, referenceFields, references) {
+    const shownIn = (within, name) => typeof name === "string" &&
+        within !== undefined &&
+        Object.hasOwn(within, name) &&
+        within[name]?.kind === "scalar";
+    return (Array.isArray(referenceFields) &&
+        referenceFields.length === references.length &&
+        referenceFields.every((name) => shownIn(fields, name)) &&
+        references.every((name) => shownIn(targetFields, name)));
+}
 function cloneOperations(operations) {
     return cloneValue(operations);
 }
@@ -1008,7 +1031,7 @@ function projectCore(model, config, diagnostics) {
     const validators = compileValidatorTable(baseline.resources, scope.pipelines);
     const projection = projectExposure({ layer: "root", style: exposureStyle(scope), diagnostics }, baseline, baseline, scope.exemptions);
     qualifyFilterModes(projection);
-    pruneHiddenPairings(projection);
+    pruneHiddenPairings(projection, "shown");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, "root", baseline.resources, baseline.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);
@@ -1059,7 +1082,7 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
     qualifyFilterModes(projection);
-    pruneHiddenPairings(projection);
+    pruneHiddenPairings(projection, "none");
     projectCreateRequirements(model, projection.resources);
     checkHiddenRequirements(model, scopeName, baseline.resources, parent.resources, projection.resources, diagnostics);
     applyValidators(projection.resources, validators);

package/dist/config/framework-config.d.ts

@@ -90,7 +90,11 @@ export type AvConfig<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfigAn
      */
     readonly policy?: {
         readonly engine: AvPolicyEngine;
-        /** The request's principal, from its `ctx.$state` and its layer; `null` for an anonymous caller. */
+        /**
+         * The request's principal, from its `ctx.$state` and its layer; `null` for
+         * an anonymous caller. It may answer with a promise (rc.5), which is
+         * awaited; a throw or a rejection answers `A3000`.
+         */
         readonly principal: (facts: {
             readonly $state: AvState;
             readonly $origin: AvRequestOrigin;

package/dist/contracts/contract.d.ts

@@ -1,6 +1,7 @@
 import type { AvContractLimits } from "./contract-limits.js";
 import type { AvContractClientProtocol } from "./contract-protocol.js";
 import type { AvEnumDefinition } from "./enum-definition.js";
+import type { AvCoreField } from "./field.js";
 import type { ReferenceWriteLimit } from "./reference-write-limit.js";
 import type { AvResource } from "./resource.js";
 import type { AvScalarRegistry } from "./scalar.js";
@@ -24,8 +25,21 @@ export interface AvContract {
      */
     readonly referenceWrites?: ReferenceWriteLimit;
 }
-/** The Contract compiled from the root configuration. */
+/**
+ * The Contract compiled from the root configuration. Its relation fields also
+ * state the target's fields their reference names (`references`), which no
+ * other Contract carries.
+ */
 export interface AvContractCore extends AvContract {
+    /** The Resources, by name. */
+    readonly resources: Readonly<Record<string, AvCoreResource>>;
+}
+/**
+ * A Resource as the Core Contract states it: its fields are
+ * {@link AvCoreField}s, so its relation fields carry `references`.
+ */
+export interface AvCoreResource extends AvResource<AvContractCore> {
+    readonly fields: Readonly<Record<string, AvCoreField<AvContractCore>>>;
 }
 /** The Contract in-process calls run under (`framework.application`). */
 export interface AvContractApplication extends AvContract {

package/dist/contracts/field.d.ts

@@ -176,3 +176,20 @@ export type AvRelationField<C extends AvContract> = {
 };
 /** One field of a Resource: a scalar or a relation. */
 export type AvField<C extends AvContract> = AvScalarField<C> | AvRelationField<C>;
+/**
+ * A relation field as the Core Contract states it: an {@link AvRelationField}
+ * and, on the end that holds the reference, the target's fields it names.
+ */
+export type AvCoreRelationField<C extends AvContract> = AvRelationField<C> & {
+    /**
+     * The target's scalar fields that `referenceFields` name, pair by pair in the
+     * same order (`Post.author`: `referenceFields: ["authorId"]`,
+     * `references: ["id"]`). Present only beside a `referenceFields` the
+     * Contract states whole, and only when every one of them is a scalar field
+     * the Core Contract shows on the target; absent on the end that holds no
+     * reference, where the other end (`inverse`) states the pairs.
+     */
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource as the Core Contract states it. */
+export type AvCoreField<C extends AvContract> = AvScalarField<C> | AvCoreRelationField<C>;

package/dist/contracts/scalar-value-type.d.ts

@@ -78,5 +78,7 @@ type ListValue<List, Atom> = [List] extends [false] ? Atom : [List] extends [tru
  * - `list: true` → `readonly T[]`, whose entries are never `null`;
  * - `nullable: true` → `| null`, on the whole value, list or not.
  */
-export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never);
+export type AvScalarValueType<C extends AvContract, Field extends AvScalarField<C>, Forms extends ScalarForms = AvApplicationScalarForms> = [
+    ListValue<Field["list"], FieldAtom<C, Field, Forms>> | (true extends Field["nullable"] ? null : never)
+] extends [infer Value] ? Value : never;
 export {};

package/dist/framework/framework-construction.error.d.ts

@@ -15,7 +15,8 @@ export type AvConstructionDiagnostic = ConstructionProblem & {
 };
 /**
  * Thrown by {@link createFramework} when construction fails: `stage` says
- * where, and `diagnostics` lists every problem found there.
+ * where, and `diagnostics` lists every problem found there. The message names
+ * the first of them and how many more there are.
  */
 export declare class AvConstructionError extends Error {
     readonly stage: AvConstructionStage;

package/dist/framework/framework-construction.error.js

@@ -4,11 +4,21 @@ const FRAMEWORK_CONSTRUCTION_MESSAGES = {
     discovery: "Aventara adapter discovery validation failed",
     "contract-compilation": "Aventara contract compilation failed",
 };
+function constructionMessage(stage, diagnostics) {
+    const base = FRAMEWORK_CONSTRUCTION_MESSAGES[stage];
+    const [first] = diagnostics;
+    if (first === undefined) {
+        return base;
+    }
+    const where = first.path === "" ? "" : ` at ${first.path}`;
+    const more = diagnostics.length > 1 ? ` (+${diagnostics.length - 1} more)` : "";
+    return `${base}: ${first.code}${where}: ${first.message}${more}`;
+}
 export class AvConstructionError extends Error {
     stage;
     diagnostics;
     constructor(stage, diagnostics) {
-        super(FRAMEWORK_CONSTRUCTION_MESSAGES[stage]);
+        super(constructionMessage(stage, diagnostics));
         this.name = "AvConstructionError";
         this.stage = stage;
         this.diagnostics = diagnostics.map((diagnostic) => ({

package/dist/framework/framework.d.ts

@@ -2,10 +2,10 @@ import type { AvAdapterModel } from "../adapters/adapter-model.js";
 import type { AvContracts } from "../compiler/contract.compiler.js";
 import type { AvConfigAny } from "../config/any-framework-config.js";
 import type { AvMcpEndpoint } from "../config/config.resolver.js";
-import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationRequest } from "../runtime/operation-request.js";
 import type { AvOperationResponse } from "../runtime/operation-response.js";
 import type { AvTransactionRunner } from "../transactions/deferred-operation.js";
-import type { FrameworkTransactionRequest } from "../transactions/transaction-request.js";
+import type { AvTransactionRequest } from "../transactions/transaction-request.js";
 import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import type { ApplicationOperations, ApplicationTransactionBuilders, ClientOperations, ClientTransactionBuilders } from "./operation-facade.js";
 /**
@@ -72,7 +72,7 @@ export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfi
      * share one (`A2004`/`V1020` at the first step of the other origin).
      */
     readonly clientTx: ClientTransactionBuilders<M, Cfg>;
-    execute(request: FrameworkOperationRequest): Promise<AvOperationResponse>;
+    execute(request: AvOperationRequest): Promise<AvOperationResponse>;
     /**
      * Validates a whole transaction plan, then runs its operations one after
      * another inside one Adapter transaction. Answers `A1009` with each
@@ -83,7 +83,7 @@ export type AvFramework<M extends AvAdapterModel = AvAdapterModel, Cfg = AvConfi
      * Guards, pipes, hooks and interceptors run while the transaction is open, so
      * they should not perform network I/O or other slow work.
      */
-    executeTransaction(request: FrameworkTransactionRequest): Promise<AvTransactionResponse>;
+    executeTransaction(request: AvTransactionRequest): Promise<AvTransactionResponse>;
     /**
      * Runs handles from `appTx`/`clientTx` as one transaction:
      * `framework.transaction([h1, h2, …], options?)`. Resolves each handle's

package/dist/framework/operation-facade.d.ts

@@ -6,10 +6,10 @@ import type { AvOperationCall, AvOperationGrammar, DeferredArguments, DeferredPl
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import { type PolicyCaller } from "../policy/policy-request.js";
 import type { AvExecutionOptions } from "../runtime/execution-options.js";
-import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
+import type { AvOperationRequest } from "../runtime/operation-request.js";
 import type { AvOperationResponse } from "../runtime/operation-response.js";
 import type { AvState } from "../runtime/request-state.js";
-import type { SqlStatementBuilder } from "../transactions/sql-statement.js";
+import type { AvSqlStatementBuilder } from "../transactions/sql-statement.js";
 import type { AvTransactionResponse } from "../transactions/transaction-response.js";
 import type { AvContractApplicationView, ClientContractView } from "./contract-view.js";
 /**
@@ -94,9 +94,9 @@ type ApplicationSqlStep = {
     /**
      * A developer SQL step, written only as a tagged template:
      * ``framework.appTx.$sql<Row>`select … ${value}` ``. Every interpolated value
-     * is bound as a parameter. See {@link SqlStatementBuilder}.
+     * is bound as a parameter. See {@link AvSqlStatementBuilder}.
      */
-    readonly $sql: SqlStatementBuilder;
+    readonly $sql: AvSqlStatementBuilder;
 };
 /**
  * `framework.appTx`: one {@link AvAppTxResourceFacade} per Resource of `C`, the
@@ -149,8 +149,8 @@ type ComputeReadFacade<C> = C extends AvContract ? string extends AvResourceKey<
     };
 } : never;
 /** Builds the request one façade call hands to `execute`, under its request id and state. */
-export type FacadeRequest = (resource: string, identity: AvOperationIdentity, args: unknown, requestId: string, state: AvState | undefined) => FrameworkOperationRequest;
-type FacadeExecutor = (request: FrameworkOperationRequest, caller: PolicyCaller | undefined) => Promise<AvOperationResponse>;
+export type FacadeRequest = (resource: string, identity: AvOperationIdentity, args: unknown, requestId: string, state: AvState | undefined) => AvOperationRequest;
+type FacadeExecutor = (request: AvOperationRequest, caller: PolicyCaller | undefined) => Promise<AvOperationResponse>;
 /**
  * Builds a façade over `model`, the same object its types are read from, so a
  * call that type-checks always reaches `execute`: a Resource, variant or field

package/dist/index.d.ts

@@ -13,12 +13,12 @@ export type { AvConfigExact } from "./config/exact-framework-config.js";
 export type { AvConfig, AvConfigAddedFieldDefinition, AvConfigAgentLayer, AvConfigAny, AvConfigExemptions, AvConfigFamily, AvConfigFieldDefinition, AvConfigFieldLifecycleTrait, AvConfigKnownFieldDefinition, AvConfigLayer, AvConfigLayerAny, AvConfigLayerKind, AvConfigLimits, AvConfigMcp, AvConfigOperations, AvConfigOperationsExemption, AvConfigOverlayField, AvConfigRelationFieldExemption, AvConfigResource, AvConfigResourceExemption, AvConfigResourceFields, AvConfigResourceKey, AvConfigResources, AvConfigResourcesAny, AvConfigResourceTransactions, AvConfigRootField, AvConfigScalarFieldExemption, AvConfigScalarTypeRef, AvConfigVariant, AvFieldCompute, AvRelationFieldCapabilityName, AvRelationFieldPipeline, AvScalarFieldCapabilityName, AvScalarFieldPipeline, AvZCheck, AvZFormat, } from "./config/framework-config.js";
 export type { AvPipeline, AvTransactionPipeline, } from "./config/pipeline-config.js";
 export type { AvPaginationCapability, AvProjectionScope, AvRelationFilterCapability, AvRelationMutationDirective, AvRelationReducer, AvScalarFilterOperator, AvScalarMutationDirective, AvWriteScope, } from "./contracts/capability.js";
-export type { AvContract, AvContractAgent, AvContractApplication, AvContractClient, AvContractCore, } from "./contracts/contract.js";
+export type { AvContract, AvContractAgent, AvContractApplication, AvContractClient, AvContractCore, AvCoreResource, } from "./contracts/contract.js";
 export type { AvContractLimits } from "./contracts/contract-limits.js";
 export type { AvContractClientProtocol, AvContractHash, AvContractProtocol, } from "./contracts/contract-protocol.js";
 export type { AvCreateRequirementGroup, AvCreateRequirements, } from "./contracts/create-requirements.js";
 export type { AvEnumDefinition } from "./contracts/enum-definition.js";
-export type { AvField, AvProjectionScopes, AvRelationField, AvRelationFieldCapabilities, AvRelationMutationCapability, AvRelationProjectionCapability, AvRelationReducerCapability, AvScalarField, AvScalarFieldCapabilities, AvScalarFormat, AvScopedRelationMutations, AvScopedRelationReducers, AvWriteScopes, } from "./contracts/field.js";
+export type { AvCoreField, AvCoreRelationField, AvField, AvProjectionScopes, AvRelationField, AvRelationFieldCapabilities, AvRelationMutationCapability, AvRelationProjectionCapability, AvRelationReducerCapability, AvScalarField, AvScalarFieldCapabilities, AvScalarFormat, AvScopedRelationMutations, AvScopedRelationReducers, AvWriteScopes, } from "./contracts/field.js";
 export type { AvFieldCheck } from "./contracts/field-check.js";
 export type { AvIdentifier, AvScalarFieldKey } from "./contracts/identifier.js";
 export type { AvLifecycleTrait } from "./contracts/lifecycle-trait.js";
@@ -33,7 +33,7 @@ export type { AvFramework } from "./framework/framework.js";
 export type { AvConstructionDiagnostic, AvConstructionStage, } from "./framework/framework-construction.error.js";
 export { AvConstructionError } from "./framework/framework-construction.error.js";
 export type { AvApplicationFacade, AvApplicationFamilyFacade, AvApplicationPlainCall, AvApplicationProjectingCall, AvApplicationResourceFacade, AvAppTxFacade, AvAppTxFamilyFacade, AvAppTxPlainCall, AvAppTxProjectingCall, AvAppTxResourceFacade, AvClientFacade, AvClientFamilyFacade, AvClientPlainCall, AvClientProjectingCall, AvClientResourceFacade, AvClientTxFacade, AvClientTxFamilyFacade, AvClientTxPlainCall, AvClientTxProjectingCall, AvClientTxResourceFacade, } from "./framework/operation-facade.js";
-export type { AvCreateDataInput, AvCursorInput, AvFieldKey, AvIncludeInput, AvNullsOrder, AvOperationArgumentMap, AvOperationArgumentsFor, AvOrderByEntry, AvOrderByInput, AvProjectionEntry, AvRelationProjectionInput, AvResourceKey, AvScalarOrderInput, AvSelectInput, AvSortDirection, AvUniqueWhereInput, AvUpdateDataInput, AvWhereInput, } from "./operations/operation-arguments.js";
+export type { AvCreateDataInput, AvCursorInput, AvFieldKey, AvIncludeInput, AvNoAdvertisedMember, AvNullsOrder, AvOperationArgumentMap, AvOperationArgumentsFor, AvOrderByEntry, AvOrderByInput, AvProjectionEntry, AvRelationProjectionInput, AvResourceKey, AvScalarFilterOperands, AvScalarOrderInput, AvScalarWhereInput, AvSelectInput, AvSortDirection, AvUniqueWhereInput, AvUpdateDataInput, AvWhereInput, } from "./operations/operation-arguments.js";
 export type { AvDeferredOperationCall, AvOperationCall, AvOperationGrammar, AvOperationSlot, } from "./operations/operation-call.js";
 export type { AvOperationFamily, AvOperationIdentity, AvOperationVariant, } from "./operations/operation-identity.js";
 export type { AvOperationResultFor } from "./operations/operation-result.js";
@@ -48,14 +48,17 @@ export type { AvComputeContext, AvComputeCreate, AvComputeRead, AvComputeUpdate,
 export { AvAuthError, AvConflictError, AvContractMismatchError, AvError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./runtime/framework-error.js";
 export type { AvJsonValue } from "./runtime/json-value.js";
 export type { AvMisuseEvent, AvMisuseSink, } from "./runtime/misuse-reporter.js";
+export type { AvAgentOperationRequest, AvApplicationOperationRequest, AvClientOperationRequest, AvOperationRequest, AvRequestProtocol, } from "./runtime/operation-request.js";
 export type { AvCause, AvOperationCode, AvOperationErrorCode, AvOperationFailureResponse, AvOperationNoMatchResponse, AvOperationResponse, AvOperationSuccessCode, AvOperationSuccessDataCode, AvOperationSuccessResponse, } from "./runtime/operation-response.js";
 export type { AvAfterHook, AvBeforeHook, AvContext, AvFieldGuard, AvFieldPipe, AvFilter, AvGuard, AvInterceptor, AvPipe, AvTransactionAfterHook, AvTransactionBeforeHook, AvTransactionContext, AvTransactionFilter, AvTransactionGuard, AvTransactionInterceptor, AvTransactionPipe, AvTransactionStep, AvTransportContext, } from "./runtime/pipeline.js";
 export type { AvDeepReadonly } from "./runtime/readonly-value.js";
 export type { AvState } from "./runtime/request-state.js";
 export type { AvOperation, AvOperationHandle, AvOperationReferenceSurface, AvReferenceableField, AvReferenceBuilder, AvSingleRowResult, AvTransactionResults, AvTransactionRunner, } from "./transactions/deferred-operation.js";
+export type { AvSqlStatementBuilder, AvSqlStatementValue, } from "./transactions/sql-statement.js";
 export type { AvTransactionIntegrityViolation } from "./transactions/transaction-integrity-error.js";
 export { AvTransactionIntegrityError } from "./transactions/transaction-integrity-error.js";
 export type { AvTransactionReference } from "./transactions/transaction-reference.js";
+export type { AvAgentTransactionRequest, AvApplicationTransactionRequest, AvClientTransactionRequest, AvTransactionRequest, } from "./transactions/transaction-request.js";
 export type { AvTransactionCommittedResponse, AvTransactionResponse, } from "./transactions/transaction-response.js";
 export type { AvTransactionSlotPathViolation } from "./transactions/transaction-slot-path-error.js";
 export { AvTransactionSlotPathError } from "./transactions/transaction-slot-path-error.js";

package/dist/internal.d.ts

@@ -32,12 +32,11 @@ export type { AvDatabaseRefusal } from "./operations/database-refusal.js";
 export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export type { SemanticOperationArguments } from "./operations/operation-validator.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
+export { prebuiltFileChanges } from "./prebuilt/prebuilt-changes.js";
 export { emitPrebuiltContracts, prebuiltContractsOf, } from "./prebuilt/prebuilt-contracts.emitter.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";
 export type { AvErrorClassName } from "./runtime/framework-error-class.table.js";
 export { FRAMEWORK_ERROR_CLASS_OF } from "./runtime/framework-error-class.table.js";
-export type { AgentOperationRequest, ApplicationOperationRequest, ClientOperationRequest, ClientProtocolIdentity, FrameworkOperationRequest, } from "./runtime/operation-request.js";
 export { OPERATION_CODES } from "./runtime/operation-response.js";
 export type { BuiltinNonRow, OperationFingerprint, } from "./transactions/deferred-operation.js";
 export { computeOperationFingerprint } from "./transactions/operation-fingerprint.js";
-export type { AgentTransactionRequest, ApplicationTransactionRequest, ClientTransactionRequest, FrameworkTransactionRequest, } from "./transactions/transaction-request.js";

package/dist/internal.js

@@ -13,6 +13,7 @@ export { BUILT_IN_SCALARS } from "./contracts/scalar.js";
 export { TRANSACTION_CAPABILITIES } from "./contracts/transaction-capability.js";
 export { DATABASE_REFUSALS } from "./operations/database-refusal.js";
 export { VALIDATION_CODES } from "./operations/validation-code.js";
+export { prebuiltFileChanges } from "./prebuilt/prebuilt-changes.js";
 export { emitPrebuiltContracts, prebuiltContractsOf, } from "./prebuilt/prebuilt-contracts.emitter.js";
 export { mcpFailureReporterOf } from "./runtime/diagnostics-reporter.js";
 export { FRAMEWORK_ERROR_CLASS_OF } from "./runtime/framework-error-class.table.js";