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

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

@@ -164,86 +164,136 @@ 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;
+}
+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) {
+export function inspectReferenceCandidate(candidate, slotPath, earlier, referencingIndex) {
+    const refused = (issue) => ({ ok: false, issue });
+    const candidateInspection = inspectControlObject(candidate, CANDIDATE_KEYS, slotPath, validationIssue("V1001", slotPath, "Reference control value must be an object."));
+    if (!candidateInspection.ok) {
+        return refused(candidateInspection.issue);
+    }
+    const refPath = [...slotPath, "$ref"];
+    const refProperty = inspectOwnDataProperty(candidateInspection.value, "$ref", refPath, "V1001", slotPath);
+    if (!refProperty.ok) {
+        return refused(refProperty.issue);
+    }
+    const operationPath = [...refPath, "operation"];
+    const referenceInspection = inspectControlObject(refProperty.value, REFERENCE_KEYS, refPath, validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."));
+    if (!referenceInspection.ok) {
+        return refused(referenceInspection.issue);
+    }
+    const sourceIndexProperty = inspectOwnDataProperty(referenceInspection.value, "operation", operationPath, "V1016", refPath);
+    if (!sourceIndexProperty.ok) {
+        return refused(sourceIndexProperty.issue);
+    }
+    const source = referenceSourceAt(earlier, sourceIndexProperty.value, referencingIndex);
+    if (source === undefined) {
+        return refused(invalidSourceIndexIssue(operationPath));
+    }
+    if (source.kind === "sql") {
+        return refused(sqlSourceIssue([...refPath, "path"]));
+    }
+    const fingerprintPath = [...refPath, "fingerprint"];
+    const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1000", refPath);
+    if (!fingerprintProperty.ok) {
+        return refused(fingerprintProperty.issue);
+    }
+    const fingerprint = fingerprintProperty.value;
+    if (!isOperationFingerprint(fingerprint) ||
+        fingerprint !== source.fingerprint) {
+        return refused(validationIssue("V1017", fingerprintPath, "Transaction reference fingerprint does not match its source operation."));
+    }
+    const pathPath = [...refPath, "path"];
+    const pathProperty = inspectOwnDataProperty(referenceInspection.value, "path", pathPath, "V1010", refPath);
+    if (!pathProperty.ok) {
+        return refused(pathProperty.issue);
+    }
+    const pathInspection = inspectPathTuple(pathProperty.value, pathPath);
+    if (!pathInspection.ok) {
+        return refused(pathInspection.issue);
+    }
+    const { segment } = pathInspection;
+    if (containsUnpairedSurrogate(segment)) {
+        return refused(validationIssue("V1010", pathPath, "Transaction reference path contains invalid Unicode."));
+    }
+    const sourceRead = referenceSourceField(source, segment, pathPath);
+    if (!sourceRead.ok) {
+        return refused(sourceRead.issue);
+    }
+    return {
+        ok: true,
+        source,
+        segment,
+        fingerprint,
+        field: sourceRead.field,
+        pathPath,
+    };
+}
+export function validateReferenceSlots(candidates, earlier, index) {
     const references = [];
-    for (const slot of operation.candidates) {
-        const candidateInspection = inspectControlObject(slot.candidate, CANDIDATE_KEYS, slot.path, validationIssue("V1001", slot.path, "Reference control value must be an object."));
-        if (!candidateInspection.ok) {
-            return failure(candidateInspection.issue, operation.index);
-        }
-        const refPath = [...slot.path, "$ref"];
-        const refProperty = inspectOwnDataProperty(candidateInspection.value, "$ref", refPath, "V1001", slot.path);
-        if (!refProperty.ok) {
-            return failure(refProperty.issue, operation.index);
-        }
-        const operationPath = [...refPath, "operation"];
-        const referenceInspection = inspectControlObject(refProperty.value, REFERENCE_KEYS, refPath, validationIssue("V1016", operationPath, "Transaction reference operation index is invalid."));
-        if (!referenceInspection.ok) {
-            return failure(referenceInspection.issue, operation.index);
-        }
-        const sourceIndexProperty = inspectOwnDataProperty(referenceInspection.value, "operation", operationPath, "V1016", refPath);
-        if (!sourceIndexProperty.ok) {
-            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 fingerprintPath = [...refPath, "fingerprint"];
-        const fingerprintProperty = inspectOwnDataProperty(referenceInspection.value, "fingerprint", fingerprintPath, "V1017", refPath);
-        if (!fingerprintProperty.ok) {
-            return failure(fingerprintProperty.issue, operation.index);
-        }
-        const fingerprint = fingerprintProperty.value;
-        if (!isOperationFingerprint(fingerprint) ||
-            fingerprint !== source.fingerprint) {
-            return failure(validationIssue("V1017", fingerprintPath, "Transaction reference fingerprint does not match its source operation."), operation.index);
-        }
-        const pathPath = [...refPath, "path"];
-        const pathProperty = inspectOwnDataProperty(referenceInspection.value, "path", pathPath, "V1010", refPath);
-        if (!pathProperty.ok) {
-            return failure(pathProperty.issue, operation.index);
-        }
-        const pathInspection = inspectPathTuple(pathProperty.value, pathPath);
-        if (!pathInspection.ok) {
-            return failure(pathInspection.issue, operation.index);
-        }
-        const { segment } = pathInspection;
-        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);
+    for (const slot of candidates) {
+        const inspection = inspectReferenceCandidate(slot.candidate, slot.path, earlier, index);
+        if (!inspection.ok) {
+            return inspection;
         }
+        const { source, segment, fingerprint, pathPath } = inspection;
+        const sourceField = inspection.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);
+            return {
+                ok: false,
+                issue: validationIssue("V1011", pathPath, "Transaction reference source type is not assignable to its destination."),
+            };
         }
         const reference = Object.freeze({
             $ref: Object.freeze({
-                operation: sourceIndex,
+                operation: source.index,
                 fingerprint,
                 path: Object.freeze([segment]),
             }),
@@ -257,6 +307,14 @@ export function validateTransactionReferences(operation, earlier) {
             reference,
         });
     }
+    return { ok: true, references };
+}
+export function validateTransactionReferences(operation, earlier) {
+    const validation = validateReferenceSlots(operation.candidates, earlier, operation.index);
+    if (!validation.ok) {
+        return failure(validation.issue, operation.index);
+    }
+    const { references } = validation;
     const controls = references.map((slot) => ({
         path: slot.path,
         value: slot.reference,

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;
@@ -22,7 +22,7 @@ export type TransactionReference<Value = unknown> = {
     readonly [REFERENCE_VALUE]?: Value;
 };
 /** Whether a value is an ordinary value or a `$ref` candidate. */
-export type TransactionReferenceCandidateRoute = {
+type TransactionReferenceCandidateRoute = {
     readonly kind: "ordinary";
 } | {
     readonly kind: "candidate";
@@ -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-reference.js

@@ -14,6 +14,11 @@ export function routeTransactionReferenceCandidate(value) {
         if (!ownKeys.includes("$ref") || referenceDescriptor === undefined) {
             return ORDINARY_ROUTE;
         }
+        if ("value" in referenceDescriptor &&
+            (referenceDescriptor.value === null ||
+                typeof referenceDescriptor.value !== "object")) {
+            return ORDINARY_ROUTE;
+        }
         return {
             kind: "candidate",
             candidate: value,

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

@@ -1,26 +1,39 @@
-import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
-import type { PipelineTransportContext } from "../runtime/pipeline.js";
+import type { AvRequestProtocol } from "../runtime/operation-request.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 & {
+export type AvApplicationTransactionRequest = TransactionRequestBase & {
     readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
 /** A remote transaction request, run under the Client Contract. */
-export type ClientTransactionRequest = TransactionRequestBase & {
+export type AvClientTransactionRequest = TransactionRequestBase & {
     readonly origin: "client";
-    readonly protocol: ClientProtocolIdentity;
-    readonly transport?: PipelineTransportContext;
+    readonly protocol: AvRequestProtocol;
+    readonly transport?: AvTransportContext;
+};
+/** An AI agent's transaction request, run under the Agent Contract. */
+export type AvAgentTransactionRequest = TransactionRequestBase & {
+    readonly origin: "agent";
+    readonly protocol: AvRequestProtocol;
+    readonly transport?: AvTransportContext;
 };
 /** One transaction request, as `framework.executeTransaction` takes it. */
-export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest;
+export type AvTransactionRequest = AvApplicationTransactionRequest | AvClientTransactionRequest | AvAgentTransactionRequest;
 /**
  * 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<AvApplicationTransactionRequest, "origin"> | Pick<AvClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AvAgentTransactionRequest, "origin" | "protocol" | "transport">;
 export {};

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

@@ -1,20 +1,20 @@
-import type { OperationFailureResponse } from "../runtime/operation-response.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
 /** A committed plan: each operation's final `data`, in plan order. */
-export type TransactionCommittedResponse<T = readonly unknown[]> = {
+export type AvTransactionCommittedResponse<T = readonly unknown[]> = {
     readonly data: T;
     readonly code: "A1009";
     readonly cause: null;
 };
 /** What a transaction answers: committed (`A1009`) or a failure. */
-export type TransactionResponse = TransactionCommittedResponse | OperationFailureResponse;
+export type AvTransactionResponse = AvTransactionCommittedResponse | AvOperationFailureResponse;
 /** Builds the committed response. */
-export declare function transactionCommitted(results: readonly unknown[]): TransactionCommittedResponse;
+export declare function transactionCommitted(results: readonly unknown[]): AvTransactionCommittedResponse;
 /**
  * Builds the failure response of a plan step: the step named in
  * `cause.operation`, and each issue at its full plan location —
  * `["operations", operation, "args", …]` for the step's arguments,
  * `["operations", operation, …]` for the step itself.
  */
-export declare function transactionOperationFailure(failure: OperationFailureResponse, operation: number): OperationFailureResponse;
+export declare function transactionOperationFailure(failure: AvOperationFailureResponse, operation: number): AvOperationFailureResponse;
 /** Builds the `A3002` response for a transaction that itself failed. */
-export declare function transactionInfrastructureFailure(operation?: number): OperationFailureResponse;
+export declare function transactionInfrastructureFailure(operation?: number): AvOperationFailureResponse;

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

@@ -1,9 +1,10 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import { type PolicyCaller } from "../policy/policy-request.js";
 import type { TransactionDiagnosticsChannel } from "../runtime/diagnostics-reporter.js";
-import type { OperationRuntimeDependencies } from "../runtime/operation-runtime.js";
+import type { OperationPipelineDependencies, OperationRuntimeDependencies } from "../runtime/operation-runtime.js";
 import type { PlanArguments } from "./transaction-plan-validator.js";
-import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
-import type { TransactionResponse } from "./transaction-response.js";
+import type { AvTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
+import type { AvTransactionResponse } from "./transaction-response.js";
 /**
  * The transaction executor core. Like the operation executor it owns no
  * diagnostics channel: the framework factory binds one to the request and
@@ -13,10 +14,13 @@ import type { TransactionResponse } from "./transaction-response.js";
  * runner's mixed plans), and `planArguments` whether the steps' arguments are
  * copied at the door; see `validateTransactionPlan`.
  */
-export type FrameworkTransactionExecutor = (request: FrameworkTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins: readonly TransactionOperationOrigin[] | undefined, planArguments: PlanArguments) => Promise<TransactionResponse>;
+export type FrameworkTransactionExecutor = (request: AvTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins: readonly TransactionOperationOrigin[] | undefined, planArguments: PlanArguments, 
+/** The principal an application run's steps run as (`{ as }`), when it names one. */
+caller?: PolicyCaller) => Promise<AvTransactionResponse>;
 /**
  * Validates a whole plan through the Framework Validation Layer, then runs it inside
- * exactly one Adapter transaction. Guards, pipes, hooks and interceptors of every plan
- * operation run while the provider transaction is open.
+ * exactly one Adapter transaction. The touched Resources' transaction stages and
+ * every plan operation's guards, pipes, hooks and interceptors run while the
+ * provider transaction is open.
  */
-export declare function createTransactionRuntime<M extends AdapterModel>(dependencies: OperationRuntimeDependencies<M>): FrameworkTransactionExecutor;
+export declare function createTransactionRuntime<M extends AvAdapterModel>(dependencies: OperationRuntimeDependencies<M>, pipelineDependencies: OperationPipelineDependencies<M>): FrameworkTransactionExecutor;