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

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

@@ -22,7 +22,7 @@ export type AvTransactionReference<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";

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,4 +1,4 @@
-import type { ClientProtocolIdentity } from "../runtime/operation-request.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 = {
@@ -11,29 +11,29 @@ type TransactionRequestBase = {
     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 protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** An AI agent's transaction request, run under the Agent Contract. */
-export type AgentTransactionRequest = TransactionRequestBase & {
+export type AvAgentTransactionRequest = TransactionRequestBase & {
     readonly origin: "agent";
-    readonly protocol: ClientProtocolIdentity;
+    readonly protocol: AvRequestProtocol;
     readonly transport?: AvTransportContext;
 };
 /** One transaction request, as `framework.executeTransaction` takes it. */
-export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest | AgentTransactionRequest;
+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 or agent step — the protocol identity it is
  * accepted with.
  */
-export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "origin"> | Pick<ClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AgentTransactionRequest, "origin" | "protocol" | "transport">;
+export type TransactionOperationOrigin = Pick<AvApplicationTransactionRequest, "origin"> | Pick<AvClientTransactionRequest, "origin" | "protocol" | "transport"> | Pick<AvAgentTransactionRequest, "origin" | "protocol" | "transport">;
 export {};

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

@@ -1,8 +1,9 @@
 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 { 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 { AvTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
 import type { AvTransactionResponse } from "./transaction-response.js";
 /**
  * The transaction executor core. Like the operation executor it owns no
@@ -13,7 +14,9 @@ import type { AvTransactionResponse } 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<AvTransactionResponse>;
+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. The touched Resources' transaction stages and

package/dist/transactions/transaction-runtime.js

@@ -1,16 +1,19 @@
 import { transactionLevelsOf } from "../config/pipeline-tree.resolver.js";
+import { derivePolicyCaller, holdFirstPrincipal, openRequestPolicy, } from "../policy/policy-request.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 = {
@@ -18,13 +21,13 @@ export function createTransactionRuntime(dependencies, pipelineDependencies) {
         cascades: resolveCascadeClosure(adapter.referentialActions),
         sqlStatements: adapter.sqlStatements === true,
     };
-    return async (seeded, diagnostics, origins, planArguments) => {
+    return async (seeded, diagnostics, origins, planArguments, caller) => {
         const request = withRequestState(seeded);
         const validation = await validateTransactionPlan(planDependencies, request, origins, planArguments);
         if (!validation.ok) {
             return validation.response;
         }
-        return executeTransactionPlan(adapter, pipelineDependencies, request, validation.plan, request.state, diagnostics);
+        return executeTransactionPlan(dependencies, pipelineDependencies, request, validation.plan, request.state, diagnostics, caller);
     };
 }
 function planOrigin(request, plan) {
@@ -59,39 +62,108 @@ 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 });
+async function executeTransactionPlan(runtime, dependencies, request, plan, state, diagnostics, caller) {
+    const { adapter } = runtime;
+    const callers = new Map();
+    if (caller !== undefined) {
+        for (const step of plan.operations) {
+            if (step.kind === "operation") {
+                holdFirstPrincipal(runtime.config.policy, {
+                    origin: step.request.origin,
+                    state,
+                });
+            }
+        }
+    }
+    else {
+        for (const step of plan.operations) {
+            if (step.kind === "sql" || callers.has(step.request.origin)) {
+                continue;
+            }
+            try {
+                const derived = derivePolicyCaller(runtime.config.policy, {
+                    origin: step.request.origin,
+                    state,
+                });
+                callers.set(step.request.origin, derived instanceof Promise ? await derived : derived);
+            }
+            catch (error) {
+                diagnostics.operation(step.request, step.index)(error, "A3000");
+                return transactionOperationFailure(internalFailure(), step.index);
+            }
+        }
+    }
+    const steps = new Map();
+    const stateful = (operation) => {
+        const known = steps.get(operation);
+        if (known !== undefined) {
+            return known;
+        }
+        const settle = (policy) => {
+            const step = policy === undefined
+                ? { ...operation.request, state }
+                : { ...operation.request, state, policy };
+            steps.set(operation, step);
+            return step;
+        };
+        const policy = openRequestPolicy(runtime.config.policy, runtime.contracts.core, { origin: operation.request.origin, state }, caller ?? callers.get(operation.request.origin), adapter);
+        return policy instanceof Promise ? policy.then(settle) : settle(policy);
+    };
     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);
+        let stepRequest;
+        try {
+            const opened = stateful(step);
+            stepRequest = opened instanceof Promise ? await opened : opened;
+        }
+        catch (error) {
+            report(error, "A3000");
+            return transactionOperationFailure(internalFailure(), step.index);
+        }
+        const admission = await admitOperation(dependencies, stepRequest, 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);
@@ -101,9 +173,18 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
     const runPlanOperation = async (operation, args, transactionPiped, executor, results, outer) => {
         const report = diagnostics.operation(operation.request, operation.index);
         const argumentsPath = planOperationArgumentsPath(operation.index);
-        const stepRequest = stateful(operation);
+        const opened = stateful(operation);
+        const stepRequest = opened instanceof Promise ? await opened : opened;
         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 +200,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-settlement.runtime.d.ts

@@ -14,9 +14,9 @@ import { type TransactionStepView } from "./transaction-stage.runtime.js";
  * the touched Resources' transaction filters answer it once the transaction
  * interceptors have unwound. Its answer is the step's own outcome.
  */
-export type TransactionStepRunner<M extends AvAdapterModel> = (index: number, step: TransactionStepView, piped: boolean, executor: AvAdapterTransactionExecutor<M>, results: readonly unknown[], outer: OuterFailureLayer) => Promise<AvOperationResponse>;
+type TransactionStepRunner<M extends AvAdapterModel> = (index: number, step: TransactionStepView, piped: boolean, executor: AvAdapterTransactionExecutor<M>, results: readonly unknown[], outer: OuterFailureLayer) => Promise<AvOperationResponse>;
 /** How one transaction settled. */
-export type TransactionSettlement = 
+type TransactionSettlement = 
 /** Committed: every step's own outcome, in plan order. */
 {
     readonly kind: "committed";
@@ -34,7 +34,7 @@ export type TransactionSettlement =
     readonly error: unknown;
     readonly operation: number | undefined;
 };
-export type TransactionSettlementInput<M extends AvAdapterModel> = {
+type TransactionSettlementInput<M extends AvAdapterModel> = {
     readonly adapter: AvAdapter<M>;
     /** The touched Resources' transaction levels, outer to inner. */
     readonly levels: readonly ResolvedTransactionPipelineConfig[];
@@ -49,3 +49,4 @@ export type TransactionSettlementInput<M extends AvAdapterModel> = {
 };
 /** Runs `plan` inside one Adapter transaction, its stages around its steps, and settles it. */
 export declare function settleTransaction<M extends AvAdapterModel>(input: TransactionSettlementInput<M>): Promise<TransactionSettlement>;
+export {};

package/dist/transactions/transaction-slot-path-error.js

@@ -1,3 +1,4 @@
+import { brandCoreClass } from "../runtime/core-class.brand.js";
 const TRANSACTION_SLOT_PATH_MESSAGES = {
     "slot-prefix": "Transaction slot path does not name a member below the operation's arguments.",
     "absent-member": "Transaction slot path names an absent member of the operation arguments.",
@@ -11,3 +12,4 @@ export class AvTransactionSlotPathError extends Error {
         this.violation = violation;
     }
 }
+brandCoreClass(AvTransactionSlotPathError, "AvTransactionSlotPathError");

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

@@ -23,11 +23,12 @@ 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. */
-export type TransactionStagesOutcome = 
+type TransactionStagesOutcome = 
 /** Every stage and step ran; the steps' results, as the stages left them. */
 {
     readonly kind: "ran";
@@ -60,7 +61,7 @@ export type TransactionStagesOutcome =
  * changed it, in which case every operation step's arguments are held to the
  * server's rules and its validators again before it runs.
  */
-export type StagedPlan = {
+type StagedPlan = {
     readonly plan: readonly TransactionStepView[];
     readonly piped: boolean;
 };
@@ -79,3 +80,4 @@ export declare function runTransactionStages(levels: readonly ResolvedTransactio
  * exact reverse (the first that handles it wins), then final sanitization.
  */
 export declare function resolveTransactionStageFailure(error: unknown, levels: readonly ResolvedTransactionPipelineConfig[], context: AvTransactionContext, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<AvOperationFailureResponse>;
+export {};

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

@@ -2,7 +2,8 @@ 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 { isRecord } from "../runtime/record.guard.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 +11,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 }
@@ -26,9 +27,6 @@ export function touchedTransactionLevels(plan, levelsOf) {
     }
     return [...touched].flatMap((resource) => levelsOf(resource));
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function sameStructure(left, right) {
     if (Object.is(left, right)) {
         return true;
@@ -86,8 +84,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,11 +1,11 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.11",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
   "engines": {
-    "node": "^22.18.0 || >=24.2.0"
+    "node": "^22.23.4 || >=24.22.1"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,19 +34,20 @@
   "files": [
     "dist",
     "src/runtime/field-check.evaluator.ts",
+    "ERRORS.md",
     "LICENSE-ADDITIONAL-PERMISSION.md",
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "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 && node scripts/core-version.generator.ts && 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"
   }
 }

package/src/runtime/field-check.evaluator.ts

@@ -712,7 +712,7 @@ export function entryCheckIssues(
 }
 
 /** Whether a check judges a list's own length (`AvZ.minItems`/`AvZ.maxItems`). */
-export function isListCheck(check: AvFieldCheck): boolean {
+function isListCheck(check: AvFieldCheck): boolean {
 	return (
 		(check.check === "max_length" || check.check === "min_length") &&
 		check.list === true