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

package/dist/transactions/transaction-plan-validator.js

@@ -1,18 +1,20 @@
-import { CanonicalJsonError } from "../contracts/contract-canonicalizer.js";
+import { AvCanonicalJsonError } from "../contracts/contract-canonicalizer.js";
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { parseOperationIdentity } from "../operations/operation-identity.js";
-import { findOperationAvailabilityIssue, unavailableOperationKey, } from "../operations/operation-validator.js";
+import { findOperationAvailabilityIssue, operationUnavailableIssue, unavailableOperationKey, } from "../operations/operation-validator.js";
+import { resourceUnavailableIssue } from "../operations/operation-validator-core.js";
 import { VALIDATION_CODE_MESSAGES, validationIssue, } from "../operations/validation-code.js";
-import { CallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
+import { AvCallerDataError, locateCallerDataError, } from "../runtime/caller-data.copier.js";
 import { copyAtDoor, misuseIdentityOf, refuseCallerData, } from "../runtime/caller-data.door.js";
 import { planReadOperation, } from "../runtime/computed-read-runtime.js";
 import { planOperationArgumentsPath, planStepPath, } from "../runtime/error-boundary.js";
 import { createMisuseReporter } from "../runtime/misuse-reporter.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { activeContract, validateOperationRequest, validateProtocolIdentity, } from "../runtime/operation-runtime.js";
-import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { mapValidationOutcome, VALIDATION_OUTCOME_MESSAGES, } from "../runtime/outcome-mapper.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
 import { computeOperationFingerprint, isOperationFingerprint, } from "./operation-fingerprint.js";
+import { validateSqlStatement } from "./sql-statement.validator.js";
 import { inspectTransactionEnvelope, inspectTransactionOperationEntry, inspectTransactionOperations, } from "./transaction-envelope.js";
 import { routeTransactionReferenceCandidate, } from "./transaction-reference.js";
 import { collectTransactionReferenceCandidates, } from "./transaction-reference-collector.js";
@@ -24,7 +26,13 @@ const STEP_ARGUMENTS_POLICY = {
 };
 function captureSteps(operations, operationCount, planArguments) {
     const steps = [];
+    const statements = planArguments.source === "owned" ? planArguments.statements : undefined;
     for (let index = 0; index < operationCount; index += 1) {
+        const statement = statements?.get(index);
+        if (statement !== undefined) {
+            steps.push({ ok: true, kind: "sql", statement });
+            continue;
+        }
         const operationEntry = inspectTransactionOperationEntry(operations, index);
         if (!operationEntry.ok) {
             steps.push({
@@ -55,7 +63,7 @@ function captureSteps(operations, operationCount, planArguments) {
             : planArguments.source === "owned"
                 ? { ok: true, value: args }
                 : copyAtDoor(args, STEP_ARGUMENTS_POLICY);
-        steps.push({ ok: true, node, args: copy });
+        steps.push({ ok: true, kind: "operation", node, args: copy });
         if (!copy.ok) {
             break;
         }
@@ -73,11 +81,16 @@ const OPERATION_KEYS = [
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function operationKeyFailure(key, message, operation) {
-    return transactionOperationFailure(operationFailure("A2002", {
-        message: "Operation arguments failed framework validation.",
-        issues: [validationIssue("V1006", [key], message)],
-    }), operation);
+function operationKeyFailure(contract, step, operation) {
+    const { resource, family, variant } = step;
+    const issue = typeof family === "string" && typeof variant === "string"
+        ? operationUnavailableIssue(contract, { resource, family, variant })
+        : validationIssue("V1006", [
+            typeof family === "string"
+                ? unavailableOperationKey(contract, { resource, family })
+                : "family",
+        ], `Operation is not available on Resource "${resource}".`);
+    return transactionOperationFailure(mapValidationOutcome([issue]), operation);
 }
 function structuralFailure(rejection, operation) {
     return operationFailure("A2004", {
@@ -93,9 +106,10 @@ function structuralFailure(rejection, operation) {
         ...(operation === undefined ? {} : { operation }),
     });
 }
-function syntheticRequest(origin, requestId, resource, identity, args) {
+function syntheticRequest(origin, request, resource, identity, args) {
     const common = {
-        requestId,
+        requestId: request.requestId,
+        ...(request.state === undefined ? {} : { state: request.state }),
         resource,
         ...identity,
         arguments: args,
@@ -104,7 +118,7 @@ function syntheticRequest(origin, requestId, resource, identity, args) {
         ? { ...common, origin: "application" }
         : {
             ...common,
-            origin: "client",
+            origin: origin.origin,
             protocol: origin.protocol,
             ...(origin.transport === undefined
                 ? {}
@@ -115,7 +129,7 @@ function requestOrigin(request) {
     return request.origin === "application"
         ? { origin: "application" }
         : {
-            origin: "client",
+            origin: request.origin,
             protocol: request.protocol,
             ...(request.transport === undefined
                 ? {}
@@ -124,7 +138,21 @@ function requestOrigin(request) {
 }
 function originContracts(contracts, origins) {
     const layers = new Set(origins.map(({ origin }) => origin));
-    return [...layers].map((origin) => origin === "application" ? contracts.application : contracts.client);
+    return [...layers].map((origin) => contracts[origin]);
+}
+function mixedOriginFailure(origins) {
+    const [first] = origins ?? [];
+    const other = first === undefined
+        ? -1
+        : (origins ?? []).findIndex(({ origin }) => origin !== first.origin);
+    return other === -1
+        ? undefined
+        : transactionOperationFailure(operationFailure("A2004", {
+            message: "Transaction plan failed framework validation.",
+            issues: [
+                validationIssue("V1020", [], VALIDATION_CODE_MESSAGES.V1020),
+            ],
+        }), other);
 }
 function* relationTraversals(contract, resourceName, value, path) {
     const resource = lookupResource(contract, resourceName);
@@ -208,6 +236,10 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
     if (protocolFailure !== undefined) {
         return { ok: false, response: protocolFailure };
     }
+    const mixed = mixedOriginFailure(origins);
+    if (mixed !== undefined) {
+        return { ok: false, response: mixed };
+    }
     const ownOrigin = requestOrigin(request);
     const originOf = (index) => origins?.[index] ?? ownOrigin;
     const planContracts = origins === undefined || origins.length === 0
@@ -259,17 +291,28 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
         if (!step.ok) {
             return { ok: false, response: step.response };
         }
+        if (step.kind === "sql") {
+            const statement = validateSqlStatement(step.statement, {
+                index,
+                earlier: validated,
+                available: dependencies.sqlStatements,
+                misuse,
+            });
+            if (!statement.ok) {
+                return statement;
+            }
+            validated.push(statement.statement);
+            continue;
+        }
         const node = step.node;
         const origin = originOf(index);
-        const contract = origin.origin === "application"
-            ? dependencies.contracts.application
-            : dependencies.contracts.client;
+        const contract = dependencies.contracts[origin.origin];
         const resourceValue = node.get("resource");
         if (typeof resourceValue !== "string") {
             return {
                 ok: false,
                 response: transactionOperationFailure(operationFailure("A2001", {
-                    message: "Operation Resource is invalid.",
+                    message: VALIDATION_OUTCOME_MESSAGES.A2001,
                     issues: [
                         validationIssue("V1001", ["resource"], "resource must be a string."),
                     ],
@@ -279,12 +322,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
         if (lookupResource(contract, resourceValue) === undefined) {
             return {
                 ok: false,
-                response: transactionOperationFailure(operationFailure("A2001", {
-                    message: "Operation arguments failed framework validation.",
-                    issues: [
-                        validationIssue("V1005", ["resource"], `Resource "${resourceValue}" is not available in the active Contract.`),
-                    ],
-                }), index),
+                response: transactionOperationFailure(mapValidationOutcome([resourceUnavailableIssue(resourceValue)]), index),
             };
         }
         const family = node.get("family");
@@ -295,12 +333,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
         if (identity === undefined) {
             return {
                 ok: false,
-                response: operationKeyFailure(typeof family === "string"
-                    ? unavailableOperationKey(contract, {
-                        resource: resourceValue,
-                        family,
-                    })
-                    : "family", "Operation is not part of the standard operation grammar.", index),
+                response: operationKeyFailure(contract, { resource: resourceValue, family, variant }, index),
             };
         }
         const stepRequest = { resource: resourceValue, ...identity };
@@ -326,7 +359,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
             };
         }
         try {
-            const operationRequest = syntheticRequest(origin, request.requestId, resourceValue, identity, step.args.value);
+            const operationRequest = syntheticRequest(origin, request, resourceValue, identity, step.args.value);
             const operationValidation = validateOperationRequest(contract, operationRequest, { transactionReferences: true });
             if (!operationValidation.ok) {
                 return {
@@ -338,9 +371,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 index,
                 request: operationRequest,
                 arguments: operationValidation.arguments,
-                projection: planReadOperation(dependencies.contracts.core, contract, (origin.origin === "application"
-                    ? dependencies.config.application
-                    : dependencies.config.client).behaviors, operationRequest, operationValidation.arguments).projection,
+                projection: planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, dependencies.config[origin.origin].compute, operationRequest, operationValidation.arguments).projection,
                 declaredFingerprint: node.get("fingerprint"),
                 candidates: collectTransactionReferenceCandidates(contract, operationRequest, index, operationValidation.arguments),
             };
@@ -353,7 +384,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 arguments: referenceValidation.requestArguments,
             };
             const validatedArguments = referenceValidation.arguments;
-            const wireArguments = origin.origin === "client"
+            const wireArguments = origin.origin !== "application"
                 ? validatedRequest.arguments
                 : encodeOperationArgumentsForWire(contract, validatedRequest, validatedArguments);
             let fingerprint;
@@ -366,7 +397,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 });
             }
             catch (error) {
-                if (!(error instanceof CanonicalJsonError)) {
+                if (!(error instanceof AvCanonicalJsonError)) {
                     throw error;
                 }
                 return {
@@ -404,6 +435,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 }
             }
             validated.push({
+                kind: "operation",
                 index: candidate.index,
                 request: validatedRequest,
                 contract,
@@ -414,7 +446,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
             });
         }
         catch (error) {
-            if (!(error instanceof CallerDataError)) {
+            if (!(error instanceof AvCallerDataError)) {
                 throw error;
             }
             return {

package/dist/transactions/transaction-reference-collector.d.ts

@@ -1,13 +1,13 @@
-import type { Contract } from "../contracts/contract.js";
-import type { ScalarField } from "../contracts/field.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvScalarField } from "../contracts/field.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
 import { type TransactionSlotShape } from "./transaction-reference.js";
 type Path = readonly (string | number)[];
 /** One `$ref` candidate found at a reference position, before it is validated. */
 export type TransactionReferenceCandidateSlot = {
     readonly path: Path;
-    readonly field: ScalarField<Contract>;
+    readonly field: AvScalarField<AvContract>;
     readonly shape: TransactionSlotShape;
     /** The slot is a scalar value of mutation data: what it resolves to is written. */
     readonly written: boolean;
@@ -24,7 +24,7 @@ export type TransactionReferenceCandidateSlot = {
  * It reads the validated argument view, whose normalization keeps every key where
  * the caller wrote it, so a slot path names the same member of the wire view.
  */
-export declare function collectTransactionReferenceCandidates(contract: Contract, request: OperationIdentity & {
+export declare function collectTransactionReferenceCandidates(contract: AvContract, request: AvOperationIdentity & {
     readonly resource: string;
 }, index: number, args: SemanticOperationArguments): readonly TransactionReferenceCandidateSlot[];
 export {};

package/dist/transactions/transaction-reference-resolver.d.ts

@@ -1,13 +1,30 @@
+import type { AvAdapterSqlStatement } from "../adapters/adapter-sql-statement.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { ValidatedSqlStatement } from "./sql-statement.js";
 import type { ValidatedTransactionOperation } from "./transaction-plan-validator.js";
 export type ResolvedTransactionArguments = {
     readonly ok: true;
     readonly arguments: SemanticOperationArguments;
 } | {
     readonly ok: false;
-    readonly issues: readonly ValidationIssue[];
+    readonly issues: readonly AvValidationIssue[];
 };
+export type ResolvedSqlStatement = {
+    readonly ok: true;
+    readonly statement: AvAdapterSqlStatement;
+} | {
+    readonly ok: false;
+    readonly issues: readonly AvValidationIssue[];
+};
+/**
+ * The statement a validated SQL step hands the Adapter: every `$ref` value read from
+ * the results ledger, exactly as an operation's slot is — the source's final data,
+ * copied by the source field's own codec — and then bound like any other value. A
+ * source row lacking the field is `V1018` at the value, before the statement runs.
+ * Issue paths are relative to the step (`["values", k, "$ref", "path"]`).
+ */
+export declare function resolveSqlStatement(statement: ValidatedSqlStatement, results: readonly unknown[]): ResolvedSqlStatement;
 /**
  * Substitutes every validated `$ref` placeholder of one operation from the results
  * ledger: each earlier operation's final `data`, exactly the value at its index in the

package/dist/transactions/transaction-reference-resolver.js

@@ -1,32 +1,44 @@
 import { validationIssue } from "../operations/validation-code.js";
-import { copyScalarFieldValue, jsonShapeIssues, } from "../runtime/scalar-runtime.js";
+import { copyScalarFieldValue } from "../runtime/scalar-runtime.js";
 import { replaceTransactionSlotValues } from "./transaction-slot-writer.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function unresolvedIssue(path) {
+    return validationIssue("V1018", [...path, "$ref", "path"], "Transaction reference resolved to no value.");
+}
+export function resolveSqlStatement(statement, results) {
+    const values = [];
+    for (const [position, value] of statement.values.entries()) {
+        if (value.kind === "value") {
+            values.push(value.value);
+            continue;
+        }
+        const row = results[value.operation];
+        if (!isRecord(row) || !Object.hasOwn(row, value.field)) {
+            return { ok: false, issues: [unresolvedIssue(["values", position])] };
+        }
+        values.push(copyScalarFieldValue(value.source, row[value.field]));
+    }
+    return {
+        ok: true,
+        statement: Object.freeze({
+            strings: statement.strings,
+            values: Object.freeze(values),
+        }),
+    };
+}
 export function resolveTransactionReferences(operation, results) {
     const substitutions = [];
-    const shapeIssues = [];
     for (const slot of operation.references) {
         const { operation: source, path: [segment], } = slot.reference.$ref;
         const row = results[source];
         if (!isRecord(row) || !Object.hasOwn(row, segment)) {
-            return {
-                ok: false,
-                issues: [
-                    validationIssue("V1018", [...slot.path, "$ref", "path"], "Transaction reference resolved to no value."),
-                ],
-            };
+            return { ok: false, issues: [unresolvedIssue(slot.path)] };
         }
         const value = copyScalarFieldValue(slot.source, row[segment]);
-        if (slot.written) {
-            shapeIssues.push(...jsonShapeIssues(slot.field, value, slot.path));
-        }
         substitutions.push({ path: slot.path, value });
     }
-    if (shapeIssues.length > 0) {
-        return { ok: false, issues: shapeIssues };
-    }
     return {
         ok: true,
         arguments: replaceTransactionSlotValues(operation.arguments, operation.index, substitutions),

package/dist/transactions/transaction-reference-validator.d.ts

@@ -1,5 +1,9 @@
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
-import type { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionOperation } from "./transaction-plan-validator.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvField } from "../contracts/field.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import type { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionStep } from "./transaction-plan-validator.js";
+type Path = readonly (string | number)[];
 type ReferenceValidationResult = {
     readonly ok: true;
     readonly references: readonly TransactionReferenceSlot[];
@@ -7,8 +11,34 @@ type ReferenceValidationResult = {
     readonly requestArguments: unknown;
 } | {
     readonly ok: false;
-    readonly response: OperationFailureResponse;
+    readonly response: AvOperationFailureResponse;
 };
+/** The `V1016` refusal of a reference's source index, at its `operation` member. */
+export declare function invalidSourceIndexIssue(operationPath: Path): AvValidationIssue;
+/**
+ * The validated step a reference names, or `undefined` when its index is no
+ * integer naming a step before the referencing one (`V1016`).
+ */
+export declare function referenceSourceAt(earlier: readonly ValidatedTransactionStep[], sourceIndex: unknown, referencingIndex: number): ValidatedTransactionStep | undefined;
+/** The `V1010` refusal of a reference whose source is an `appTx.$sql` step. */
+export declare function sqlSourceIssue(pathPath: Path): AvValidationIssue;
+/** The field a reference reads from its source step, or why it cannot read one. */
+export type ReferenceSourceRead = {
+    readonly ok: true;
+    readonly field: AvField<AvContract>;
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Reads the field a reference's one path segment names from its source step,
+ * holding the source to what a reference may read: one row (not a `many` or
+ * `count` result, not a SQL step's rows), and a field in its actual projection,
+ * never a reducer. The field is read under the source's own Contract: in a plan
+ * that mixes origins, a source field the referencing step's layer hides is still
+ * the source's to read. Assignability to a destination is the caller's.
+ */
+export declare function referenceSourceField(source: ValidatedTransactionStep, segment: string, pathPath: Path): ReferenceSourceRead;
 /** Validates every passive reference candidate before operation fingerprinting. */
-export declare function validateTransactionReferences(operation: CandidateTransactionOperation, earlier: readonly ValidatedTransactionOperation[]): ReferenceValidationResult;
+export declare function validateTransactionReferences(operation: CandidateTransactionOperation, earlier: readonly ValidatedTransactionStep[]): ReferenceValidationResult;
 export {};

package/dist/transactions/transaction-reference-validator.js

@@ -164,6 +164,52 @@ function isAssignable(source, destination, shape) {
             return source.list && !source.nullable;
     }
 }
+export function invalidSourceIndexIssue(operationPath) {
+    return validationIssue("V1016", operationPath, "Transaction reference operation index is invalid.");
+}
+export function referenceSourceAt(earlier, sourceIndex, referencingIndex) {
+    if (typeof sourceIndex !== "number" ||
+        !Number.isInteger(sourceIndex) ||
+        sourceIndex < 0 ||
+        sourceIndex >= referencingIndex) {
+        return undefined;
+    }
+    const source = earlier[sourceIndex];
+    return source !== undefined && source.index === sourceIndex
+        ? source
+        : undefined;
+}
+export function sqlSourceIssue(pathPath) {
+    return validationIssue("V1010", pathPath, "Transaction reference source is a SQL step, whose rows cannot be referenced.");
+}
+export function referenceSourceField(source, segment, pathPath) {
+    if (source.kind === "sql") {
+        return { ok: false, issue: sqlSourceIssue(pathPath) };
+    }
+    if (source.request.variant === "many" || source.request.variant === "count") {
+        return {
+            ok: false,
+            issue: validationIssue("V1010", pathPath, "Transaction reference source has no addressable single-row projection."),
+        };
+    }
+    const projection = source.projection;
+    if (projection?.reducers.some((reducer) => reducer === segment)) {
+        return {
+            ok: false,
+            issue: validationIssue("V1011", pathPath, "Transaction reference source is not a scalar field."),
+        };
+    }
+    const field = projection === undefined || !projection.requested.includes(segment)
+        ? undefined
+        : lookupField(lookupResource(source.contract, projection.resource), segment);
+    if (field === undefined) {
+        return {
+            ok: false,
+            issue: validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."),
+        };
+    }
+    return { ok: true, field };
+}
 const CANDIDATE_KEYS = new Set(["$ref"]);
 const REFERENCE_KEYS = new Set(["operation", "fingerprint", "path"]);
 export function validateTransactionReferences(operation, earlier) {
@@ -188,19 +234,15 @@ export function validateTransactionReferences(operation, earlier) {
             return failure(sourceIndexProperty.issue, operation.index);
         }
         const sourceIndex = sourceIndexProperty.value;
-        const source = typeof sourceIndex === "number" && Number.isInteger(sourceIndex)
-            ? earlier[sourceIndex]
-            : undefined;
-        if (typeof sourceIndex !== "number" ||
-            !Number.isInteger(sourceIndex) ||
-            sourceIndex < 0 ||
-            sourceIndex >= operation.index ||
-            source === undefined ||
-            source.index !== sourceIndex) {
-            return failure(validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."), operation.index);
+        const source = referenceSourceAt(earlier, sourceIndex, operation.index);
+        if (source === undefined) {
+            return failure(invalidSourceIndexIssue(operationPath), operation.index);
+        }
+        if (source.kind === "sql") {
+            return failure(sqlSourceIssue([...refPath, "path"]), operation.index);
         }
         const fingerprintPath = [...refPath, "fingerprint"];
-        const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1017", refPath);
+        const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1000", refPath);
         if (!fingerprintProperty.ok) {
             return failure(fingerprintProperty.issue, operation.index);
         }
@@ -222,28 +264,18 @@ export function validateTransactionReferences(operation, earlier) {
         if (containsUnpairedSurrogate(segment)) {
             return failure(validationIssue("V1010", pathPath, "Transaction reference path contains invalid Unicode."), operation.index);
         }
-        if (source.request.variant === "many" ||
-            source.request.variant === "count") {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference source has no addressable single-row projection."), operation.index);
-        }
-        const projection = source.projection;
-        if (projection?.reducers.some((reducer) => reducer === segment)) {
-            return failure(validationIssue("V1011", pathPath, "Transaction reference source is not a scalar field."), operation.index);
-        }
-        if (projection === undefined || !projection.requested.includes(segment)) {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
-        }
-        const sourceField = lookupField(lookupResource(source.contract, projection.resource), segment);
-        if (sourceField === undefined) {
-            return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
+        const sourceRead = referenceSourceField(source, segment, pathPath);
+        if (!sourceRead.ok) {
+            return failure(sourceRead.issue, operation.index);
         }
+        const sourceField = sourceRead.field;
         if (sourceField.kind !== "scalar" ||
             !isAssignable(sourceField, slot.field, slot.shape)) {
             return failure(validationIssue("V1011", pathPath, "Transaction reference source type is not assignable to its destination."), operation.index);
         }
         const reference = Object.freeze({
             $ref: Object.freeze({
-                operation: sourceIndex,
+                operation: source.index,
                 fingerprint,
                 path: Object.freeze([segment]),
             }),

package/dist/transactions/transaction-reference.d.ts

@@ -1,8 +1,8 @@
-import type { WriteScope } from "../contracts/capability.js";
-import type { Contract } from "../contracts/contract.js";
+import type { AvWriteScope } from "../contracts/capability.js";
+import type { AvContract } from "../contracts/contract.js";
 import type { ScalarForms } from "../contracts/scalar-value-type.js";
-import type { CreateDataInput, OperationArgumentsFor, ResourceKey, UpdateDataInput } from "../operations/operation-arguments.js";
-import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { AvCreateDataInput, AvOperationArgumentsFor, AvResourceKey, AvUpdateDataInput } from "../operations/operation-arguments.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 declare const REFERENCE_VALUE: unique symbol;
 /** Any object with a `$ref` key, before it is validated as a reference. */
@@ -13,7 +13,7 @@ export type TransactionReferenceCandidate = {
  * A reference to a field of an earlier operation's result in the same
  * transaction plan: `{ $ref: { operation, fingerprint, path } }`.
  */
-export type TransactionReference<Value = unknown> = {
+export type AvTransactionReference<Value = unknown> = {
     readonly $ref: {
         readonly operation: number;
         readonly fingerprint: OperationFingerprint;
@@ -38,12 +38,12 @@ export declare function routeTransactionReferenceCandidate(value: unknown): Tran
 /** Whether `value` is an object with a `$ref` key; it is not validated here. */
 export declare function isTransactionReferenceCandidate(value: unknown): value is TransactionReferenceCandidate;
 /** Whether `value` is a complete `$ref` object. */
-export declare function isTransactionReferenceObject(value: unknown): value is TransactionReference;
+export declare function isTransactionReferenceObject(value: unknown): value is AvTransactionReference;
 /**
  * A scalar mutation value inside a plan: the value itself, or a reference to an
  * earlier operation's field of that same type.
  */
-export type TransactionScalarValue<Value> = Value | TransactionReference<Value>;
+export type TransactionScalarValue<Value> = Value | AvTransactionReference<Value>;
 /**
  * What a Transaction Slot holds of its destination field, which decides the source
  * fields a reference there accepts — always the same scalar or enum, no coercion:
@@ -62,16 +62,16 @@ export type TransactionSlotShape = "value" | "nonNullValue" | "entry" | "entries
 /**
  * Create data inside a transaction plan, at one write position: its scalar values
  * and the unique keys its relation directives name may hold a `$ref`. The default
- * is the unrestricted position, as on `CreateDataInput`.
+ * is the unrestricted position, as on `AvCreateDataInput`.
  */
-export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = CreateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
+export type TransactionCreateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = "nested"> = AvCreateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
 /** Update data inside a transaction plan. See {@link TransactionCreateDataInput}. */
-export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = UpdateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
+export type TransactionUpdateDataInput<C extends AvContract, K extends AvResourceKey<C>, Scope extends AvWriteScope = "nested"> = AvUpdateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
 /**
  * Operation arguments inside a transaction plan, under one value form and one
- * reference form: `OperationArgumentsFor` with its reference positions opened.
+ * reference form: `AvOperationArgumentsFor` with its reference positions opened.
  */
-export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = OperationArgumentsFor<C, K, I, Forms, ReferenceForms>;
+export type ReferenceableArgumentsFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = AvOperationArgumentsFor<C, K, I, Forms, ReferenceForms>;
 /** Operation arguments inside a transaction plan, no scalar form stated. */
-export type TransactionOperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity> = ReferenceableArgumentsFor<C, K, I, ScalarForms, ScalarForms>;
+export type TransactionOperationArgumentsFor<C extends AvContract, K extends AvResourceKey<C>, I extends AvOperationIdentity> = ReferenceableArgumentsFor<C, K, I, ScalarForms, ScalarForms>;
 export {};

package/dist/transactions/transaction-request.d.ts

@@ -1,8 +1,14 @@
 import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
-import type { PipelineTransportContext } from "../runtime/pipeline.js";
+import type { AvTransportContext } from "../runtime/pipeline.js";
+import type { AvState } from "../runtime/request-state.js";
 type TransactionRequestBase = {
     readonly requestId: string;
     readonly plan: unknown;
+    /**
+     * The run's `ctx.$state`: every step's stages and the transaction stages share
+     * this one object. Omitted, it is a fresh `{}`.
+     */
+    readonly state?: AvState;
 };
 /** An in-process transaction request, run under the Application Contract. */
 export type ApplicationTransactionRequest = TransactionRequestBase & {
@@ -14,13 +20,20 @@ export type ApplicationTransactionRequest = TransactionRequestBase & {
 export type ClientTransactionRequest = TransactionRequestBase & {
     readonly origin: "client";
     readonly protocol: ClientProtocolIdentity;
-    readonly transport?: PipelineTransportContext;
+    readonly transport?: AvTransportContext;
+};
+/** An AI agent's transaction request, run under the Agent Contract. */
+export type AgentTransactionRequest = TransactionRequestBase & {
+    readonly origin: "agent";
+    readonly protocol: ClientProtocolIdentity;
+    readonly transport?: AvTransportContext;
 };
 /** One transaction request, as `framework.executeTransaction` takes it. */
-export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest;
+export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest | AgentTransactionRequest;
 /**
  * The origin one plan operation runs under: its own layer's Contract, its own
- * pipelines, and — for a client step — the protocol identity it is accepted with.
+ * pipelines, and — for a client or agent step — the protocol identity it is
+ * accepted with.
  */
-export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "origin"> | Pick<ClientTransactionRequest, "origin" | "protocol" | "transport">;
+export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "origin"> | Pick<ClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AgentTransactionRequest, "origin" | "protocol" | "transport">;
 export {};