@aventara/core 0.1.0-pilot.3 → 1.0.0-rc.0

package/dist/transactions/deferred-operation.d.ts

@@ -3,6 +3,7 @@ import type { ExecutionOptions } from "../runtime/execution-options.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
 import type { TransactionReference } from "./transaction-reference.js";
 import type { TransactionCommittedResponse } from "./transaction-response.js";
+/** An operation fingerprint: `fp1:` and a hash of the operation and its arguments. */
 export type OperationFingerprint = `fp1:${string}`;
 /** One serializable transaction-plan operation node. */
 export type DeferredOperation = OperationIdentity & {
@@ -10,36 +11,28 @@ export type DeferredOperation = OperationIdentity & {
     readonly args: unknown;
     readonly fingerprint: OperationFingerprint;
 };
+/** A transaction plan: its operations, in the order they run. */
 export type TransactionPlan = {
     readonly operations: readonly DeferredOperation[];
 };
 declare const OPERATION_RESULT: unique symbol;
 declare const OPERATION_HANDLE: unique symbol;
-/**
- * Standard-library shapes that are objects but never a projected result row.
- * `ArrayBufferView` is TypeScript's shared structural base for every typed array
- * and `DataView`, so no constructor is enumerated and the declaration stays
- * portable ES2022 with no runtime dependency.
- */
+/** Standard-library shapes that are objects but never a projected result row. */
 export type BuiltinNonRow = Date | RegExp | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | PromiseLike<unknown> | ArrayBufferView;
 /**
- * The single row behind a supplied result type, or `never` when the result is
- * not one referenceable row. Declaration-only: arrays, functions, the
- * `BuiltinNonRow` shapes, non-objects, and objects without a string key are
- * excluded without any `instanceof` test or `Record<string, unknown>` gate,
- * which ordinary interfaces would fail.
+ * The single row behind a result type, or `never` when the result is not one
+ * referenceable row.
  */
 export type SingleRowResult<T> = NonNullable<T> extends readonly unknown[] ? never : NonNullable<T> extends (...args: never[]) => unknown ? never : NonNullable<T> extends BuiltinNonRow ? never : NonNullable<T> extends object ? Extract<keyof NonNullable<T>, string> extends never ? never : NonNullable<T> : never;
 /** The field names a result row can be referenced by. */
 export type ReferenceableField<T> = Extract<keyof SingleRowResult<T>, string>;
+/** Builds a `$ref` to one field of this handle's row, typed as that field. */
 export type ReferenceBuilder<T> = <F extends ReferenceableField<T>>(field: F) => TransactionReference<SingleRowResult<T>[F]>;
 /** Contributes `$ref` only where the result is a referenceable single row. */
 export type OperationReferenceSurface<T> = [SingleRowResult<T>] extends [never] ? {} : {
     readonly $ref: ReferenceBuilder<T>;
 };
-/**
- * An opaque deferred-operation handle.
- */
+/** An opaque deferred-operation handle. */
 export type Operation<T> = {
     readonly [OPERATION_HANDLE]: true;
     readonly [OPERATION_RESULT]?: T;
@@ -49,13 +42,9 @@ export type TransactionResults<Ops extends readonly Operation<unknown>[]> = {
     readonly [I in keyof Ops]: Ops[I] extends Operation<infer R> ? R : never;
 };
 /**
- * The one typed transaction runner — `framework.transaction`'s own type. It infers
- * the handle tuple without `as const` at the call site, and resolves what the
- * runtime answers: the committed envelope (`A1009`) with each handle's result in
- * plan order, or the failure response. Never the bare result tuple.
- *
- * The second argument is the run's `ExecutionOptions`: its `requestId` is every
- * step's, under either origin. A handle takes none.
+ * `framework.transaction`'s type. It infers the handle tuple without `as const`
+ * and resolves the committed response (`A1009`) with each handle's result in
+ * plan order, or the failure response.
  */
 export type TransactionRunner = <const Ops extends readonly Operation<unknown>[]>(operations: Ops, options?: ExecutionOptions) => Promise<TransactionCommittedResponse<TransactionResults<Ops>> | OperationFailureResponse>;
 export {};

package/dist/transactions/operation-arguments-encoder.d.ts

@@ -1,6 +1,7 @@
 import type { Contract } from "../contracts/contract.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+/** Encodes validated application arguments into the wire scalar form. */
 export declare function encodeOperationArgumentsForWire(contract: Contract, operation: OperationIdentity & {
     readonly resource: string;
 }, args: SemanticOperationArguments): unknown;

package/dist/transactions/operation-fingerprint.d.ts

@@ -1,10 +1,12 @@
 import type { OperationFingerprint } from "./deferred-operation.js";
+/** What an operation fingerprint is computed from. */
 export type OperationFingerprintNode = {
     readonly resource: string;
     readonly family: string;
     readonly variant: string;
     readonly args: unknown;
 };
+/** Whether `value` is an operation fingerprint (`fp1:…`). */
 export declare function isOperationFingerprint(value: unknown): value is OperationFingerprint;
-/** Computes the v1 operation fingerprint from an already wire-form node. */
+/** Computes an operation's fingerprint from its wire-form arguments. */
 export declare function computeOperationFingerprint(node: OperationFingerprintNode): Promise<OperationFingerprint>;

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

@@ -28,10 +28,8 @@ export type TransactionOperationEntryInspection = {
     readonly issue: ValidationIssue;
 };
 /**
- * Inspects the plan's operations tuple without dereferencing untrusted array
- * properties outside a reflection boundary. The caller uses the returned
- * length and per-index inspector rather than `operations.length` or
- * `operations[index]` directly.
+ * The caller uses the returned length and per-index inspector rather than
+ * `operations.length` or `operations[index]` directly.
  */
 export declare function inspectTransactionOperations(value: unknown): TransactionOperationsInspection;
 /** Reads one operations entry through its own data descriptor. */

package/dist/transactions/transaction-integrity-error.d.ts

@@ -1,22 +1,11 @@
 /**
- * The ways an Adapter transaction can break the contract the framework's plan
- * executor depends on. Each is answered `A3002`; the violation is the only thing
- * that tells them apart, so it is structured data rather than message text.
- *
- * - `transaction-unavailable`: the Adapter's `transaction` function is gone at
- *   execution time.
- * - `resolved-after-abort`: the Adapter resolved although the framework threw its
- *   rollback request.
- * - `resolved-incomplete`: the Adapter resolved before every plan operation ran,
- *   so no committed `A1009` array exists.
- * - `foreign-abort`: the Adapter rejected with the framework's rollback request
- *   although this plan never made one.
+ * The ways an Adapter transaction can break the framework's transaction
+ * contract. Each is answered `A3002`.
  */
 export type TransactionIntegrityViolation = "transaction-unavailable" | "resolved-after-abort" | "resolved-incomplete" | "foreign-abort";
 /**
- * The framework-owned failure reported to diagnostics when an Adapter
- * transaction violates its contract. It never reaches the wire: the response
- * is always the constant `A3002` envelope.
+ * Reported to diagnostics when an Adapter transaction breaks the framework's
+ * transaction contract. The caller receives `A3002`.
  */
 export declare class TransactionIntegrityError extends Error {
     readonly violation: TransactionIntegrityViolation;

package/dist/transactions/transaction-plan-assembler.d.ts

@@ -1,10 +1,13 @@
 import type { FrameworkContracts } from "../compiler/contract.compiler.js";
 import type { RequestOrigin } from "../config/config-layer.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { CallerDataError } from "../runtime/caller-data.copier.js";
+import type { MisuseReporter } from "../runtime/misuse-reporter.js";
 import type { ClientProtocolIdentity } from "../runtime/operation-request.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
 import type { Operation, OperationFingerprint } from "./deferred-operation.js";
 import type { TransactionOperationOrigin } from "./transaction-request.js";
+/** One wire node, exactly as the transaction runtime receives it. */
 type WireOperationNode = {
     readonly resource: string;
     readonly family: string;
@@ -19,6 +22,8 @@ export type AssembledTransactionPlan = {
     };
     /** Each operation's own origin, by index (mixed plans). */
     readonly origins: readonly TransactionOperationOrigin[];
+    /** The steps whose arguments their builder could not copy, by index. */
+    readonly refused: ReadonlyMap<number, CallerDataError>;
 } | {
     readonly ok: false;
     readonly response: OperationFailureResponse;
@@ -34,5 +39,5 @@ export type TransactionPlanAssembler = {
  * handle, so a handle another instance built — typed against another model,
  * bound to other Contracts — is refused rather than run.
  */
-export declare function createTransactionPlanAssembler(contracts: FrameworkContracts, protocol: ClientProtocolIdentity): TransactionPlanAssembler;
+export declare function createTransactionPlanAssembler(contracts: FrameworkContracts, protocol: ClientProtocolIdentity, misuse: MisuseReporter): TransactionPlanAssembler;
 export {};

package/dist/transactions/transaction-plan-assembler.js

@@ -1,4 +1,5 @@
 import { validationIssue } from "../operations/validation-code.js";
+import { copyAtDoor, refuseCallerData } from "../runtime/caller-data.door.js";
 import { operationFailure } from "../runtime/operation-response.js";
 import { mapValidationOutcome } from "../runtime/outcome-mapper.js";
 import { encodeOperationArgumentsForWire } from "./operation-arguments-encoder.js";
@@ -11,63 +12,63 @@ function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-function referenceKeys(identity) {
-    switch (identity.family) {
-        case "create":
-        case "update":
-            return ["data"];
-        case "upsert":
-            return ["create", "update"];
-        default:
-            return [];
+const KEEP = Symbol("keep");
+function rebuildArguments(value, path, leaf, ancestors = new Set()) {
+    const replaced = leaf(value, path);
+    if (replaced !== KEEP) {
+        return replaced;
     }
-}
-function referenceContainers(identity, args) {
-    if (!isPlainRecord(args)) {
-        return [];
-    }
-    return referenceKeys(identity).flatMap((key) => {
-        const value = args[key];
-        if (Array.isArray(value)) {
-            return value.flatMap((entry, index) => isPlainRecord(entry) ? [{ path: [key, index], record: entry }] : []);
-        }
-        return isPlainRecord(value) ? [{ path: [key], record: value }] : [];
-    });
-}
-function replaceContainers(identity, args, rebuild) {
-    if (!isPlainRecord(args)) {
-        return args;
+    if (!Array.isArray(value) && !isPlainRecord(value)) {
+        return value;
     }
-    const result = { ...args };
-    for (const key of referenceKeys(identity)) {
-        const value = args[key];
-        if (Array.isArray(value)) {
-            result[key] = value.map((entry, index) => isPlainRecord(entry)
-                ? rebuild({ path: [key, index], record: entry })
-                : entry);
-        }
-        else if (isPlainRecord(value)) {
-            result[key] = rebuild({ path: [key], record: value });
-        }
+    if (ancestors.has(value)) {
+        return value;
     }
-    return result;
+    ancestors.add(value);
+    const rebuilt = Array.isArray(value)
+        ? value.map((entry, index) => rebuildArguments(entry, [...path, index], leaf, ancestors))
+        : Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            rebuildArguments(entry, [...path, key], leaf, ancestors),
+        ]));
+    ancestors.delete(value);
+    return rebuilt;
 }
 function operationEntryFailure(operation, message) {
     return transactionOperationFailure(operationFailure("A2004", {
         message: "Transaction plan failed framework validation.",
-        issues: [validationIssue("V1001", ["operation"], message)],
+        issues: [validationIssue("V1001", [], message)],
     }), operation);
 }
 function referenceFailure(issue, operation) {
     return transactionOperationFailure(mapValidationOutcome([issue]), operation);
 }
-export function createTransactionPlanAssembler(contracts, protocol) {
+export function createTransactionPlanAssembler(contracts, protocol, misuse) {
     const handles = new WeakMap();
     const placeholders = new WeakMap();
     const originOf = (origin) => origin === "application"
-        ? { scope: "application" }
-        : { scope: "client", protocol };
-    const snapshot = (identity, args) => replaceContainers(identity, args, ({ record }) => ({ ...record }));
+        ? { origin: "application" }
+        : { origin: "client", protocol };
+    const snapshot = (args) => {
+        const copy = copyAtDoor(args, {
+            keep: (value) => placeholders.has(value),
+        });
+        return copy.ok ? { args: copy.value } : { args: {}, refused: copy.error };
+    };
+    const placeholderSites = (args) => {
+        const sites = [];
+        rebuildArguments(args, [], (value, path) => {
+            const placeholder = typeof value === "object" && value !== null
+                ? placeholders.get(value)
+                : undefined;
+            if (placeholder === undefined) {
+                return KEEP;
+            }
+            sites.push({ path, object: value, placeholder });
+            return value;
+        });
+        return sites;
+    };
     const defer = (origin, resource, identity, args) => {
         const handle = Object.freeze({
             $ref: (field) => {
@@ -82,11 +83,22 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             origin,
             resource,
             identity,
-            args: snapshot(identity, args),
+            ...snapshot(args),
         });
         return handle;
     };
-    const assemble = async (operations) => {
+    const assemble = async (input) => {
+        const list = copyAtDoor(input, { keep: (value) => value !== input });
+        if (!list.ok) {
+            return {
+                ok: false,
+                response: operationFailure("A2004", {
+                    message: "Transaction plan failed framework validation.",
+                    issues: [refuseCallerData(list.error, ["operations"], {}, misuse)],
+                }),
+            };
+        }
+        const operations = list.value;
         if (!Array.isArray(operations)) {
             return {
                 ok: false,
@@ -120,17 +132,12 @@ export function createTransactionPlanAssembler(contracts, protocol) {
             records.push(record);
         }
         for (const [index, record] of records.entries()) {
-            for (const { path, record: container } of referenceContainers(record.identity, record.args)) {
-                for (const [field, value] of Object.entries(container)) {
-                    const placeholder = typeof value === "object" && value !== null
-                        ? placeholders.get(value)
-                        : undefined;
-                    if (placeholder !== undefined && !positions.has(placeholder.source)) {
-                        return {
-                            ok: false,
-                            response: referenceFailure(validationIssue("V1010", ["operations", index, "args", ...path, field, "$ref"], "Transaction reference names an operation that is not in this transaction."), index),
-                        };
-                    }
+            for (const { path, placeholder } of placeholderSites(record.args)) {
+                if (!positions.has(placeholder.source)) {
+                    return {
+                        ok: false,
+                        response: referenceFailure(validationIssue("V1010", ["operations", index, "args", ...path, "$ref"], "Transaction reference names an operation that is not in this transaction."), index),
+                    };
                 }
             }
         }
@@ -145,26 +152,17 @@ export function createTransactionPlanAssembler(contracts, protocol) {
         };
         const materialize = async (index) => {
             const record = records[index];
-            const references = [];
-            const args = replaceContainers(record.identity, record.args, ({ record: container }) => {
-                const bound = { ...container };
-                for (const [field, value] of Object.entries(container)) {
-                    const placeholder = typeof value === "object" && value !== null
-                        ? placeholders.get(value)
-                        : undefined;
-                    if (placeholder === undefined) {
-                        continue;
-                    }
-                    const operation = positions.get(placeholder.source);
-                    references.push(nodeAt(operation).then(({ fingerprint }) => {
-                        bound[field] = {
-                            $ref: { operation, fingerprint, path: [placeholder.field] },
-                        };
-                    }));
-                }
-                return bound;
-            });
-            await Promise.all(references);
+            const bound = new Map();
+            await Promise.all(placeholderSites(record.args).map(async ({ object, placeholder }) => {
+                const operation = positions.get(placeholder.source);
+                const { fingerprint } = await nodeAt(operation);
+                bound.set(object, {
+                    $ref: { operation, fingerprint, path: [placeholder.field] },
+                });
+            }));
+            const args = rebuildArguments(record.args, [], (value) => typeof value === "object" && value !== null && bound.has(value)
+                ? bound.get(value)
+                : KEEP);
             return {
                 resource: record.resource,
                 family: record.identity.family,
@@ -195,6 +193,7 @@ export function createTransactionPlanAssembler(contracts, protocol) {
                 operations: await Promise.all(records.map((_, index) => nodeAt(index))),
             },
             origins: records.map((record) => originOf(record.origin)),
+            refused: new Map(records.flatMap((record, index) => record.refused === undefined ? [] : [[index, record.refused]])),
         };
     };
     return { defer, assemble };

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

@@ -2,6 +2,7 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { Contract } from "../contracts/contract.js";
 import type { ScalarField } from "../contracts/field.js";
 import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+import { CallerDataError } from "../runtime/caller-data.copier.js";
 import { type ReadProjectionPlan } from "../runtime/computed-read-runtime.js";
 import type { FrameworkOperationRequest } from "../runtime/operation-request.js";
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
@@ -9,15 +10,37 @@ import type { OperationPipelineDependencies } from "../runtime/operation-runtime
 import type { CascadeClosure } from "../runtime/referential-action.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 import type { TransactionReference } from "./transaction-reference.js";
+import { type TransactionSlotShape } from "./transaction-reference.js";
+import { type TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
 import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
-export type TransactionReferenceCandidateSlot = {
-    readonly path: readonly (string | number)[];
-    readonly field: ScalarField<Contract>;
-    readonly candidate: unknown;
+/**
+ * Where a plan's step arguments came from, so the validator knows whether to copy
+ * them at the door (see `ArgumentsSource`):
+ *
+ * - `"caller"` — `framework.executeTransaction`'s caller's own objects: every step's
+ *   arguments are copied when the plan is handed in, before the validator's first
+ *   await, so a step revoked or changed after the call is never read again;
+ * - `"owned"` — a plan the protocol decoder parsed, or the typed runner assembled
+ *   from its builders' copies; `refused` names the steps whose arguments a builder
+ *   could not copy, answered at their turn.
+ */
+export type PlanArguments = {
+    readonly source: "caller";
+} | {
+    readonly source: "owned";
+    readonly refused?: ReadonlyMap<number, CallerDataError>;
 };
+export type { TransactionReferenceCandidateSlot } from "./transaction-reference-collector.js";
+/** One validated Transaction Slot: where it is, what it holds, and its reference. */
 export type TransactionReferenceSlot = {
     readonly path: readonly (string | number)[];
+    /** The destination field. */
     readonly field: ScalarField<Contract>;
+    readonly shape: TransactionSlotShape;
+    /** The slot is a scalar value of mutation data: what it resolves to is written. */
+    readonly written: boolean;
+    /** The source field, under its own step's Contract: what the slot receives. */
+    readonly source: ScalarField<Contract>;
     readonly reference: TransactionReference;
 };
 export type CandidateTransactionOperation = {
@@ -48,10 +71,10 @@ export type ValidatedTransactionPlan = {
 /**
  * What validating a plan needs beyond one operation's pipeline: the cascade
  * closure over the Adapter's referential actions, resolved once when the
- * Framework is constructed. The create requirements are not among them: they
+ * Framework is constructed. The record-write facts are not among them: they
  * are checked when each operation runs, after its pipes.
  */
-export type TransactionPlanDependencies<M extends AdapterModel> = Omit<OperationPipelineDependencies<M>, "createRequirements"> & {
+export type TransactionPlanDependencies<M extends AdapterModel> = Omit<OperationPipelineDependencies<M>, "recordWrites"> & {
     readonly cascades: CascadeClosure;
 };
 export type TransactionPlanValidationResult = {
@@ -62,26 +85,12 @@ export type TransactionPlanValidationResult = {
     readonly response: OperationFailureResponse;
 };
 /**
- * The refusal of a plan on a Contract without transaction plans (`A2002`, one
- * `V1006` at `["operations"]`). The one spelling — the protocol's absence answer
- * for `/_transactions` is this envelope too.
+ * The refusal of a plan on a Contract without transaction plans (`A2002`, one `V1006`
+ * at `["operations"]`). The one spelling — the protocol's absence answer for
+ * `/_transactions` is this envelope too.
  */
 export declare function transactionsUnavailableFailure(): OperationFailureResponse;
 /**
  * Whole-plan Framework Validation Layer for transaction structure and identity.
- *
- * `origins` states each operation's origin by index, for a plan whose steps do
- * not all share the request's (the typed runner's mixed plans). Absent — the
- * untyped seam — every operation takes the request's own origin. Each operation
- * is validated against its own origin's Contract.
- *
- * A plan is also refused when a step depends on rows an earlier step's cascade
- * removed (`V1019`, plan-scoped: a lone operation that cascades is not a
- * defect, since nothing follows it). The analysis runs over every step whatever
- * its origin — one plan runs in one Adapter transaction, so a client step's
- * read sees an application step's cascade — and reads each step against its own
- * origin's Contract. It is a planning answer, given before any provider statement
- * is issued, and as conservative as the facts it has: a plan cannot know which
- * rows a delete will match, so it refuses at the granularity of a Resource.
  */
-export declare function validateTransactionPlan<M extends AdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[]): Promise<TransactionPlanValidationResult>;
+export declare function validateTransactionPlan<M extends AdapterModel>(dependencies: TransactionPlanDependencies<M>, request: FrameworkTransactionRequest, origins?: readonly TransactionOperationOrigin[], planArguments?: PlanArguments): Promise<TransactionPlanValidationResult>;