@aventara/core 1.0.0-rc.1 → 1.0.0-rc.10

package/dist/runtime/field-stage.runtime.js

@@ -1,3 +1,4 @@
+import { frozenCopy } from "./readonly-value.js";
 export function isPlainRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return false;
@@ -5,7 +6,7 @@ export function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-const WRITE_KEYS = {
+export const WRITE_KEYS = {
     create: ["data"],
     update: ["data"],
     upsert: ["create", "update"],
@@ -104,9 +105,12 @@ export async function pipeSentFields(stages, fields, records, args, select) {
             }
             let value = record[field];
             for (const pipe of stages[field]?.pipes ?? []) {
-                const next = await pipe(value);
+                const told = frozenCopy(value);
+                const next = await pipe(told);
                 if (next !== undefined) {
-                    value = next;
+                    if (next !== told) {
+                        value = next;
+                    }
                     changed = true;
                 }
             }
@@ -133,7 +137,7 @@ export async function guardSentFields(stages, fields, records, args, context) {
             }
             for (const guard of stages[field]?.guards ?? []) {
                 const told = context();
-                if ((await guard(record[field], told)) === false) {
+                if ((await guard(frozenCopy(record[field]), told)) === false) {
                     return false;
                 }
             }

package/dist/runtime/field-validator.runtime.d.ts

@@ -1,11 +1,29 @@
 import type { AvContract } from "../contracts/contract.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
+import { AvComputedValueError } from "./computed-value.error.js";
 import { type Path } from "./field-stage.runtime.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
 import type { ReferentialActionTable } from "./referential-action.js";
+/** The write phase of a record: a created row (an upsert's `create` branch too) or an updated one. */
+type WriteStage = "create" | "update";
+/**
+ * The fields a judgment leaves for later: a plan step's (or a forced call's)
+ * literal values are judged before BEGIN, except a field a write compute stage
+ * of that phase may still change, which is judged after write compute.
+ */
+type DeferredField = (resource: string, stage: WriteStage, field: string) => boolean;
 /**
  * Every way the sent fields `select` admits break their validators: the
  * operation's own records, then each nested write target's. Paths are the
  * request's: `argumentsPath` and then the value's place in the arguments.
  */
-export declare function fieldValidatorIssues(contract: AvContract, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path, select: (path: Path) => boolean): readonly AvValidationIssue[];
+export declare function fieldValidatorIssues(contract: AvContract, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path, select: (path: Path) => boolean, deferred?: DeferredField): readonly AvValidationIssue[];
+/**
+ * The server's defect when a value written to a field the active layer hides
+ * breaks its validators or its Json shape, or `undefined`.
+ */
+export declare function hiddenFieldRefusal(contracts: {
+    readonly core: AvContract;
+    readonly active: AvContract;
+}, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path): AvComputedValueError | undefined;
+export {};

package/dist/runtime/field-validator.runtime.js

@@ -1,4 +1,5 @@
-import { validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { hasFieldValidators, validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { AvComputedValueError } from "./computed-value.error.js";
 import { entryCheckIssues, fieldCheckIssues } from "./field-check.evaluator.js";
 import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
 import { nestedWriteTargetsOf } from "./nested-write.walker.js";
@@ -14,7 +15,10 @@ function rulesOf(contract, compiled, resource, name) {
     const field = fields !== undefined && Object.hasOwn(fields, name)
         ? fields[name]
         : undefined;
-    if (field?.kind === "scalar" && field.json !== undefined) {
+    if (field === undefined) {
+        return undefined;
+    }
+    if (field.kind === "scalar" && field.json !== undefined) {
         return { kind: "shape", field };
     }
     const checks = Object.hasOwn(compiled, name) ? compiled[name] : undefined;
@@ -36,17 +40,17 @@ function entryIssues(rules, entry, at) {
     const { compiled } = rules;
     return entryCheckIssues(compiled.checks, entry, compiled.subject ?? "string", at);
 }
-function recordIssues(contract, resource, records, args, argumentsPath, select) {
+function recordIssues(contract, resource, records, args, argumentsPath, select, deferred) {
     const compiled = validatedFieldsOf(contract, resource);
     const issues = [];
-    for (const path of records) {
+    for (const { path, stage } of records) {
         const record = valueAt(args, path);
         if (!isPlainRecord(record)) {
             continue;
         }
         for (const name of Object.keys(record)) {
             const rules = rulesOf(contract, compiled, resource, name);
-            if (rules === undefined) {
+            if (rules === undefined || deferred?.(resource, stage, name) === true) {
                 continue;
             }
             const fieldPath = [...path, name];
@@ -78,10 +82,45 @@ function recordIssues(contract, resource, records, args, argumentsPath, select)
     }
     return issues;
 }
-export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select) {
-    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args), args, argumentsPath, select);
+export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select, deferred) {
+    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args).map((path) => ({
+        path,
+        stage: request.family === "create" || path[0] === "create"
+            ? "create"
+            : "update",
+    })), args, argumentsPath, select, deferred);
     for (const target of nestedWriteTargetsOf(contract, references, request, args)) {
-        issues.push(...recordIssues(contract, target.resource, target.records.map((site) => site.path), args, argumentsPath, select));
+        issues.push(...recordIssues(contract, target.resource, target.records, args, argumentsPath, select, deferred));
     }
     return issues;
 }
+function holdsField(contract, resource, field) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    return fields !== undefined && Object.hasOwn(fields, field);
+}
+export function hiddenFieldRefusal(contracts, references, request, args, argumentsPath) {
+    const { core, active } = contracts;
+    if (core === active || !hasFieldValidators(core)) {
+        return undefined;
+    }
+    const judged = [];
+    const issues = fieldValidatorIssues(core, references, request, args, argumentsPath, () => true, (resource, stage, field) => {
+        if (holdsField(active, resource, field)) {
+            return true;
+        }
+        judged.push({ resource, stage, field });
+        return false;
+    });
+    const [first] = issues;
+    if (first === undefined) {
+        return undefined;
+    }
+    const path = first.path ?? [];
+    const at = judged.find(({ field }) => path.includes(field)) ?? judged[0];
+    if (at === undefined) {
+        return undefined;
+    }
+    return new AvComputedValueError(at.resource, at.field, at.stage, issues, `compute.${at.stage} on ${at.resource}.${at.field}, a field the ${request.origin} layer hides, returned a value its validators refuse (${first.code}: ${first.message})`);
+}

package/dist/runtime/framework-error.js

@@ -1,3 +1,4 @@
+import { brandCoreClass } from "./core-class.brand.js";
 export class AvError extends Error {
     name = "AvError";
     code;
@@ -30,3 +31,11 @@ export class AvProtocolError extends AvError {
 export class AvContractMismatchError extends AvError {
     name = "AvContractMismatchError";
 }
+brandCoreClass(AvError, "AvError");
+brandCoreClass(AvValidationError, "AvValidationError");
+brandCoreClass(AvNotFoundError, "AvNotFoundError");
+brandCoreClass(AvConflictError, "AvConflictError");
+brandCoreClass(AvAuthError, "AvAuthError");
+brandCoreClass(AvInternalError, "AvInternalError");
+brandCoreClass(AvProtocolError, "AvProtocolError");
+brandCoreClass(AvContractMismatchError, "AvContractMismatchError");

package/dist/runtime/framework-warning.emitter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Emits a framework warning: through `process.emitWarning` (type
+ * `AventaraWarning`, `code` as given) where the runtime has it, else through
+ * `console.warn`. A warning changes no behaviour.
+ */
+export declare function emitFrameworkWarning(message: string, code: string): void;

package/dist/runtime/framework-warning.emitter.js

@@ -0,0 +1,8 @@
+export function emitFrameworkWarning(message, code) {
+    const emitWarning = globalThis.process?.emitWarning;
+    if (typeof emitWarning === "function") {
+        emitWarning(message, { type: "AventaraWarning", code });
+        return;
+    }
+    globalThis.console?.warn(`AventaraWarning: ${message}`);
+}

package/dist/runtime/json-value.d.ts

@@ -1,15 +1,20 @@
 /**
  * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal}, any other class
- * instance and an `undefined` property are refused (`V1001`), as are a
- * non-finite `number` (`V1004`) and a cycle (`V1001`).
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal} and any other class
+ * instance are refused (`V1001`), as are a non-finite `number` (`V1004`) and a
+ * cycle (`V1001`). An `undefined` inside the value is what JSON makes of it: a key
+ * holding it is left out, an array element holding it (or a hole) is `null`. The
+ * type admits a key holding `undefined`, so an object with an optional property is
+ * a JSON value; an array element stays typed without it, as JSON has no such
+ * value.
  *
- * Results are fresh plain copies, so mutating one is safe.
+ * Results are fresh plain copies, so mutating one is safe; a result never holds a
+ * key whose value is `undefined`.
  *
  * A `json` field's value is this without its top-level `null`: a field-level
  * `null` is the field's absence, which only `nullable: true` admits.
  */
 export type AvJsonValue = string | number | boolean | null | readonly AvJsonValue[] | {
-    readonly [key: string]: AvJsonValue;
+    readonly [key: string]: AvJsonValue | undefined;
 };

package/dist/runtime/level-lifecycle.runtime.d.ts

@@ -1,5 +1,5 @@
 /** One level's lifecycle registrations, as an operation or a transaction level holds them. */
-export type LifecycleLevel<Context> = {
+type LifecycleLevel<Context> = {
     readonly hooks: {
         readonly before: readonly ((context: Context) => unknown)[];
         readonly after: readonly ((result: unknown, context: Context) => unknown)[];
@@ -17,9 +17,10 @@ export type NextReuse<Refusal extends Error = Error> = {
  * Runs `levels`' lifecycle around `inner`: every interceptor, outer to inner,
  * around every before hook, `inner`, and every after hook. `settle` turns what
  * `inner` or an interceptor below resolved into what the stage above sees (the
- * operation read-materializes it). An after hook is told a deep-frozen copy of
- * the result; the result itself goes on to the interceptors, which may answer a
+ * operation read-materializes it). Each after hook is told its own deep-frozen
+ * copy of the result; the result itself goes on to the interceptors, which may answer a
  * different one. Every `next()` is single use: a second call rejects with
  * `refuse()`'s error, recorded in `reuse`, and runs nothing.
  */
 export declare function runLevelLifecycle<Context, Refusal extends Error>(levels: readonly LifecycleLevel<Context>[], context: () => Context, inner: () => Promise<unknown>, settle: (result: unknown) => Promise<unknown>, reuse: NextReuse<Refusal>, refuse: () => Refusal): Promise<unknown>;
+export {};

package/dist/runtime/level-lifecycle.runtime.js

@@ -20,11 +20,9 @@ export async function runLevelLifecycle(levels, context, inner, settle, reuse, r
         }
         const result = await settle(await inner());
         const after = [...levels].reverse().flatMap((level) => level.hooks.after);
-        if (after.length > 0) {
-            const told = frozenCopy(result);
-            for (const hook of after) {
-                await hook(told, context());
-            }
+        const settled = after.length > 0 ? frozenCopy(result, true) : undefined;
+        for (const [index, hook] of after.entries()) {
+            await hook(index === after.length - 1 ? settled : frozenCopy(settled), context());
         }
         return result;
     };

package/dist/runtime/mutation-planner.d.ts

@@ -10,16 +10,11 @@ import type { OperationExecutionRequest } from "./operation-request.js";
  * `application.fields` / `client.fields`, which Core does not carry. Such a field is
  * virtual: its behaviours run and its value is stripped before the Adapter call.
  */
-export type WriteContracts = {
+type WriteContracts = {
     readonly core: AvContractCore;
     readonly active: AvContract;
 };
-type WriteStage = "create" | "update";
 type ContextFactory = (args: unknown) => AvComputeContext;
-export type RelationRecordSite = {
-    readonly key: string | undefined;
-    readonly stage: WriteStage;
-};
 /**
  * The sole grammar for relation-mutation record operands. Every write pass maps these
  * sites with its own record leaf, leaving identifier-only directives untouched.

package/dist/runtime/mutation-planner.js

@@ -1,7 +1,8 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { AvComputedValueError } from "./computed-value.error.js";
 import { replaceAt, valueAt } from "./field-stage.runtime.js";
-import { jsonShapeIssues, normalizeScalarFieldValue, } from "./scalar-runtime.js";
+import { frozenCopy } from "./readonly-value.js";
+import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function writeScalarField(contracts, resourceName, fieldName) {
     const field = lookupField(lookupResource(contracts.core, resourceName), fieldName) ??
         lookupField(lookupResource(contracts.active, resourceName), fieldName);
@@ -57,7 +58,7 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
             if (field === undefined) {
                 continue;
             }
-            const snapshot = Object.freeze({ ...logicalData });
+            const snapshot = frozenCopy(logicalData);
             const computed = await callback({
                 field: fieldName,
                 value: snapshot[fieldName],
@@ -79,18 +80,6 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
             if (!validation.ok) {
                 throw new AvComputedValueError(resourceName, fieldName, stage, validation.issues);
             }
-            const shapeIssues = jsonShapeIssues(field, validation.value, [
-                "resources",
-                resourceName,
-                "fields",
-                fieldName,
-                "pipelines",
-                "compute",
-                stage,
-            ]);
-            if (shapeIssues.length > 0) {
-                throw new AvComputedValueError(resourceName, fieldName, stage, shapeIssues);
-            }
             logicalData[fieldName] = validation.value;
         }
     }

package/dist/runtime/operation-code.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "./error-guidance.js";
+import type { AvOperationCode } from "./operation-response.js";
+/** Meaning, cause and fix of every outcome code. */
+export declare const OPERATION_CODE_GUIDANCE: {
+    readonly [C in AvOperationCode]: ErrorCodeDescription;
+};

package/dist/runtime/operation-code.guidance.js

@@ -0,0 +1,167 @@
+export const OPERATION_CODE_GUIDANCE = {
+    A1000: {
+        message: "Success.",
+        cause: "A read, a count or another operation without a more specific success code succeeded.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1001: {
+        message: "No match.",
+        cause: "A first-style operation (find.first, update.first, delete.first) matched no row; data is null and the generated client resolves null.",
+        fix: "Nothing: handle the null result. A unique operation answers A2003 instead.",
+    },
+    A1002: {
+        message: "Created.",
+        cause: "create.one created a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1003: {
+        message: "Created many.",
+        cause: "create.many or create.count created rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1004: {
+        message: "Updated.",
+        cause: "update.first or update.unique updated a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1005: {
+        message: "Updated many.",
+        cause: "update.many or update.count updated rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1006: {
+        message: "Deleted.",
+        cause: "delete.first or delete.unique deleted a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1007: {
+        message: "Deleted many.",
+        cause: "delete.count deleted rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1008: {
+        message: "Upserted.",
+        cause: "upsert.unique created or updated a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1009: {
+        message: "Transaction committed.",
+        cause: "A whole transaction plan committed; data holds one result per step.",
+        fix: "Nothing: the plan committed.",
+    },
+    A2000: {
+        message: "Invalid request.",
+        cause: "The HTTP request cannot be interpreted: malformed JSON, a body that is not a JSON object, an unknown `/_*` path, a body that does not decode in its Content-Encoding, or a missing Aventara-Protocol-Version or Aventara-Contract-Hash header (the message names it).",
+        fix: "Send a JSON object with both identity headers. The generated client does this for you.",
+    },
+    A2001: {
+        message: "Unknown Resource.",
+        cause: 'The Resource is not in the caller\'s contract: misspelt, hidden by exposure, or added to the schema after aventara:prepare last ran. cause.message is "The requested Resource is not available." and the issue is V1005 at `["resource"]`.',
+        fix: "Use the model's exact name. After a schema change run the adapter's generate step (`npm run aventara:prepare` in a scaffolded project), restart, and regenerate the client. A Resource hidden on purpose is reached from server code (framework.application).",
+    },
+    A2002: {
+        message: "Unknown operation.",
+        cause: 'The operation is not available on that Resource: a typo, removed by exposure, an operation the adapter does not offer (such as delete.many), or a ctx.$sql, appTx.$sql or ctx.$transaction the adapter or the layer cannot run. The issue is V1006 at `["family"]` or `["variant"]`.',
+        fix: "Call an operation the contract lists (`GET <api>/_contract`), regenerate a stale client, and check the layer's exemptions and transactionsStyle.",
+    },
+    A2003: {
+        message: "Not found.",
+        cause: "A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs. Under a policy, a row outside the caller's read scope is a miss too, and so is a single-row update or delete of a row the caller cannot read, so the answer does not reveal that the row exists. A row the caller can read but not change answers A4002.",
+        fix: "Catch AvNotFoundError, or use a first-style operation, which answers A1001 with null. Check the $connect identifier.",
+    },
+    A2004: {
+        message: "Validation failed.",
+        cause: 'The arguments break a contract rule or a field validator. cause.issues lists each problem by V-code and path; a validator\'s issue also has check and params. The validators judge the values after the pipes and write compute, so a computed value they refuse is here too, at its field. A required create field left out is here (V1000). So is a value the database itself refused: too long for its column or its index, or out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]`, or at the value where the adapter can place it (a bigint its driver cannot bind), and its message saying what the database refused. So is a record written through a relation that writes that relation, or a field holding its reference, back (V1012, at that field), where the adapter admits no such write.',
+        fix: "Fix the argument each issue's path points at, as its V-code says. A field the server must fill takes a compute.create stage. For a value the database refused, send one its column holds. For a nested write that writes its relation back, leave that field out: the parent supplies it.",
+    },
+    A2005: {
+        message: "Contract mismatch.",
+        cause: "The caller's Aventara-Contract-Hash is not the server's current one: the schema, the configuration, the limits or the exposure changed, or the client targets another deployment.",
+        fix: "Regenerate the client against the running server: `npm run avclient:generate`.",
+    },
+    A2006: {
+        message: "Protocol mismatch.",
+        cause: "Aventara-Protocol-Version is not 1.",
+        fix: "Send `Aventara-Protocol-Version: 1`, or upgrade the client.",
+    },
+    A2007: {
+        message: "Invalid transaction reference.",
+        cause: "A transaction $ref or fingerprint is invalid: the issues are V1010, V1011, V1016, V1017 or V1018, and cause.operation is the step. A $ref with no fingerprint is A2004 / V1000.",
+        fix: "Let the generated client or framework.appTx build plans; check the $ref path and that the referenced step comes earlier.",
+    },
+    A2008: {
+        message: "Conflict.",
+        cause: "A uniqueness or reference constraint failed: a duplicate value, a missing parent, or a $disconnect or $set that would orphan a required child (also through update.first or a developer SQL statement). Sending it again unchanged fails the same way.",
+        fix: "Change the data. For a duplicate, update the existing row or use upsert.unique.",
+    },
+    A2009: {
+        message: "Limit exceeded.",
+        cause: "A contract limit was crossed: nesting depth (V1013), list or plan size (V1014), boolean nodes (V1015) or Json value depth (V1021).",
+        fix: "Ask for less (paginate, split the plan), or raise the limit under `limits`.",
+    },
+    A2010: {
+        message: "Payload too large.",
+        cause: "The decoded request body exceeds maxRequestBytes (default 1048576).",
+        fix: "Send less, or raise limits.maxRequestBytes.",
+    },
+    A2011: {
+        message: "Unsupported media type.",
+        cause: "The body is not application/json, or its Content-Encoding is not gzip, deflate or br.",
+        fix: "Send `Content-Type: application/json`.",
+    },
+    A2012: {
+        message: "Method not allowed.",
+        cause: "The HTTP method does not fit the route; the Allow header names the right one (`POST` on operations and `/_transactions`, `GET` on `/_contract`).",
+        fix: "Use the method the Allow header names.",
+    },
+    A2013: {
+        message: "Concurrent modification.",
+        cause: "A competing writer reached the state first; nothing was written.",
+        fix: "Retry. No retry is automatic.",
+    },
+    A2014: {
+        message: "Stale selection.",
+        cause: "The selected state changed before the write; nothing was written.",
+        fix: "Read again, then retry.",
+    },
+    A3000: {
+        message: "Internal error.",
+        cause: 'An unexpected failure on the server: a stage threw an error that is not an AvError, an interceptor called next() twice, a compute stage reached a write through its read-only ctx, a compute stage returned a value of the wrong type, or a compute.create returned undefined for a required field. cause.message is always "Internal framework error."',
+        fix: "Read the real error in the diagnostics sink (the root `diagnostics` key) or the server log line for the request id, and fix that stage. To answer with a code of your choice, throw an AvError.",
+    },
+    A3001: {
+        message: "Adapter error.",
+        cause: 'A database or ORM failure that is not something the caller can fix. cause.message is always "Adapter execution failed."',
+        fix: "Read the raw error in the diagnostics sink; check the database, its connection and the migration state.",
+    },
+    A3002: {
+        message: "Transaction error.",
+        cause: "Transaction infrastructure failed (commit or rollback, or the transaction expired or was closed under a step), or a Resource transaction interceptor called next() twice or resolved without calling it.",
+        fix: "Read the diagnostics sink. Call next() exactly once in a transaction interceptor; retry an infrastructure failure.",
+    },
+    A3003: {
+        message: "Serialization error.",
+        cause: "A result could not be encoded for transport.",
+        fix: "Read the diagnostics sink; make compute.read stages and Json values return plain data of the field's type.",
+    },
+    A3004: {
+        message: "Pipe output invalid.",
+        cause: 'A server pipe, field pipe or transaction pipe (or write compute) returned arguments the server\'s own contract refuses: a field the Resource does not have, a wrong type, a dropped required field, a reference written together with its relation (V1012), or a changed plan. cause.message is always "A server pipeline produced invalid arguments."',
+        fix: "Read the server log line, which names the pipe, the operation and the path, and fix the pipe. A pipe returns a new object of the same shape, or undefined to keep the arguments.",
+    },
+    A4000: {
+        message: "Unauthenticated.",
+        cause: 'A guard threw new AvError("A4000", ...): authentication is required or failed. The framework never authenticates by itself.',
+        fix: "Send the credentials your guards expect, such as the Authorization header.",
+    },
+    A4001: {
+        message: "Forbidden.",
+        cause: 'A guard returned false ("Operation denied by a framework guard."), a field write guard or a nested write\'s target guard included, or a stage threw A4001.',
+        fix: "Call as a caller the guard admits, or stop sending the guarded field. To answer another code, throw an AvError from the guard.",
+    },
+    A4002: {
+        message: "Policy denied.",
+        cause: "The configuration's policy refused the request: its engine does not allow the operation, a field the request names, writes or returns, a row it reaches, a row it creates, or the row a change leaves (moved out of what the caller reads, or failing its grant's after condition, which rolls the write back); on a database without interactive transactions, a write the policy can only check after it runs; or a stage threw new AvError(\"A4002\", ...).",
+        fix: "Read cause.message, which names what the policy refused. Call as a principal the policy allows, leave the refused field or relation out (a governed one is named only where every row grants it), or change only rows the caller may change and still read afterwards.",
+    },
+};

package/dist/runtime/operation-request.d.ts

@@ -1,11 +1,12 @@
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { PolicySession } from "../policy/policy-session.js";
 import type { AvTransportContext } from "./pipeline.js";
 import type { AvState } from "./request-state.js";
 /**
  * The protocol version and Contract hash a remote caller says it was built for:
  * the Client Contract's for a client, the Agent Contract's for an agent.
  */
-export type ClientProtocolIdentity = {
+export type AvRequestProtocol = {
     readonly version: number;
     readonly hash: string;
 };
@@ -20,7 +21,7 @@ type RuntimeOperationBase = AvOperationIdentity & {
     readonly state?: AvState;
 };
 /** An in-process request, run under the Application Contract. */
-export type ApplicationOperationRequest = RuntimeOperationBase & {
+export type AvApplicationOperationRequest = RuntimeOperationBase & {
     readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
@@ -29,24 +30,24 @@ export type ApplicationOperationRequest = RuntimeOperationBase & {
  * A remote request, run under the Client Contract; `protocol` is the identity
  * the client sent.
  */
-export type ClientOperationRequest = RuntimeOperationBase & {
+export type AvClientOperationRequest = RuntimeOperationBase & {
     readonly origin: "client";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /**
  * An AI agent's request, run under the Agent Contract; `protocol` is the
  * identity of the Agent Contract the caller (an MCP server) was built from.
  */
-export type AgentOperationRequest = RuntimeOperationBase & {
+export type AvAgentOperationRequest = RuntimeOperationBase & {
     readonly origin: "agent";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** A request from outside the server: a client's or an agent's. */
-export type RemoteOperationRequest = ClientOperationRequest | AgentOperationRequest;
+export type RemoteOperationRequest = AvClientOperationRequest | AvAgentOperationRequest;
 /** One operation request, as `framework.execute` takes it. */
-export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest | AgentOperationRequest;
+export type AvOperationRequest = AvApplicationOperationRequest | AvClientOperationRequest | AvAgentOperationRequest;
 type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "arguments"> : never;
 /**
  * A request as every stage after the Framework Validation Layer sees it:
@@ -56,12 +57,18 @@ type WithoutArguments<Request> = Request extends unknown ? Omit<Request, "argume
  * unreachable by type. Distributive, so the origin and family/variant
  * correlations survive the omission.
  */
-export type OperationExecutionRequest = WithoutArguments<FrameworkOperationRequest>;
+export type OperationExecutionRequest = WithoutArguments<AvOperationRequest>;
 /**
  * A request whose stages run: its `state` settled once, the seed or the `{}`
  * the runtime made for it, so every stage is told the same object.
  */
 export type StatefulOperationRequest = OperationExecutionRequest & {
     readonly state: AvState;
+    /**
+     * The request's policy session, when the policy checks it: a client's or an
+     * agent's request, or an application call made `as` a principal. Absent, nothing
+     * is checked: an application call, or a call a stage made through `ctx`.
+     */
+    readonly policy?: PolicySession;
 };
 export {};