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

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, mirrorCallerData, } 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";
@@ -22,9 +24,41 @@ const CALLER_PLAN = { source: "caller" };
 const STEP_ARGUMENTS_POLICY = {
     mirror: (value) => Object.hasOwn(value, "$ref"),
 };
+export function capturePlanAtCall(plan) {
+    const refused = new Map();
+    if (typeof plan !== "object" || plan === null) {
+        return { plan, refused };
+    }
+    try {
+        const mirrored = mirrorCallerData(plan, {
+            copyAt: (path) => path.length === 3 &&
+                path[0] === "operations" &&
+                typeof path[1] === "number" &&
+                path[2] === "args"
+                ? STEP_ARGUMENTS_POLICY
+                : undefined,
+            refused: (path, error) => {
+                refused.set(path[1], error);
+            },
+        });
+        return { plan: mirrored, refused };
+    }
+    catch (error) {
+        if (error instanceof AvCallerDataError) {
+            return { plan, refused };
+        }
+        throw error;
+    }
+}
 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 +89,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 +107,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 +132,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 +144,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 +155,7 @@ function requestOrigin(request) {
     return request.origin === "application"
         ? { origin: "application" }
         : {
-            origin: "client",
+            origin: request.origin,
             protocol: request.protocol,
             ...(request.transport === undefined
                 ? {}
@@ -124,7 +164,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 +262,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 +317,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 +348,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 +359,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 +385,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 +397,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 +410,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 +423,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 });
             }
             catch (error) {
-                if (!(error instanceof CanonicalJsonError)) {
+                if (!(error instanceof AvCanonicalJsonError)) {
                     throw error;
                 }
                 return {
@@ -404,6 +461,7 @@ export async function validateTransactionPlan(dependencies, request, origins, pl
                 }
             }
             validated.push({
+                kind: "operation",
                 index: candidate.index,
                 request: validatedRequest,
                 contract,
@@ -414,7 +472,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,11 @@
-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 { OperationFingerprint } from "./deferred-operation.js";
+import type { CandidateTransactionOperation, TransactionReferenceSlot, ValidatedTransactionStep } from "./transaction-plan-validator.js";
+import type { TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
+type Path = readonly (string | number)[];
 type ReferenceValidationResult = {
     readonly ok: true;
     readonly references: readonly TransactionReferenceSlot[];
@@ -7,8 +13,74 @@ 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;
+/** A `$ref` control object read through: its source step, field and fingerprint. */
+export type ReferenceCandidateInspection = {
+    readonly ok: true;
+    readonly source: Extract<ValidatedTransactionStep, {
+        kind: "operation";
+    }>;
+    readonly segment: string;
+    readonly fingerprint: OperationFingerprint;
+    readonly field: AvField<AvContract>;
+    /** The candidate's `path` member's own path, where a type refusal stands. */
+    readonly pathPath: Path;
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Inspects one `$ref` control object standing at `slotPath` of step
+ * `referencingIndex`, through property descriptors only: its shape, its source
+ * step (an earlier one, never a SQL step), the source's fingerprint and the one
+ * field its path reads from the source's projection. Assignability to the
+ * destination is the caller's. Shared by an operation step's slots and an
+ * `appTx.$sql` value, so both refuse a malformed reference alike.
+ */
+export declare function inspectReferenceCandidate(candidate: unknown, slotPath: Path, earlier: readonly ValidatedTransactionStep[], referencingIndex: number): ReferenceCandidateInspection;
+/** The validated slots of a step's candidates, or the first one's refusal. */
+export type ReferenceSlotsValidation = {
+    readonly ok: true;
+    readonly references: readonly TransactionReferenceSlot[];
+} | {
+    readonly ok: false;
+    readonly issue: AvValidationIssue;
+};
+/**
+ * Judges every `$ref` candidate of step `index` by the Framework Validation
+ * Layer's reference rules — its shape, an earlier non-SQL source step, that
+ * step's fingerprint, a field of its single-row projection, and type
+ * compatibility with the slot it stands in — and answers the validated slots,
+ * or the first refusal.
+ */
+export declare function validateReferenceSlots(candidates: readonly TransactionReferenceCandidateSlot[], earlier: readonly ValidatedTransactionStep[], index: number): ReferenceSlotsValidation;
 /** 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 {};