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

package/dist/runtime/operation-runtime.js

@@ -1,38 +1,146 @@
+import { hasFieldValidators } from "../compiler/field-validator.compiler.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 { transactionInfrastructureFailure } from "../transactions/transaction-response.js";
+import { settleTransaction } from "../transactions/transaction-settlement.runtime.js";
+import { TRANSACTION_PIPES, transactionFacts, } from "../transactions/transaction-stage.runtime.js";
 import { copyAtDoor, misuseIdentityOf, refuseCallerData, } from "./caller-data.door.js";
 import { materializeReadOperation, planReadOperation, } from "./computed-read-runtime.js";
+import { createContextExecutor, } from "./context-executor.runtime.js";
 import { createRequirementIssues, recordWriteFactsOf, } from "./create-requirement.js";
+import { createDiagnosticsReporter, } from "./diagnostics-reporter.js";
 import { AdapterBoundary, OPERATION_ARGUMENTS_PATH, resolveOperationFailure, sanitizeOperationFailure, } from "./error-boundary.js";
+import { planFieldStages } from "./field-stage.plan.js";
+import { guardSentFields, pipeSentFields, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
+import { fieldValidatorIssues } from "./field-validator.runtime.js";
+import { thrownFailure } from "./framework-error.factory.js";
+import { AvInterceptorNextError } from "./interceptor-next.error.js";
+import { runLevelLifecycle, } from "./level-lifecycle.runtime.js";
 import { createMisuseReporter, } from "./misuse-reporter.js";
-import { applyWriteFieldBehaviors, stripVirtualMutationInput, } from "./mutation-planner.js";
+import { applyNestedWriteCompute, applyWriteCompute, stripVirtualMutationInput, } from "./mutation-planner.js";
+import { nestedWriteTargetsOf, } from "./nested-write.walker.js";
 import { internalFailure, operationFailure } from "./operation-response.js";
-import { mapOperationOutcome, mapValidationOutcome } from "./outcome-mapper.js";
-import { OutputValidationError, validateOperationOutput, } from "./output-validator.js";
-import { refusePipeOutput } from "./pipe-output.validator.js";
+import { mapOperationOutcome, mapValidationOutcome, uniqueMissFailure, } from "./outcome-mapper.js";
+import { AvOutputValidationError, validateOperationOutput, } from "./output-validator.js";
+import { refusePipeOutput, refuseStageOutput, } from "./pipe-output.validator.js";
+import { deepFreeze, frozenCopy } from "./readonly-value.js";
+import { requestStateOf } from "./request-state.resolver.js";
 import { normalizeOperationScalarValues, } from "./scalar-runtime.js";
+function scopeOf(request, binding) {
+    return {
+        requestId: request.requestId,
+        transaction: binding?.kind === "transaction" ? binding.executor : undefined,
+        state: request.state,
+    };
+}
+export function withRequestState(request) {
+    return { ...request, state: requestStateOf(request.state) };
+}
+export function createPipelineDependencies(dependencies, model) {
+    const misuse = createMisuseReporter(dependencies.config.misuse);
+    const recordWrites = recordWriteFactsOf(dependencies.adapter);
+    const contexts = createContextExecutor({
+        model,
+        adapter: dependencies.adapter,
+        application: dependencies.contracts.application,
+        diagnostics: dependencies.config.diagnostics,
+        misuse,
+        run: (request, transaction) => executeContextCall(raw, dependencies, request, transaction, misuse),
+    });
+    const { contracts, config } = dependencies;
+    const pipeline = {
+        contracts,
+        config,
+        recordWrites,
+        contexts,
+        fieldStages: {
+            application: planFieldStages(config.application.pipelines, contracts.application),
+            client: planFieldStages(config.client.pipelines, contracts.client),
+            agent: planFieldStages(config.agent.pipelines, contracts.agent),
+        },
+    };
+    const rawTree = rawPipelineTree(config.application.pipelines);
+    const raw = {
+        ...pipeline,
+        config: {
+            ...config,
+            application: { ...config.application, pipelines: rawTree },
+        },
+        fieldStages: {
+            ...pipeline.fieldStages,
+            application: planFieldStages(rawTree, contracts.application),
+        },
+    };
+    return pipeline;
+}
+async function executeContextCall(raw, dependencies, request, transaction, misuse) {
+    const report = createDiagnosticsReporter(dependencies.config.diagnostics, request);
+    try {
+        let validated;
+        try {
+            validated = validateOperation(dependencies, request, "caller", misuse);
+        }
+        catch (error) {
+            return sanitizeOperationFailure(error, "runtime", report, {
+                path: OPERATION_ARGUMENTS_PATH,
+                arguments: request.arguments,
+            });
+        }
+        if (!validated.ok) {
+            return validated.response;
+        }
+        const stateful = withRequestState(request);
+        const admitted = await admitOperation(raw, stateful, validated.contract, validated.arguments, OPERATION_ARGUMENTS_PATH, report, {
+            requestId: request.requestId,
+            transaction,
+            state: stateful.state,
+        });
+        if (!admitted.ok) {
+            return admitted.response;
+        }
+        return await executeAdmittedOperation(raw, stateful, validated.contract, admitted.args, OPERATION_ARGUMENTS_PATH, transaction === undefined
+            ? { kind: "standalone", executor: dependencies.adapter }
+            : { kind: "transaction", executor: transaction }, report);
+    }
+    catch (error) {
+        report(error, "A3000");
+        return internalFailure();
+    }
+}
 export function activeContract(contracts, request) {
-    return request.origin === "application"
-        ? contracts.application
-        : contracts.client;
+    return contracts[request.origin];
 }
 function activeScopeConfig(config, request) {
-    return request.origin === "application" ? config.application : config.client;
+    return config[request.origin];
 }
-function pipelineContext(contract, request, args) {
+function operationFacts(contract, request, args) {
     return {
-        contract,
-        origin: request.origin,
-        resource: request.resource,
-        family: request.family,
-        variant: request.variant,
-        args,
-        requestId: request.requestId,
-        ...(request.origin === "client" && request.transport !== undefined
-            ? { transport: request.transport }
+        $operation: {
+            resource: request.resource,
+            family: request.family,
+            variant: request.variant,
+        },
+        $args: args,
+        $origin: request.origin,
+        $requestId: request.requestId,
+        $contract: contract,
+        ...(request.origin !== "application" && request.transport !== undefined
+            ? { $transport: request.transport }
             : {}),
     };
 }
+function nestedFacts(contract, request, target, payload) {
+    return {
+        ...operationFacts(contract, request, payload),
+        $operation: {
+            resource: target.resource,
+            family: target.family,
+            variant: "one",
+            nested: true,
+        },
+    };
+}
 function forbidden() {
     return operationFailure("A4001", {
         message: "Operation denied by a framework guard.",
@@ -48,16 +156,11 @@ function outputAccepted(contract, request, projection, data, report) {
         return false;
     }
     if (!validation.ok) {
-        report(new OutputValidationError(request, validation.issues), "A3000");
+        report(new AvOutputValidationError(request, validation.issues), "A3000");
     }
     return validation.ok;
 }
-export function createOperationRuntime(dependencies) {
-    const pipelineDependencies = {
-        contracts: dependencies.contracts,
-        config: dependencies.config,
-        recordWrites: recordWriteFactsOf(dependencies.adapter),
-    };
+export function createOperationRuntime(dependencies, pipelineDependencies) {
     const misuse = createMisuseReporter(dependencies.config.misuse);
     return async (request, report, source) => {
         let validated;
@@ -73,7 +176,19 @@ export function createOperationRuntime(dependencies) {
         if (!validated.ok) {
             return validated.response;
         }
-        return executeValidatedOperation(pipelineDependencies, request, validated.contract, validated.arguments, OPERATION_ARGUMENTS_PATH, dependencies.adapter, report);
+        const stateful = withRequestState(request);
+        const admitted = await admitOperation(pipelineDependencies, stateful, validated.contract, validated.arguments, OPERATION_ARGUMENTS_PATH, report, {
+            requestId: request.requestId,
+            transaction: undefined,
+            state: stateful.state,
+        });
+        if (!admitted.ok) {
+            return admitted.response;
+        }
+        if (isForcedOperation(activeScopeConfig(dependencies.config, request).pipelines, request)) {
+            return executeForcedOperation(pipelineDependencies, dependencies.adapter, stateful, validated.contract, admitted.args, report);
+        }
+        return executeAdmittedOperation(pipelineDependencies, stateful, validated.contract, admitted.args, OPERATION_ARGUMENTS_PATH, { kind: "standalone", executor: dependencies.adapter }, report);
     };
 }
 function validateOperation(dependencies, request, source, misuse) {
@@ -100,19 +215,21 @@ function validateOperation(dependencies, request, source, misuse) {
     return { ok: true, contract, arguments: validation.arguments };
 }
 export function validateProtocolIdentity(contracts, request) {
-    return request.origin === "client"
-        ? protocolIdentityFailure(contracts, request.protocol)
-        : undefined;
+    return request.origin === "application"
+        ? undefined
+        : protocolIdentityFailure(contracts, request.protocol, request.origin);
 }
-export function protocolIdentityFailure(contracts, protocol) {
+export function protocolIdentityFailure(contracts, protocol, origin) {
     if (protocol.version !== AVENTARA_PROTOCOL_VERSION) {
         return operationFailure("A2006", {
             message: "Aventara protocol version does not match the server.",
         });
     }
-    if (protocol.hash !== contracts.client.protocol.hash) {
+    if (protocol.hash !== contracts[origin].protocol.hash) {
         return operationFailure("A2005", {
-            message: "Generated client contract does not match the server. Regenerate the client.",
+            message: origin === "client"
+                ? "Generated client contract does not match the server. Regenerate the client."
+                : "Agent contract does not match the server. Rebuild the agent's tools from the current Agent Contract.",
         });
     }
     return undefined;
@@ -133,76 +250,280 @@ export function validateOperationRequest(contract, request, options, write = "co
 function rejected(response) {
     return { ok: false, response };
 }
-export async function executeValidatedOperation(dependencies, request, contract, validatedArguments, argumentsPath, executor, report) {
-    const scopeConfig = activeScopeConfig(dependencies.config, request);
-    const pipelines = scopeConfig.pipelines;
-    const adapterBoundary = new AdapterBoundary();
-    let args = validatedArguments;
+const FIELD_PIPES = "Field pipes";
+const STEP_PIPES = "Pipes";
+export const EVERY_FIELD = () => true;
+function filtersOf(levels) {
+    return levels.flatMap((level) => level.filters);
+}
+const SINGLE_CALL = { select: EVERY_FIELD };
+export async function admitOperation(dependencies, request, contract, args, argumentsPath, report, scope, admission = SINGLE_CALL) {
+    const contexts = dependencies.contexts;
+    const tree = activeScopeConfig(dependencies.config, request).pipelines;
+    const levels = operationLevels(tree, request);
+    const planned = dependencies.fieldStages[request.origin];
+    const guarded = planned.guarded(request.resource);
+    const contracts = { core: dependencies.contracts.core, active: contract };
+    let current = deepFreeze(args);
+    const context = () => contexts.operation(scope, operationFacts(contract, request, current));
+    const admit = async () => {
+        for (const level of levels) {
+            for (const guard of level.guards) {
+                if ((await guard(context())) === false) {
+                    return { ok: false, response: forbidden() };
+                }
+            }
+        }
+        if (guarded.length > 0 &&
+            !(await guardSentFields(fieldStagesOf(tree, request.resource), guarded, writeRecordPathsOf(request.family, current), current, context))) {
+            return { ok: false, response: forbidden() };
+        }
+        for (const target of planned.nestedGuards
+            ? nestedWriteTargetsOf(contract, dependencies.recordWrites.references, request, current)
+            : []) {
+            const told = () => contexts.operation(scope, nestedFacts(contract, request, target, valueAt(current, target.path)));
+            for (const level of nestedTargetLevels(tree, target.resource, target.family)) {
+                for (const guard of level.guards) {
+                    if ((await guard(told())) === false) {
+                        return { ok: false, response: forbidden() };
+                    }
+                }
+            }
+            const targetGuarded = planned.guarded(target.resource);
+            if (targetGuarded.length > 0 &&
+                !(await guardSentFields(fieldStagesOf(tree, target.resource), targetGuarded, target.records.map((site) => site.path), current, told))) {
+                return { ok: false, response: forbidden() };
+            }
+        }
+        let piped = false;
+        let pipeIndex = 0;
+        for (const level of levels) {
+            for (const pipe of level.pipes) {
+                const returned = await pipe(current, context());
+                if (returned !== undefined && returned !== current) {
+                    const refused = refusePipeOutput(contracts, request, returned, pipe, pipeIndex, admission.validation);
+                    if (refused !== undefined) {
+                        report(refused.error, "A3004");
+                        return { ok: false, response: refused.response };
+                    }
+                    current = deepFreeze(returned);
+                    piped = true;
+                }
+                pipeIndex += 1;
+            }
+        }
+        const fields = await runFieldInputStages(dependencies, request, contract, current, argumentsPath, report, admission);
+        if (!fields.ok) {
+            return fields;
+        }
+        return {
+            ok: true,
+            args: deepFreeze(fields.args),
+            piped: piped || fields.piped,
+        };
+    };
     try {
-        return await runLifecycle();
+        return await admit();
     }
     catch (error) {
-        return resolveOperationFailure(error, pipelines.filters, pipelineContext(contract, request, args), adapterBoundary, report, { path: argumentsPath, arguments: args });
+        return {
+            ok: false,
+            response: await resolveOperationFailure(error, filtersOf(levels), context(), new AdapterBoundary(), report, { path: argumentsPath, arguments: current }),
+        };
     }
-    async function runLifecycle() {
-        for (const guard of pipelines.guards) {
-            const allowed = await guard(pipelineContext(contract, request, args));
-            if (allowed === false) {
-                return forbidden();
+}
+async function runFieldInputStages(dependencies, request, contract, args, argumentsPath, report, admission) {
+    const tree = activeScopeConfig(dependencies.config, request).pipelines;
+    const planned = dependencies.fieldStages[request.origin];
+    const pipes = planned.anyPipes;
+    if (!pipes && !hasFieldValidators(contract)) {
+        return { ok: true, args, piped: false };
+    }
+    let current = args;
+    let changed = false;
+    if (pipes) {
+        const pipedFields = planned.piped(request.resource);
+        let piped = pipedFields.length === 0
+            ? { args: current, changed: false }
+            : await pipeSentFields(fieldStagesOf(tree, request.resource), pipedFields, writeRecordPathsOf(request.family, current), current, admission.select);
+        changed = piped.changed;
+        for (const target of nestedWriteTargetsOf(contract, dependencies.recordWrites.references, request, piped.args)) {
+            const targetPiped = planned.piped(target.resource);
+            if (targetPiped.length === 0) {
+                continue;
             }
+            piped = await pipeSentFields(fieldStagesOf(tree, target.resource), targetPiped, target.records.map((site) => site.path), piped.args, admission.select);
+            changed ||= piped.changed;
         }
-        for (const [index, pipe] of pipelines.pipes.entries()) {
-            const nextArgs = await pipe(args, pipelineContext(contract, request, args));
-            if (nextArgs !== undefined) {
-                args = nextArgs;
+        current = piped.args;
+        if (changed) {
+            const refused = refuseStageOutput({ core: dependencies.contracts.core, active: contract }, request, current, FIELD_PIPES, admission.validation);
+            if (refused !== undefined) {
+                report(refused.error, "A3004");
+                return { ok: false, response: refused.response };
             }
-            const refused = refusePipeOutput({ core: dependencies.contracts.core, active: contract }, request, args, pipe, index);
+        }
+    }
+    const broken = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, current, argumentsPath, admission.select);
+    if (broken.length > 0) {
+        return { ok: false, response: mapValidationOutcome(broken) };
+    }
+    return { ok: true, args: current, piped: changed };
+}
+export async function prepareStep(dependencies, request, contract, args, argumentsPath, report, executor, changes, outer) {
+    let current = deepFreeze(args);
+    const scope = {
+        requestId: request.requestId,
+        transaction: executor,
+        state: request.state,
+    };
+    try {
+        const resolved = await runFieldInputStages(dependencies, request, contract, current, argumentsPath, report, { select: changes.written });
+        if (!resolved.ok) {
+            return resolved;
+        }
+        current = resolved.args;
+        const subject = changes.transactionPiped
+            ? TRANSACTION_PIPES
+            : changes.pipedAroundReferences
+                ? STEP_PIPES
+                : undefined;
+        if (subject !== undefined) {
+            const refused = refuseStageOutput({ core: dependencies.contracts.core, active: contract }, request, current, subject);
             if (refused !== undefined) {
                 report(refused.error, "A3004");
-                return refused.response;
+                return { ok: false, response: refused.response };
+            }
+        }
+        if (changes.transactionPiped) {
+            const broken = fieldValidatorIssues(contract, dependencies.recordWrites.references, request, current, argumentsPath, EVERY_FIELD);
+            if (broken.length > 0) {
+                return { ok: false, response: mapValidationOutcome(broken) };
+            }
+        }
+        return { ok: true, args: deepFreeze(current), piped: resolved.piped };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            response: await resolveOperationFailure(error, filtersOf(operationLevels(activeScopeConfig(dependencies.config, request).pipelines, request)), dependencies.contexts.operation(scope, operationFacts(contract, request, current)), new AdapterBoundary(), report, { path: argumentsPath, arguments: current }, outer),
+        };
+    }
+}
+async function executeForcedOperation(dependencies, adapter, request, contract, args, report) {
+    const plan = [
+        {
+            resource: request.resource,
+            family: request.family,
+            variant: request.variant,
+            args,
+        },
+    ];
+    const settled = await settleTransaction({
+        adapter,
+        levels: transactionLevelsOf(activeScopeConfig(dependencies.config, request).pipelines, request.resource),
+        plan,
+        contextOf: (current, executor) => dependencies.contexts.transaction({
+            requestId: request.requestId,
+            transaction: executor,
+            state: request.state,
+        }, transactionFacts(contract, request, current)),
+        failureView: { path: OPERATION_ARGUMENTS_PATH, arguments: args },
+        report,
+        runStep: async (_index, step, piped, executor, _results, outer) => {
+            let stepArguments = step.args;
+            if (piped) {
+                const prepared = await prepareStep(dependencies, request, contract, stepArguments, OPERATION_ARGUMENTS_PATH, report, executor, {
+                    written: () => false,
+                    transactionPiped: true,
+                    pipedAroundReferences: false,
+                }, outer);
+                if (!prepared.ok) {
+                    return prepared.response;
+                }
+                stepArguments = prepared.args;
             }
+            return executeAdmittedOperation(dependencies, request, contract, stepArguments, OPERATION_ARGUMENTS_PATH, { kind: "transaction", executor, outer }, report);
+        },
+    });
+    switch (settled.kind) {
+        case "committed":
+            return settled.responses[0] ?? internalFailure();
+        case "rolled-back":
+            return settled.response;
+        case "broken":
+            report(settled.error, "A3002");
+            return transactionInfrastructureFailure();
+    }
+}
+export async function executeAdmittedOperation(dependencies, request, contract, admittedArguments, argumentsPath, binding, report) {
+    const { executor } = binding;
+    const scope = scopeOf(request, binding);
+    const contexts = dependencies.contexts;
+    const scopeConfig = activeScopeConfig(dependencies.config, request);
+    const levels = operationLevels(scopeConfig.pipelines, request);
+    const adapterBoundary = new AdapterBoundary();
+    const contracts = { core: dependencies.contracts.core, active: contract };
+    let args = deepFreeze(admittedArguments);
+    let told;
+    const view = () => {
+        if (told === undefined || told.of !== args) {
+            told = { of: args, view: frozenCopy(args) };
         }
-        args = await applyWriteFieldBehaviors({ core: dependencies.contracts.core, active: contract }, scopeConfig.behaviors, request, args, () => pipelineContext(contract, request, args));
-        const missing = createRequirementIssues(contract, dependencies.recordWrites, request, args, argumentsPath);
+        return told.view;
+    };
+    const context = () => contexts.operation(scope, operationFacts(contract, request, view()));
+    const computeContext = () => contexts.compute(scope, operationFacts(contract, request, view()));
+    const reuse = { refusal: undefined };
+    const refusedReuse = (refusal) => {
+        report(refusal, "A3000");
+        return internalFailure();
+    };
+    let response;
+    try {
+        response = await runLifecycle();
+    }
+    catch (error) {
+        if (reuse.refusal !== undefined) {
+            return refusedReuse(reuse.refusal);
+        }
+        return resolveOperationFailure(error, filtersOf(levels), context(), adapterBoundary, report, { path: argumentsPath, arguments: args }, binding.kind === "transaction" ? binding.outer : undefined);
+    }
+    return reuse.refusal === undefined ? response : refusedReuse(reuse.refusal);
+    async function runLifecycle() {
+        let computed = await applyWriteCompute(contracts, scopeConfig.compute, request, args, computeContext);
+        computed = await applyNestedWriteCompute(contracts, scopeConfig.compute, computed, nestedWriteTargetsOf(contract, dependencies.recordWrites.references, request, computed), (target, payload) => contexts.compute(scope, nestedFacts(contract, request, target, payload)));
+        const missing = createRequirementIssues(contract, dependencies.recordWrites, request, computed, argumentsPath);
         if (missing.length > 0) {
             return mapValidationOutcome(missing);
         }
-        for (const hook of pipelines.hooks.before) {
-            await hook(pipelineContext(contract, request, args));
-        }
+        args = deepFreeze(computed);
         let readMaterialized = false;
         let executedReadPlan;
         const materialize = async (data, plan) => {
             readMaterialized = true;
             executedReadPlan = plan;
-            return materializeReadOperation(contract, scopeConfig.behaviors, request, plan, data, () => pipelineContext(contract, request, args));
+            return materializeReadOperation(contract, scopeConfig.compute, request, plan, data, computeContext);
         };
-        let invoke = async () => {
-            const readPlan = planReadOperation(dependencies.contracts.core, contract, scopeConfig.behaviors, request, args);
-            const adapterArguments = await stripVirtualMutationInput({ core: dependencies.contracts.core, active: contract }, request, readPlan.arguments);
+        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({
                 ...identity,
                 resource: request.resource,
                 arguments: adapterArguments,
             }));
+            const miss = uniqueMissFailure(request, adapterData);
+            if (miss !== undefined) {
+                throw thrownFailure(miss);
+            }
             return materialize(adapterData, readPlan);
         };
-        for (let index = pipelines.interceptors.length - 1; index >= 0; index -= 1) {
-            const interceptor = pipelines.interceptors[index];
-            if (interceptor === undefined) {
-                continue;
-            }
-            const next = invoke;
-            invoke = () => interceptor(pipelineContext(contract, request, args), next);
-        }
-        let data = await invoke();
-        if (!readMaterialized) {
-            data = await materialize(data, planReadOperation(dependencies.contracts.core, contract, scopeConfig.behaviors, request, args));
-        }
-        for (const hook of pipelines.hooks.after) {
-            await hook(data, pipelineContext(contract, request, args));
-        }
+        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 (!outputAccepted(contract, request, executedReadPlan?.projection, data, report)) {
             return internalFailure();
         }

package/dist/runtime/outcome-mapper.d.ts

@@ -1,11 +1,22 @@
-import type { OperationIdentity } from "../operations/operation-identity.js";
-import type { ValidationIssue } from "../operations/validation-code.js";
-import type { OperationFailureResponse, OperationResponse } from "./operation-response.js";
+import type { AvOperationIdentity } from "../operations/operation-identity.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import type { AvOperationFailureResponse, AvOperationResponse } from "./operation-response.js";
+/**
+ * The failure a strict unique operation's miss raises inside the pipeline, or
+ * `undefined` when `data` is a row, or the variant answers a miss with `null`.
+ */
+export declare function uniqueMissFailure(operation: AvOperationIdentity, data: unknown): AvOperationFailureResponse | undefined;
 /**
  * Maps one validated operation result to its stable outcome envelope. The
  * result must already have passed output validation, so `null` can only
  * reach a variant whose cardinality admits it.
  */
-export declare function mapOperationOutcome(operation: OperationIdentity, data: unknown): OperationResponse;
+export declare function mapOperationOutcome(operation: AvOperationIdentity, data: unknown): AvOperationResponse;
+/** The A-codes a set of Framework Validation Layer issues can roll up to. */
+export type ValidationOutcomeCode = "A2001" | "A2002" | "A2004" | "A2007" | "A2009";
+/** The framework's top-level `cause.message` for each validation outcome code. */
+export declare const VALIDATION_OUTCOME_MESSAGES: {
+    readonly [K in ValidationOutcomeCode]: string;
+};
 /** Maps framework validation issues to their stable failure envelope. */
-export declare function mapValidationOutcome(issues: readonly ValidationIssue[]): OperationFailureResponse;
+export declare function mapValidationOutcome(issues: readonly AvValidationIssue[]): AvOperationFailureResponse;

package/dist/runtime/outcome-mapper.js

@@ -21,18 +21,26 @@ function outcomeRule(operation) {
     const table = OUTCOME_TABLE;
     return table[`${operation.family}.${operation.variant}`];
 }
+function notFound() {
+    return operationFailure("A2003", {
+        message: "No record matched the unique selector.",
+    });
+}
 function absenceOutcome(absence) {
     switch (absence) {
         case "no-match":
             return operationNoMatch();
         case "not-found":
-            return operationFailure("A2003", {
-                message: "No record matched the unique selector.",
-            });
+            return notFound();
         case undefined:
             return internalFailure();
     }
 }
+export function uniqueMissFailure(operation, data) {
+    return data === null && outcomeRule(operation)?.absence === "not-found"
+        ? notFound()
+        : undefined;
+}
 export function mapOperationOutcome(operation, data) {
     const rule = outcomeRule(operation);
     if (rule === undefined) {
@@ -52,6 +60,13 @@ function namesUnavailableOperation(issue) {
     const head = stepRelativeHead(issue);
     return issue.code === "V1006" && (head === "family" || head === "variant");
 }
+export const VALIDATION_OUTCOME_MESSAGES = {
+    A2001: "The requested Resource is not available.",
+    A2002: "The requested operation is not available on this Resource.",
+    A2004: "Operation arguments failed framework validation.",
+    A2007: "Operation arguments failed framework validation.",
+    A2009: "Operation arguments failed framework validation.",
+};
 function validationCode(issues) {
     if (issues.some((issue) => issue.code !== "V1019" && stepRelativeHead(issue) === "resource")) {
         return "A2001";
@@ -68,14 +83,16 @@ function validationCode(issues) {
     }
     if (issues.some((issue) => issue.code === "V1013" ||
         issue.code === "V1014" ||
-        issue.code === "V1015")) {
+        issue.code === "V1015" ||
+        issue.code === "V1021")) {
         return "A2009";
     }
     return "A2004";
 }
 export function mapValidationOutcome(issues) {
-    return operationFailure(validationCode(issues), {
-        message: "Operation arguments failed framework validation.",
+    const code = validationCode(issues);
+    return operationFailure(code, {
+        message: VALIDATION_OUTCOME_MESSAGES[code],
         issues,
     });
 }