@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

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

@@ -0,0 +1,81 @@
+import type { ResolvedTransactionPipelineConfig } from "../config/pipeline-config.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { ContextFacts } from "../runtime/context-executor.runtime.js";
+import type { DiagnosticsReporter } from "../runtime/diagnostics-reporter.js";
+import { type CallerArgumentsView } from "../runtime/error-boundary.js";
+import type { OperationExecutionRequest } from "../runtime/operation-request.js";
+import type { AvOperationFailureResponse } from "../runtime/operation-response.js";
+import { type RefusedStageOutput } from "../runtime/pipe-output.validator.js";
+import type { AvTransactionContext, AvTransactionStep } from "../runtime/pipeline.js";
+import { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
+/**
+ * The framework-owned rollback request. It is thrown out of the Adapter transaction
+ * callback only after a failure is recorded, and a rejection is recognized as it
+ * solely by identity — never by message, shape or class. It is a control signal,
+ * not a failure, so it never reaches diagnostics.
+ */
+export declare const TRANSACTION_ABORT: Readonly<{
+    readonly reason: "aventara-transaction-abort";
+}>;
+/** One plan step as a transaction stage reads it (the erased {@link AvTransactionStep}). */
+export type TransactionStepView = AvTransactionStep;
+/** The subject a refused transaction pipe output is reported under. */
+export declare const TRANSACTION_PIPES = "Transaction pipes";
+/**
+ * The `$` facts a transaction stage is told: the plan as `$args`, not one
+ * operation (`$operation` is absent).
+ */
+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 = 
+/** Every stage and step ran; the steps' results, as the stages left them. */
+{
+    readonly kind: "ran";
+}
+/** A transaction guard returned `false`: `A4001`. */
+ | {
+    readonly kind: "denied";
+}
+/** A transaction pipe returned something that is not the plan: `A3004`. */
+ | {
+    readonly kind: "refused";
+    readonly refusal: RefusedStageOutput;
+}
+/** A stage or a step threw (the rollback request included). */
+ | {
+    readonly kind: "failed";
+    readonly error: unknown;
+}
+/**
+ * A transaction interceptor broke the stages' contract: it called `next()`
+ * twice (whatever it then did with the refusal). Answered `A3002`, past every
+ * filter, and the transaction rolls back.
+ */
+ | {
+    readonly kind: "broken";
+    readonly error: AvTransactionIntegrityError;
+};
+/**
+ * What the steps see after the stages: the plan, and whether a transaction pipe
+ * 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 = {
+    readonly plan: readonly TransactionStepView[];
+    readonly piped: boolean;
+};
+/**
+ * Each touched Resource's transaction levels, root then overlay, Resources in the
+ * order their first top-level operation step appears. A SQL step touches nothing.
+ */
+export declare function touchedTransactionLevels(plan: readonly TransactionStepView[], levelsOf: (resource: string) => readonly ResolvedTransactionPipelineConfig[]): readonly ResolvedTransactionPipelineConfig[];
+/**
+ * Runs the transaction stages of `levels` around `runSteps`, inside an open
+ * transaction. Never throws: every way the stages can end is the outcome.
+ */
+export declare function runTransactionStages(levels: readonly ResolvedTransactionPipelineConfig[], plan: readonly TransactionStepView[], contextOf: (plan: readonly TransactionStepView[]) => AvTransactionContext, runSteps: (staged: StagedPlan) => Promise<readonly unknown[]>): Promise<TransactionStagesOutcome>;
+/**
+ * An error a transaction stage threw, through the touched Resources' filters in
+ * 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>;

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

@@ -0,0 +1,123 @@
+import { AdapterBoundary, resolveOperationFailure, } from "../runtime/error-boundary.js";
+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 { AvTransactionIntegrityError } from "./transaction-integrity-error.js";
+export const TRANSACTION_ABORT = Object.freeze({ reason: "aventara-transaction-abort" });
+export const TRANSACTION_PIPES = "Transaction pipes";
+export function transactionFacts(contract, request, plan) {
+    return {
+        $contract: contract,
+        $origin: request.origin,
+        $args: plan,
+        $requestId: request.requestId,
+        ...(request.origin !== "application" && request.transport !== undefined
+            ? { $transport: request.transport }
+            : {}),
+    };
+}
+export function touchedTransactionLevels(plan, levelsOf) {
+    const touched = new Set();
+    for (const step of plan) {
+        if (step.resource !== undefined) {
+            touched.add(step.resource);
+        }
+    }
+    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;
+    }
+    if (Array.isArray(left) && Array.isArray(right)) {
+        return (left.length === right.length &&
+            left.every((entry, index) => sameStructure(entry, right[index])));
+    }
+    if (isRecord(left) &&
+        isRecord(right) &&
+        Object.getPrototypeOf(left) === Object.prototype &&
+        Object.getPrototypeOf(right) === Object.prototype) {
+        const keys = Object.keys(left);
+        return (keys.length === Object.keys(right).length &&
+            keys.every((key) => Object.hasOwn(right, key) && sameStructure(left[key], right[key])));
+    }
+    return false;
+}
+function acceptPlan(original, returned, index) {
+    if (!Array.isArray(returned) || returned.length !== original.length) {
+        return `Transaction pipes[${index}] returned a plan that does not keep its ${original.length} step(s)`;
+    }
+    const accepted = [];
+    for (const [position, step] of original.entries()) {
+        const entry = returned[position];
+        if (step.sql !== undefined) {
+            if (!isRecord(entry) || !sameStructure(entry.sql, step.sql)) {
+                return `Transaction pipes[${index}] changed SQL step ${position}`;
+            }
+            accepted.push(step);
+            continue;
+        }
+        if (!isRecord(entry) ||
+            entry.resource !== step.resource ||
+            entry.family !== step.family ||
+            entry.variant !== step.variant) {
+            return `Transaction pipes[${index}] changed which operation step ${position} runs`;
+        }
+        accepted.push({ ...step, args: entry.args });
+    }
+    return accepted;
+}
+export async function runTransactionStages(levels, plan, contextOf, runSteps) {
+    let current = deepFreeze(plan);
+    const reuse = { refusal: undefined };
+    try {
+        for (const level of levels) {
+            for (const guard of level.guards) {
+                if ((await guard(contextOf(current))) === false) {
+                    return { kind: "denied" };
+                }
+            }
+        }
+        let piped = false;
+        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 accepted = acceptPlan(current, returned, pipeIndex);
+                    if (typeof accepted === "string") {
+                        return {
+                            kind: "refused",
+                            refusal: {
+                                response: operationFailure("A3004", {
+                                    message: PIPE_OUTPUT_FAILURE_MESSAGE,
+                                }),
+                                error: new AvPipeOutputError(accepted, []),
+                            },
+                        };
+                    }
+                    current = deepFreeze(accepted);
+                    piped = true;
+                }
+                pipeIndex += 1;
+            }
+        }
+        const staged = { plan: current, piped };
+        await runLevelLifecycle(levels, () => contextOf(current), () => runSteps(staged), async (results) => results, reuse, () => new AvTransactionIntegrityError("next-called-twice"));
+        return reuse.refusal === undefined
+            ? { kind: "ran" }
+            : { kind: "broken", error: reuse.refusal };
+    }
+    catch (error) {
+        return reuse.refusal === undefined
+            ? { kind: "failed", error }
+            : { kind: "broken", error: reuse.refusal };
+    }
+}
+export function resolveTransactionStageFailure(error, levels, context, report, view) {
+    return resolveOperationFailure(error, levels.flatMap((level) => level.filters), context, new AdapterBoundary(), report, view);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "0.1.0-pilot.4",
+  "version": "1.0.0-rc.1",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
@@ -19,17 +19,32 @@
       "types": "./dist/protocol/index.d.ts",
       "import": "./dist/protocol/index.js",
       "default": "./dist/protocol/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "default": "./dist/internal.js"
+    },
+    "./avz": {
+      "types": "./dist/avz/index.d.ts",
+      "import": "./dist/avz/index.js",
+      "default": "./dist/avz/index.js"
     }
   },
   "files": [
     "dist",
-    "LICENSE-ADDITIONAL-PERMISSION.md"
+    "src/runtime/field-check.evaluator.ts",
+    "LICENSE-ADDITIONAL-PERMISSION.md",
+    "CHANGELOG.md"
   ],
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "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",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src"