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

package/dist/runtime/operation-runtime.js

@@ -3,6 +3,9 @@ import { createComputedFields } from "../config/field-compute.resolver.js";
 import { fieldStagesOf, isForcedOperation, nestedTargetLevels, operationLevels, rawPipelineTree, transactionLevelsOf, } from "../config/pipeline-tree.resolver.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { findOperationAvailabilityIssue, validateOperationArguments, } from "../operations/operation-validator.js";
+import { enforceReadPolicy, } from "../policy/policy-read.runtime.js";
+import { admitRequestPolicy, openRequestPolicy, } from "../policy/policy-request.js";
+import { enforceWritePolicy, writeNeedsTransaction, } from "../policy/policy-write.runtime.js";
 import { transactionInfrastructureFailure } from "../transactions/transaction-response.js";
 import { settleTransaction } from "../transactions/transaction-settlement.runtime.js";
 import { TRANSACTION_PIPES, transactionFacts, } from "../transactions/transaction-stage.runtime.js";
@@ -40,6 +43,16 @@ function scopeOf(request, binding) {
 export function withRequestState(request) {
     return { ...request, state: requestStateOf(request.state) };
 }
+export function withRequestPolicy(dependencies, request, caller, report) {
+    try {
+        const policy = openRequestPolicy(dependencies.config.policy, dependencies.contracts.core, request, caller, dependencies.adapter);
+        return policy === undefined ? request : { ...request, policy };
+    }
+    catch (error) {
+        report(error, "A3000");
+        return internalFailure();
+    }
+}
 export function createPipelineDependencies(dependencies, model) {
     const misuse = createMisuseReporter(dependencies.config.misuse);
     const recordWrites = recordWriteFactsOf({
@@ -170,7 +183,7 @@ function outputAccepted(contract, request, projection, data, report) {
 }
 export function createOperationRuntime(dependencies, pipelineDependencies) {
     const misuse = createMisuseReporter(dependencies.config.misuse);
-    return async (request, report, source) => {
+    return async (request, report, source, caller) => {
         let validated;
         try {
             validated = validateOperation(dependencies, request, source, misuse);
@@ -184,7 +197,10 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
         if (!validated.ok) {
             return validated.response;
         }
-        const stateful = withRequestState(request);
+        const stateful = withRequestPolicy(dependencies, withRequestState(request), caller, report);
+        if (!("state" in stateful)) {
+            return stateful;
+        }
         const forced = isForcedOperation(activeScopeConfig(dependencies.config, request).pipelines, request);
         const admitted = await admitOperation(pipelineDependencies, stateful, validated.contract, validated.arguments, OPERATION_ARGUMENTS_PATH, report, {
             requestId: request.requestId,
@@ -194,8 +210,20 @@ export function createOperationRuntime(dependencies, pipelineDependencies) {
         if (!admitted.ok) {
             return admitted.response;
         }
-        if (forced) {
-            return executeForcedOperation(pipelineDependencies, dependencies.adapter, stateful, validated.contract, admitted.args, report);
+        let checkedWrite = false;
+        if (stateful.policy !== undefined &&
+            request.family !== "find" &&
+            validated.contract.transactions === "interactive" &&
+            !forced) {
+            try {
+                checkedWrite = await writeNeedsTransaction(stateful.policy, dependencies.contracts.core, stateful, () => planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, validated.contract, activeScopeConfig(dependencies.config, request).compute, stateful, admitted.args), admitted.args);
+            }
+            catch (error) {
+                return sanitizeOperationFailure(error, stateful.policy.execution.boundary.originOf(error), report, { path: OPERATION_ARGUMENTS_PATH, arguments: admitted.args });
+            }
+        }
+        if (forced || checkedWrite) {
+            return executeForcedOperation(pipelineDependencies, dependencies.adapter, stateful, validated.contract, admitted.args, report, forced);
         }
         return executeAdmittedOperation(pipelineDependencies, stateful, validated.contract, admitted.args, OPERATION_ARGUMENTS_PATH, { kind: "standalone", executor: dependencies.adapter }, report);
     };
@@ -346,6 +374,12 @@ export async function admitOperation(dependencies, request, contract, args, argu
     if (absent.length > 0) {
         return { ok: false, response: mapValidationOutcome(absent) };
     }
+    if (request.policy !== undefined) {
+        const refused = await admitRequestPolicy(request.policy, dependencies.contracts.core, contract, request, current, report, { path: argumentsPath, arguments: current });
+        if (refused !== undefined) {
+            return { ok: false, response: refused };
+        }
+    }
     try {
         return await admit();
     }
@@ -441,7 +475,7 @@ export async function prepareStep(dependencies, request, contract, args, argumen
         };
     }
 }
-async function executeForcedOperation(dependencies, adapter, request, contract, args, report) {
+async function executeForcedOperation(dependencies, adapter, request, contract, args, report, forced) {
     const plan = [
         {
             resource: request.resource,
@@ -452,7 +486,9 @@ async function executeForcedOperation(dependencies, adapter, request, contract,
     ];
     const settled = await settleTransaction({
         adapter,
-        levels: transactionLevelsOf(activeScopeConfig(dependencies.config, request).pipelines, request.resource),
+        levels: forced
+            ? transactionLevelsOf(activeScopeConfig(dependencies.config, request).pipelines, request.resource)
+            : [],
         plan,
         contextOf: (current, executor) => dependencies.contexts.transaction({
             requestId: request.requestId,
@@ -544,6 +580,25 @@ export async function executeAdmittedOperation(dependencies, request, contract,
             throw hiddenRefusal;
         }
         args = deepFreeze(computed);
+        let policyWrite;
+        if (request.policy !== undefined && request.family !== "find") {
+            const planned = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
+            const plannedArguments = await stripVirtualMutationInput(contracts, request, planned.arguments);
+            try {
+                policyWrite = await enforceWritePolicy(request.policy.on({ executor, boundary: adapterBoundary }), dependencies.contracts.core, dependencies.config.adapter.model, request, planned, plannedArguments, binding.kind === "transaction");
+            }
+            catch (error) {
+                return sanitizeOperationFailure(error, adapterBoundary.originOf(error), report, { path: argumentsPath, arguments: args });
+            }
+            if (policyWrite.kind === "refused") {
+                return policyWrite.response;
+            }
+        }
+        let policyFailure;
+        const refuseWrite = (response) => {
+            policyFailure = response;
+            throw thrownFailure(response);
+        };
         let readMaterialized = false;
         let executedReadPlan;
         const materialize = async (data, plan) => {
@@ -552,24 +607,73 @@ export async function executeAdmittedOperation(dependencies, request, contract,
             return materializeReadOperation(contract, scopeConfig.compute, request, plan, data, computeContext);
         };
         const invoke = async () => {
-            const readPlan = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
-            const adapterArguments = await stripVirtualMutationInput(contracts, request, readPlan.arguments);
-            const identity = request;
-            const adapterData = await adapterBoundary.execute(() => executor.execute({
+            let readPlan = planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args);
+            let adapterArguments = await stripVirtualMutationInput(contracts, request, readPlan.arguments);
+            let operation = request;
+            let settle;
+            let writeMiss;
+            if (policyWrite !== undefined && policyWrite.kind !== "refused") {
+                writeMiss = policyWrite.miss;
+                if (policyWrite.kind === "empty") {
+                    if (writeMiss !== undefined && policyWrite.data === null) {
+                        refuseWrite(await writeMiss());
+                    }
+                    return materialize(policyWrite.data, readPlan);
+                }
+                operation = policyWrite.identity;
+                adapterArguments = policyWrite.arguments;
+                readPlan = policyWrite.plan;
+                settle = policyWrite.settle;
+            }
+            else if (request.policy !== undefined && request.family === "find") {
+                const read = await enforceReadPolicy(request.policy.on({ executor, boundary: adapterBoundary }), dependencies.contracts.core, dependencies.config.adapter.model, request, readPlan, adapterArguments);
+                if (read.kind === "refused") {
+                    throw thrownFailure(read.response);
+                }
+                if (read.kind === "empty") {
+                    const miss = uniqueMissFailure(request, read.data);
+                    if (miss !== undefined) {
+                        throw thrownFailure(miss);
+                    }
+                    return materialize(read.data, readPlan);
+                }
+                operation = read.identity;
+                adapterArguments = read.arguments;
+                readPlan = read.plan;
+                settle = read.settle;
+            }
+            const { policy: _session, ...identity } = operation;
+            let adapterData = await adapterBoundary.execute(() => executor.execute({
                 ...identity,
                 resource: request.resource,
                 arguments: adapterArguments,
             }));
+            if (writeMiss !== undefined && adapterData === null) {
+                refuseWrite(await writeMiss());
+            }
             const miss = uniqueMissFailure(request, adapterData);
             if (miss !== undefined) {
                 throw thrownFailure(miss);
             }
+            if (settle !== undefined) {
+                const settled = await settle(adapterData);
+                if (!settled.ok) {
+                    if (policyWrite !== undefined) {
+                        refuseWrite(settled.response);
+                    }
+                    throw thrownFailure(settled.response);
+                }
+                adapterData = settled.data;
+            }
             return materialize(adapterData, readPlan);
         };
         const materialized = async (data) => readMaterialized
             ? data
             : materialize(data, planReadOperation(dependencies.contracts.core, dependencies.config.adapter.model, contract, scopeConfig.compute, request, args));
         const data = await materialized(await runLevelLifecycle(levels, context, invoke, materialized, reuse, () => new AvInterceptorNextError()));
+        if (policyFailure !== undefined) {
+            return policyFailure;
+        }
         if (!outputAccepted(contract, request, executedReadPlan?.projection, data, report)) {
             return internalFailure();
         }

package/dist/runtime/readonly-value.d.ts

@@ -32,8 +32,12 @@ export declare function deepFreeze<T>(value: T): T;
  * only reads is told — the validated arguments after validation, a result in an
  * after hook — so neither what is written nor the result the caller receives can
  * be changed through it.
+ *
+ * With `snapshot`, a copied container found to hold no `Date` or `Uint8Array`
+ * is remembered as such at once, so a later `frozenCopy` of the copy shares it
+ * without walking it: for a copy that is itself copied again for each stage.
  */
-export declare function frozenCopy<T>(value: T): AvDeepReadonly<T>;
+export declare function frozenCopy<T>(value: T, snapshot?: boolean): AvDeepReadonly<T>;
 /**
  * A read-only view of `value`: reads see the live value, nested plain objects
  * and arrays as views too, and any write, definition or deletion throws a

package/dist/runtime/readonly-value.js

@@ -37,38 +37,79 @@ function scalarCopy(value) {
     return undefined;
 }
 const SCALAR_FREE = new WeakSet();
-export function frozenCopy(value) {
+function scalarFree(value) {
+    return Object.isFrozen(value) && SCALAR_FREE.has(value);
+}
+const WALKING = Symbol("walking");
+function place(target, key, value, enumerable) {
+    if (enumerable && typeof key === "string" && !(key in target)) {
+        target[key] = value;
+        return;
+    }
+    Object.defineProperty(target, key, {
+        value,
+        enumerable,
+        writable: true,
+        configurable: true,
+    });
+}
+export function frozenCopy(value, snapshot = false) {
+    const scalar = scalarCopy(value);
+    if (scalar !== undefined) {
+        return scalar;
+    }
+    if (!isContainer(value) || scalarFree(value)) {
+        return value;
+    }
     const copies = new Map();
-    const walking = new Set();
     let cycled = false;
+    let holdsScalar = false;
     const copy = (current) => {
+        if (current === null || typeof current !== "object") {
+            return current;
+        }
         const scalar = scalarCopy(current);
         if (scalar !== undefined) {
+            holdsScalar = true;
             return scalar;
         }
-        if (!isContainer(current) || SCALAR_FREE.has(current)) {
+        if (!isContainer(current) || scalarFree(current)) {
             return current;
         }
-        if (copies.has(current)) {
-            cycled ||= walking.has(current);
-            return copies.get(current);
+        const known = copies.get(current);
+        if (known === WALKING) {
+            cycled = true;
+            return current;
+        }
+        if (known !== undefined) {
+            holdsScalar ||= !scalarFree(known);
+            return known;
         }
-        copies.set(current, current);
-        walking.add(current);
-        const entries = [];
-        let changed = !DEEP_FROZEN.has(current);
+        copies.set(current, WALKING);
+        const outer = holdsScalar;
+        holdsScalar = false;
+        let changed = !(Object.isFrozen(current) && DEEP_FROZEN.has(current));
+        const array = Array.isArray(current);
+        const prototype = Object.getPrototypeOf(current);
+        const target = array
+            ? new Array(current.length)
+            : prototype === Object.prototype
+                ? {}
+                : Object.create(prototype);
         for (const key of Reflect.ownKeys(current)) {
+            if (array && key === "length") {
+                continue;
+            }
             const descriptor = Object.getOwnPropertyDescriptor(current, key);
-            if (descriptor === undefined ||
-                !("value" in descriptor) ||
-                (Array.isArray(current) && key === "length")) {
+            if (descriptor === undefined || !("value" in descriptor)) {
                 continue;
             }
             const next = copy(descriptor.value);
             changed ||= next !== descriptor.value;
-            entries.push([key, descriptor, next]);
+            place(target, key, next, descriptor.enumerable === true);
         }
-        walking.delete(current);
+        const held = holdsScalar;
+        holdsScalar = outer || held;
         if (!changed) {
             copies.set(current, current);
             if (!cycled) {
@@ -76,20 +117,18 @@ export function frozenCopy(value) {
             }
             return current;
         }
-        const target = Array.isArray(current)
-            ? new Array(current.length)
-            : Object.create(Object.getPrototypeOf(current));
-        for (const [key, descriptor, next] of entries) {
-            Object.defineProperty(target, key, {
-                value: next,
-                enumerable: descriptor.enumerable ?? false,
-                writable: true,
-                configurable: true,
-            });
+        Object.freeze(target);
+        DEEP_FROZEN.add(target);
+        if (cycled) {
+            for (const key of Reflect.ownKeys(target)) {
+                deepFreeze(target[key]);
+            }
+        }
+        if (snapshot && !held && !cycled) {
+            SCALAR_FREE.add(target);
         }
-        const frozen = deepFreeze(target);
-        copies.set(current, frozen);
-        return frozen;
+        copies.set(current, target);
+        return target;
     };
     return copy(value);
 }

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

@@ -1,4 +1,5 @@
 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";
@@ -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: FrameworkTransactionRequest, 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,4 +1,5 @@
 import { transactionLevelsOf } from "../config/pipeline-tree.resolver.js";
+import { openRequestPolicy, } from "../policy/policy-request.js";
 import { AdapterBoundary, planOperationArgumentsPath, planStepPath, sanitizeOperationFailure, } from "../runtime/error-boundary.js";
 import { internalFailure, operationSuccess, } from "../runtime/operation-response.js";
 import { admitOperation, EVERY_FIELD, executeAdmittedOperation, prepareStep, STEP_PIPES, withRequestState, } from "../runtime/operation-runtime.js";
@@ -20,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) {
@@ -79,8 +80,21 @@ function standingReferences(core, operation, args, steps, subject) {
     }
     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 steps = new Map();
+    const stateful = (operation) => {
+        const known = steps.get(operation);
+        if (known !== undefined) {
+            return known;
+        }
+        const policy = openRequestPolicy(runtime.config.policy, runtime.contracts.core, { origin: operation.request.origin, state }, caller, adapter);
+        const step = policy === undefined
+            ? { ...operation.request, state }
+            : { ...operation.request, state, policy };
+        steps.set(operation, step);
+        return step;
+    };
     const admitted = [];
     const standing = [];
     for (const step of plan.operations) {
@@ -90,7 +104,15 @@ async function executeTransactionPlan(adapter, dependencies, request, plan, stat
             continue;
         }
         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 }, {
+        let stepRequest;
+        try {
+            stepRequest = stateful(step);
+        }
+        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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
@@ -45,7 +45,7 @@
     "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 && node scripts/errors-markdown.generator.ts",
+    "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 scripts"