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

package/dist/runtime/misuse-reporter.d.ts

@@ -1,32 +1,32 @@
-import type { RequestOrigin } from "../config/config-layer.js";
-import type { OperationFamily } from "../operations/operation-identity.js";
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
 /**
  * One caller value the framework refused because it could not be read
  * (`"unreadable-value"`: a revoked Proxy, a throwing getter or trap) or is not plain
- * data (`"non-plain-value"`: a class instance other than `Date`, `Decimal` or
+ * data (`"non-plain-value"`: a class instance other than `Date`, `AvDecimal` or
  * `Uint8Array`). The caller received `A2004` with one `V1001` at `path`.
  *
- * The operation's identity is present when the framework could read it — absent for
- * a request whose own envelope could not be read — and `operation` is the step's
+ * The operation's identity is present when the framework could read it (absent for
+ * a request whose own envelope could not be read), and `operation` is the step's
  * index in a transaction plan.
  */
-export type FrameworkMisuseEvent = {
+export type AvMisuseEvent = {
     readonly kind: "unreadable-value" | "non-plain-value";
     /** The issue path the caller received. */
     readonly path: readonly (string | number)[];
-    readonly origin?: RequestOrigin;
+    readonly origin?: AvRequestOrigin;
     readonly resource?: string;
-    readonly family?: OperationFamily;
+    readonly family?: AvOperationFamily;
     readonly variant?: string;
     readonly operation?: number;
 };
 /**
- * Receives a {@link FrameworkMisuseEvent} for every caller value the framework
+ * Receives a {@link AvMisuseEvent} for every caller value the framework
  * refused as unreadable or not plain data. Set once, as the root configuration's
  * `misuse`. What it returns, throws or rejects with never reaches the response.
  */
-export type FrameworkMisuseSink = (event: FrameworkMisuseEvent) => void | Promise<void>;
+export type AvMisuseSink = (event: AvMisuseEvent) => void | Promise<void>;
 /** The channel as the runtime holds it: total, never awaited. */
-export type MisuseReporter = (event: FrameworkMisuseEvent) => void;
+export type MisuseReporter = (event: AvMisuseEvent) => void;
 /** Binds the configured sink; without one, nothing is observed. */
-export declare function createMisuseReporter(sink: FrameworkMisuseSink | undefined): MisuseReporter;
+export declare function createMisuseReporter(sink: AvMisuseSink | undefined): MisuseReporter;

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

@@ -1,24 +1,20 @@
-import type { FrameworkBehaviorsConfig } from "../config/framework-behaviors-config.js";
-import type { RelationMutationDirective } from "../contracts/capability.js";
-import type { Contract, CoreContract } from "../contracts/contract.js";
+import type { ResolvedComputeConfig } from "../config/field-compute.resolver.js";
+import type { AvRelationMutationDirective } from "../contracts/capability.js";
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvComputeContext } from "./field-compute.js";
+import type { NestedWriteTarget } from "./nested-write.walker.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
-import type { PipelineContext } from "./pipeline.js";
 /**
  * The two Contracts a write reads. The Core Contract decides what the Adapter is asked
  * to store; the active Contract adds the fields its scope declared under
  * `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 = {
-    readonly core: CoreContract;
-    readonly active: Contract;
-};
-type WriteStage = "create" | "update";
-type ContextFactory = (args: unknown) => PipelineContext;
-export type RelationRecordSite = {
-    readonly key: string | undefined;
-    readonly stage: WriteStage;
+type WriteContracts = {
+    readonly core: AvContractCore;
+    readonly active: AvContract;
 };
+type ContextFactory = (args: unknown) => AvComputeContext;
 /**
  * The sole grammar for relation-mutation record operands. Every write pass maps these
  * sites with its own record leaf, leaving identifier-only directives untouched.
@@ -53,9 +49,17 @@ export declare const RELATION_MUTATION_RECORD_SITES: {
  * membership, not an assertion: `Object.prototype` members resolve through the
  * prototype chain and would otherwise reach a site loop with a non-iterable.
  */
-export declare function isRelationMutationDirective(key: string): key is RelationMutationDirective;
-/** Apply effective computed create/update field behavior to post-pipe logical args. */
-export declare function applyWriteFieldBehaviors(contracts: WriteContracts, behaviors: FrameworkBehaviorsConfig | undefined, request: OperationExecutionRequest, args: unknown, contextFactory: ContextFactory): Promise<unknown>;
+export declare function isRelationMutationDirective(key: string): key is AvRelationMutationDirective;
+/** Apply the effective create/update compute stages to the post-pipe logical args. */
+export declare function applyWriteCompute(contracts: WriteContracts, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, args: unknown, contextFactory: ContextFactory): Promise<unknown>;
+/**
+ * Applies each nested target's write compute, in the targets' order, to its
+ * records: `compute.create` on a created row (an `$upsert`'s `create` branch
+ * too), `compute.update` on an updated one. Each target's stages are told
+ * `context(target, payload)`, the nested target's own context. The arguments
+ * are copied where a record changes, never written.
+ */
+export declare function applyNestedWriteCompute(contracts: WriteContracts, compute: ResolvedComputeConfig | undefined, args: unknown, targets: readonly NestedWriteTarget[], context: (target: NestedWriteTarget, payload: unknown) => AvComputeContext): Promise<unknown>;
 /** Strip VIRTUAL scalar input only at the persistence boundary. */
 export declare function stripVirtualMutationInput(contracts: WriteContracts, request: OperationExecutionRequest, args: unknown): Promise<unknown>;
 export {};

package/dist/runtime/mutation-planner.js

@@ -1,6 +1,8 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { ComputedValueError } from "./computed-value.error.js";
-import { jsonShapeIssues, normalizeScalarFieldValue, } from "./scalar-runtime.js";
+import { AvComputedValueError } from "./computed-value.error.js";
+import { replaceAt, valueAt } from "./field-stage.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);
@@ -33,7 +35,7 @@ function cloneRecord(value) {
 function relationEntries(value) {
     return Array.isArray(value) ? value : [value];
 }
-async function computeRecord(contracts, behaviors, request, resourceName, stage, data, contextFactory) {
+async function computeRecord(contracts, compute, resourceName, stage, data, contextFactory) {
     if (!isRecord(data)) {
         return data;
     }
@@ -42,13 +44,13 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
         return data;
     }
     const logicalData = cloneRecord(data);
-    const resourceBehaviors = behaviors[resourceName]?.fields;
-    if (resourceBehaviors !== undefined) {
-        for (const [fieldName, fieldBehavior] of Object.entries(resourceBehaviors)) {
-            if (fieldBehavior === undefined) {
+    const resourceCompute = compute[resourceName];
+    if (resourceCompute !== undefined) {
+        for (const [fieldName, fieldCompute] of Object.entries(resourceCompute)) {
+            if (fieldCompute === undefined) {
                 continue;
             }
-            const callback = fieldBehavior[stage];
+            const callback = fieldCompute[stage];
             if (typeof callback !== "function") {
                 continue;
             }
@@ -56,40 +58,31 @@ async function computeRecord(contracts, behaviors, request, resourceName, stage,
             if (field === undefined) {
                 continue;
             }
+            const snapshot = frozenCopy(logicalData);
             const computed = await callback({
-                origin: request.origin,
-                resource: resourceName,
                 field: fieldName,
-                value: logicalData[fieldName],
-                data: logicalData,
-                operation: contextFactory(logicalData),
+                value: snapshot[fieldName],
+                data: snapshot,
+                ctx: contextFactory(snapshot),
             });
             if (computed === undefined) {
                 continue;
             }
-            const validation = normalizeScalarFieldValue(contracts.core, field, computed, "runtime", ["behaviors", resourceName, fieldName, stage]);
-            if (!validation.ok) {
-                throw new ComputedValueError(resourceName, fieldName, stage, validation.issues);
-            }
-            const shapeIssues = jsonShapeIssues(field, validation.value, [
-                "behaviors",
+            const validation = normalizeScalarFieldValue(contracts.core, field, computed, "runtime", [
+                "resources",
                 resourceName,
+                "fields",
                 fieldName,
+                "pipelines",
+                "compute",
                 stage,
             ]);
-            if (shapeIssues.length > 0) {
-                throw new ComputedValueError(resourceName, fieldName, stage, shapeIssues);
+            if (!validation.ok) {
+                throw new AvComputedValueError(resourceName, fieldName, stage, validation.issues);
             }
             logicalData[fieldName] = validation.value;
         }
     }
-    for (const [fieldName, value] of Object.entries(logicalData)) {
-        const field = lookupField(resource, fieldName);
-        if (field?.kind !== "relation") {
-            continue;
-        }
-        logicalData[fieldName] = await mapRelationMutationRecords(field, value, (targetResource, nestedStage, record) => computeRecord(contracts, behaviors, request, targetResource, nestedStage, record, contextFactory));
-    }
     return logicalData;
 }
 async function mapRelationMutationRecords(relation, value, leaf) {
@@ -125,29 +118,49 @@ async function mapRelationMutationRecords(relation, value, leaf) {
     }
     return normalized;
 }
-export async function applyWriteFieldBehaviors(contracts, behaviors, request, args, contextFactory) {
-    if (behaviors === undefined || !isRecord(args)) {
+export async function applyWriteCompute(contracts, compute, request, args, contextFactory) {
+    if (compute === undefined || !isRecord(args)) {
         return args;
     }
     const logicalArgs = cloneRecord(args);
     if (request.family === "create" && "data" in logicalArgs) {
         logicalArgs.data = Array.isArray(logicalArgs.data)
-            ? await Promise.all(logicalArgs.data.map((entry) => computeRecord(contracts, behaviors, request, request.resource, "create", entry, contextFactory)))
-            : await computeRecord(contracts, behaviors, request, request.resource, "create", logicalArgs.data, contextFactory);
+            ? await Promise.all(logicalArgs.data.map((entry) => computeRecord(contracts, compute, request.resource, "create", entry, contextFactory)))
+            : await computeRecord(contracts, compute, request.resource, "create", logicalArgs.data, contextFactory);
     }
     if (request.family === "update" && "data" in logicalArgs) {
-        logicalArgs.data = await computeRecord(contracts, behaviors, request, request.resource, "update", logicalArgs.data, contextFactory);
+        logicalArgs.data = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.data, contextFactory);
     }
     if (request.family === "upsert") {
         if ("create" in logicalArgs) {
-            logicalArgs.create = await computeRecord(contracts, behaviors, request, request.resource, "create", logicalArgs.create, contextFactory);
+            logicalArgs.create = await computeRecord(contracts, compute, request.resource, "create", logicalArgs.create, contextFactory);
         }
         if ("update" in logicalArgs) {
-            logicalArgs.update = await computeRecord(contracts, behaviors, request, request.resource, "update", logicalArgs.update, contextFactory);
+            logicalArgs.update = await computeRecord(contracts, compute, request.resource, "update", logicalArgs.update, contextFactory);
         }
     }
     return logicalArgs;
 }
+export async function applyNestedWriteCompute(contracts, compute, args, targets, context) {
+    if (compute === undefined) {
+        return args;
+    }
+    let current = args;
+    for (const target of targets) {
+        if (!Object.hasOwn(compute, target.resource)) {
+            continue;
+        }
+        for (const site of target.records) {
+            const record = valueAt(current, site.path);
+            if (!isRecord(record)) {
+                continue;
+            }
+            const computed = await computeRecord(contracts, compute, target.resource, site.stage, record, () => context(target, valueAt(current, target.path)));
+            current = replaceAt(current, site.path, computed);
+        }
+    }
+    return current;
+}
 async function stripVirtualRecord(contracts, resourceName, data) {
     if (!isRecord(data)) {
         return data;

package/dist/runtime/nested-write.walker.d.ts

@@ -0,0 +1,32 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import { type Path } from "./field-stage.runtime.js";
+import type { ReferentialActionTable } from "./referential-action.js";
+/** The family a nested target's stages are told, and its guards are drawn from. */
+export type NestedTargetFamily = "create" | "update" | "delete";
+/** One record of a nested target's data, and the write phase it is. */
+export type NestedRecordSite = {
+    /** Where the record sits in the operation's arguments. */
+    readonly path: Path;
+    /** `create` for a created row (an `$upsert`'s `create` branch too), `update` otherwise. */
+    readonly stage: "create" | "update";
+};
+/** One nested write's target, in data order. */
+export type NestedWriteTarget = {
+    /** The target Resource. */
+    readonly resource: string;
+    readonly family: NestedTargetFamily;
+    /** Where the directive's entry — the nested payload — sits in the arguments. */
+    readonly path: Path;
+    /** The entry's data records the target's field stages run on. */
+    readonly records: readonly NestedRecordSite[];
+};
+/**
+ * Every nested write target in an operation's arguments, depth first in data
+ * order: a target comes before the targets inside its own data, and before the
+ * next directive's. Empty for an operation with no write data. Total over
+ * malformed input.
+ */
+export declare function nestedWriteTargetsOf(contract: AvContract, references: ReferentialActionTable, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown): readonly NestedWriteTarget[];

package/dist/runtime/nested-write.walker.js

@@ -0,0 +1,73 @@
+import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
+import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
+import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
+const DIRECTIVE_FAMILY = {
+    $create: "create",
+    $connectOrCreate: "create",
+    $update: "update",
+    $upsert: "update",
+    $delete: "delete",
+    $connect: "relation",
+    $disconnect: "relation",
+    $set: "relation",
+};
+function holdsReference(references, resource, relation) {
+    const edges = Object.hasOwn(references, resource)
+        ? references[resource]
+        : undefined;
+    return (Array.isArray(edges) &&
+        edges.some((edge) => edge.field === relation));
+}
+function walkRecord(context, resource, path, record) {
+    if (!isPlainRecord(record)) {
+        return;
+    }
+    const owner = lookupResource(context.contract, resource);
+    for (const [key, value] of Object.entries(record)) {
+        const field = lookupField(owner, key);
+        if (field?.kind !== "relation" || !isPlainRecord(value)) {
+            continue;
+        }
+        for (const [directive, operand] of Object.entries(value)) {
+            if (!isRelationMutationDirective(directive)) {
+                continue;
+            }
+            const mapped = DIRECTIVE_FAMILY[directive];
+            if (mapped === "relation" &&
+                field.cardinality === "one" &&
+                holdsReference(context.references, resource, key)) {
+                continue;
+            }
+            const family = mapped === "relation" ? "update" : mapped;
+            const entries = directive !== "$set" && Array.isArray(operand)
+                ? operand.map((_entry, index) => [index])
+                : [[]];
+            for (const at of entries) {
+                const entryPath = [...path, key, directive, ...at];
+                const records = [];
+                for (const site of RELATION_MUTATION_RECORD_SITES[directive]) {
+                    const sitePath = site.key === undefined ? entryPath : [...entryPath, site.key];
+                    if (isPlainRecord(valueAt(record, sitePath.slice(path.length)))) {
+                        records.push({ path: sitePath, stage: site.stage });
+                    }
+                }
+                context.targets.push({
+                    resource: field.target,
+                    family,
+                    path: entryPath,
+                    records,
+                });
+                for (const site of records) {
+                    walkRecord(context, field.target, site.path, valueAt(record, site.path.slice(path.length)));
+                }
+            }
+        }
+    }
+}
+export function nestedWriteTargetsOf(contract, references, request, args) {
+    const context = { contract, references, targets: [] };
+    for (const path of writeRecordPathsOf(request.family, args)) {
+        walkRecord(context, request.resource, path, valueAt(args, path));
+    }
+    return context.targets;
+}

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,17 +1,27 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { PipelineTransportContext } from "./pipeline.js";
-/** The protocol version and ClientContract hash a client says it was built for. */
-export type ClientProtocolIdentity = {
+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 AvRequestProtocol = {
     readonly version: number;
     readonly hash: string;
 };
-type RuntimeOperationBase = OperationIdentity & {
+type RuntimeOperationBase = AvOperationIdentity & {
     readonly resource: string;
     readonly arguments: unknown;
     readonly requestId: string;
+    /**
+     * The request's `ctx.$state`: every stage of it, and every ctx call they make,
+     * shares this one object. Omitted, it is a fresh `{}`.
+     */
+    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;
@@ -20,13 +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 transport?: PipelineTransportContext;
+    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 AvAgentOperationRequest = RuntimeOperationBase & {
+    readonly origin: "agent";
+    readonly protocol: AvRequestProtocol;
+    readonly transport?: AvTransportContext;
 };
+/** A request from outside the server: a client's or an agent's. */
+export type RemoteOperationRequest = AvClientOperationRequest | AvAgentOperationRequest;
 /** One operation request, as `framework.execute` takes it. */
-export type FrameworkOperationRequest = ApplicationOperationRequest | ClientOperationRequest;
+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:
@@ -36,5 +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 {};