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

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

@@ -2,7 +2,9 @@ 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;
@@ -39,6 +41,46 @@ export type ReferenceSourceRead = {
  * 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 ValidatedTransactionStep[]): ReferenceValidationResult;
 export {};

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

@@ -212,66 +212,84 @@ export function referenceSourceField(source, segment, pathPath) {
 }
 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);
+    for (const slot of candidates) {
+        const inspection = inspectReferenceCandidate(slot.candidate, slot.path, earlier, index);
+        if (!inspection.ok) {
+            return inspection;
         }
-        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 = 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, "V1000", 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);
-        }
-        const sourceRead = referenceSourceField(source, segment, pathPath);
-        if (!sourceRead.ok) {
-            return failure(sourceRead.issue, operation.index);
-        }
-        const sourceField = sourceRead.field;
+        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({
@@ -289,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.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-runtime.js

@@ -1,16 +1,18 @@
 import { transactionLevelsOf } from "../config/pipeline-tree.resolver.js";
 import { AdapterBoundary, planOperationArgumentsPath, planStepPath, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
-import { isPlainRecord, valueAt } from "../runtime/field-stage.runtime.js";
 import { internalFailure, operationSuccess, } from "../runtime/operation-response.js";
-import { admitOperation, executeAdmittedOperation, prepareStep, withRequestState, } from "../runtime/operation-runtime.js";
+import { admitOperation, EVERY_FIELD, executeAdmittedOperation, prepareStep, STEP_PIPES, withRequestState, } from "../runtime/operation-runtime.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
+import { refusedStageOutput, serverContractFor, } from "../runtime/pipe-output.validator.js";
 import { resolveCascadeClosure } from "../runtime/referential-action.js";
 import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
 import { validateTransactionPlan } from "./transaction-plan-validator.js";
+import { collectTransactionReferenceCandidates } from "./transaction-reference-collector.js";
 import { resolveSqlStatement, resolveTransactionReferences, } from "./transaction-reference-resolver.js";
+import { validateReferenceSlots } from "./transaction-reference-validator.js";
 import { transactionCommitted, transactionInfrastructureFailure, transactionOperationFailure, } from "./transaction-response.js";
 import { settleTransaction } from "./transaction-settlement.runtime.js";
-import { touchedTransactionLevels, transactionFacts, } from "./transaction-stage.runtime.js";
+import { TRANSACTION_PIPES, touchedTransactionLevels, transactionFacts, } from "./transaction-stage.runtime.js";
 export function createTransactionRuntime(dependencies, pipelineDependencies) {
     const { adapter } = dependencies;
     const planDependencies = {
@@ -59,39 +61,54 @@ function pathKey(path) {
 function relativeSlotPath(operation, path) {
     return path.slice(planOperationArgumentsPath(operation.index).length);
 }
-function standsAt(args, path, slot) {
-    const value = valueAt(args, path);
-    if (value === slot.reference) {
-        return true;
+function standingReferences(core, operation, args, steps, subject) {
+    const candidates = collectTransactionReferenceCandidates(serverContractFor(core, operation.contract), operation.request, operation.index, args);
+    const validation = validateReferenceSlots(candidates, steps, operation.index);
+    if (validation.ok) {
+        return validation;
     }
-    const reference = isPlainRecord(value) ? value.$ref : undefined;
-    if (!isPlainRecord(reference) || !Array.isArray(reference.path)) {
-        return false;
+    const { issue } = validation;
+    const refused = refusedStageOutput(operation.request, [
+        {
+            ...issue,
+            path: ["arguments", ...relativeSlotPath(operation, issue.path ?? [])],
+        },
+    ], subject);
+    if (refused === undefined) {
+        throw new TypeError("A refused reference produced no refusal.");
     }
-    const expected = slot.reference.$ref;
-    return (reference.operation === expected.operation &&
-        reference.path.length === 1 &&
-        reference.path[0] === expected.path[0]);
-}
-function slotKeys(operation) {
-    return new Set(operation.references.map((slot) => pathKey(relativeSlotPath(operation, slot.path))));
+    return { ok: false, ...refused };
 }
 async function executeTransactionPlan(adapter, dependencies, request, plan, state, diagnostics) {
     const stateful = (operation) => ({ ...operation.request, state });
     const admitted = [];
+    const standing = [];
     for (const step of plan.operations) {
         if (step.kind === "sql") {
             admitted.push({ ok: true, args: undefined, piped: false });
+            standing.push([]);
             continue;
         }
-        const references = slotKeys(step);
-        const admission = await admitOperation(dependencies, stateful(step), step.contract, step.arguments, planOperationArgumentsPath(step.index), diagnostics.operation(step.request, step.index), { requestId: request.requestId, transaction: undefined, state }, {
-            select: (path) => !references.has(pathKey(path)),
+        const report = diagnostics.operation(step.request, step.index);
+        const admission = await admitOperation(dependencies, stateful(step), step.contract, step.arguments, planOperationArgumentsPath(step.index), report, { requestId: request.requestId, transaction: undefined, state }, {
+            select: EVERY_FIELD,
             validation: { transactionReferences: true },
+            beforeBegin: true,
         });
         if (!admission.ok) {
             return transactionOperationFailure(admission.response, step.index);
         }
+        if (!admission.piped) {
+            standing.push(step.references);
+        }
+        else {
+            const references = standingReferences(dependencies.contracts.core, step, admission.args, plan.operations, STEP_PIPES);
+            if (!references.ok) {
+                report(references.error, "A3004");
+                return transactionOperationFailure(references.response, step.index);
+            }
+            standing.push(references.references);
+        }
         admitted.push(admission);
     }
     const origin = planOrigin(request, plan);
@@ -103,7 +120,15 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
         const argumentsPath = planOperationArgumentsPath(operation.index);
         const stepRequest = stateful(operation);
         try {
-            const live = operation.references.filter((slot) => standsAt(args, relativeSlotPath(operation, slot.path), slot));
+            let live = standing[operation.index] ?? operation.references;
+            if (transactionPiped) {
+                const references = standingReferences(dependencies.contracts.core, operation, args, plan.operations, TRANSACTION_PIPES);
+                if (!references.ok) {
+                    report(references.error, "A3004");
+                    return references.response;
+                }
+                live = references.references;
+            }
             const resolved = resolveTransactionReferences({
                 ...operation,
                 arguments: args,
@@ -119,7 +144,7 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
                 written: (path) => written.has(pathKey(path)),
                 transactionPiped,
                 pipedAroundReferences: admitted[operation.index]?.piped === true &&
-                    operation.references.length > 0,
+                    (live.length > 0 || operation.references.length > 0),
             }, outer);
             if (!prepared.ok) {
                 return prepared.response;

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

@@ -23,7 +23,8 @@ export type TransactionStepView = AvTransactionStep;
 export declare const TRANSACTION_PIPES = "Transaction pipes";
 /**
  * The `$` facts a transaction stage is told: the plan as `$args`, not one
- * operation (`$operation` is absent).
+ * operation (`$operation` is absent). Each ctx holds its own frozen copy of the
+ * plan, a `Date` or a `Uint8Array` in a step's arguments fresh.
  */
 export declare function transactionFacts(contract: AvContract, request: Pick<OperationExecutionRequest, "origin" | "requestId" | "transport">, plan: readonly TransactionStepView[]): ContextFacts;
 /** How the transaction stages around a plan's steps ended. */

package/dist/transactions/transaction-stage.runtime.js

@@ -2,7 +2,7 @@ import { AdapterBoundary, resolveOperationFailure, } from "../runtime/error-boun
 import { runLevelLifecycle, } from "../runtime/level-lifecycle.runtime.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { AvPipeOutputError, PIPE_OUTPUT_FAILURE_MESSAGE, } from "../runtime/pipe-output.validator.js";
-import { deepFreeze } from "../runtime/readonly-value.js";
+import { deepFreeze, frozenCopy } from "../runtime/readonly-value.js";
 import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
 export const TRANSACTION_ABORT = Object.freeze({ reason: "aventara-transaction-abort" });
 export const TRANSACTION_PIPES = "Transaction pipes";
@@ -10,7 +10,7 @@ export function transactionFacts(contract, request, plan) {
     return {
         $contract: contract,
         $origin: request.origin,
-        $args: plan,
+        $args: frozenCopy(plan),
         $requestId: request.requestId,
         ...(request.origin !== "application" && request.transport !== undefined
             ? { $transport: request.transport }
@@ -86,8 +86,11 @@ export async function runTransactionStages(levels, plan, contextOf, runSteps) {
         let pipeIndex = 0;
         for (const level of levels) {
             for (const pipe of level.pipes) {
-                const returned = await pipe(current, contextOf(current));
-                if (returned !== undefined && returned !== current) {
+                const told = frozenCopy(current);
+                const returned = await pipe(told, contextOf(current));
+                if (returned !== undefined &&
+                    returned !== told &&
+                    returned !== current) {
                     const accepted = acceptPlan(current, returned, pipeIndex);
                     if (typeof accepted === "string") {
                         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.3",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
@@ -34,6 +34,7 @@
   "files": [
     "dist",
     "src/runtime/field-check.evaluator.ts",
+    "ERRORS.md",
     "LICENSE-ADDITIONAL-PERMISSION.md",
     "CHANGELOG.md"
   ],
@@ -44,9 +45,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
+    "build": "node ../../scripts/build/build-output.cleaner.ts dist && tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist && node scripts/errors-markdown.generator.ts",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
-    "lint": "biome lint src"
+    "lint": "biome lint src scripts"
   }
 }