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

package/dist/transactions/transaction-reference-collector.js

@@ -0,0 +1,204 @@
+import { lookupField, lookupOwn, lookupResource, } from "../contracts/contract-lookup.js";
+import { planOperationArgumentsPath } from "../runtime/error-boundary.js";
+import { isPlainRecord, referenceOperandShape, } from "../runtime/scalar-runtime.js";
+import { routeTransactionReferenceCandidate, } from "./transaction-reference.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function at(position, ...segments) {
+    return { ...position, path: [...position.path, ...segments] };
+}
+function collectValue(field, shape, value, path, candidates, written = false) {
+    const route = routeTransactionReferenceCandidate(value);
+    if (route.kind === "ordinary") {
+        return false;
+    }
+    candidates.push({
+        path,
+        field,
+        shape,
+        written,
+        candidate: route.candidate,
+    });
+    return true;
+}
+function collectKey(position, selector, candidates) {
+    if (!isObject(selector)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [fieldName, value] of Object.entries(selector)) {
+        const field = lookupField(resource, fieldName);
+        if (field?.kind === "scalar") {
+            collectValue(field, "nonNullValue", value, [...position.path, fieldName], candidates);
+        }
+    }
+}
+function collectKeys(position, selectors, candidates) {
+    if (Array.isArray(selectors)) {
+        selectors.forEach((selector, index) => {
+            collectKey(at(position, index), selector, candidates);
+        });
+        return;
+    }
+    collectKey(position, selectors, candidates);
+}
+function collectScalarFilter(field, filter, path, candidates) {
+    if (collectValue(field, "value", filter, path, candidates) ||
+        !isPlainRecord(filter)) {
+        return;
+    }
+    for (const [operator, operand] of Object.entries(filter)) {
+        const operandPath = [...path, operator];
+        if (operator === "not") {
+            collectScalarFilter(field, operand, operandPath, candidates);
+            continue;
+        }
+        const shape = referenceOperandShape(operator);
+        if (shape !== undefined) {
+            collectValue(field, shape, operand, operandPath, candidates);
+        }
+    }
+}
+function collectWhere(position, where, candidates) {
+    if (!isObject(where)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [key, value] of Object.entries(where)) {
+        if (key === "AND" || key === "OR") {
+            if (Array.isArray(value)) {
+                value.forEach((entry, index) => {
+                    collectWhere(at(position, key, index), entry, candidates);
+                });
+            }
+            continue;
+        }
+        if (key === "NOT") {
+            collectWhere(at(position, key), value, candidates);
+            continue;
+        }
+        const field = lookupField(resource, key);
+        if (field?.kind === "scalar") {
+            collectScalarFilter(field, value, [...position.path, key], candidates);
+        }
+        else if (field?.kind === "relation") {
+            const target = { ...at(position, key), resource: field.target };
+            if (field.cardinality === "one") {
+                collectWhere(target, value, candidates);
+            }
+            else if (isObject(value)) {
+                for (const operator of ["some", "every", "none"]) {
+                    if (Object.hasOwn(value, operator)) {
+                        collectWhere(at(target, operator), value[operator], candidates);
+                    }
+                }
+            }
+        }
+    }
+}
+function eachEntry(position, operand, visit) {
+    if (Array.isArray(operand)) {
+        operand.forEach((entry, index) => {
+            visit(at(position, index), entry);
+        });
+        return;
+    }
+    visit(position, operand);
+}
+function collectRelationDirectives(position, edge, value, candidates) {
+    if (!isObject(value)) {
+        return;
+    }
+    const target = { ...position, resource: edge.target };
+    for (const [directive, operand] of Object.entries(value)) {
+        const directivePosition = at(target, directive);
+        switch (directive) {
+            case "$connect":
+            case "$disconnect":
+            case "$set":
+                collectKeys(directivePosition, operand, candidates);
+                break;
+            case "$create":
+                eachEntry(directivePosition, operand, (entryPosition, entry) => {
+                    collectData(entryPosition, entry, candidates);
+                });
+                break;
+            case "$connectOrCreate":
+            case "$update":
+            case "$delete":
+            case "$upsert":
+                eachEntry(directivePosition, operand, (entryPosition, entry) => {
+                    if (!isObject(entry)) {
+                        return;
+                    }
+                    const where = at(entryPosition, "where");
+                    if (directive === "$update" || directive === "$delete") {
+                        collectWhere(where, entry.where, candidates);
+                    }
+                    else {
+                        collectKey(where, entry.where, candidates);
+                    }
+                    for (const branch of ["create", "update", "data"]) {
+                        if (Object.hasOwn(entry, branch)) {
+                            collectData(at(entryPosition, branch), entry[branch], candidates);
+                        }
+                    }
+                });
+                break;
+        }
+    }
+}
+function collectData(position, data, candidates) {
+    if (!isObject(data)) {
+        return;
+    }
+    const resource = lookupResource(position.contract, position.resource);
+    for (const [fieldName, value] of Object.entries(data)) {
+        const field = lookupField(resource, fieldName);
+        if (field?.kind === "scalar") {
+            collectValue(field, "value", value, [...position.path, fieldName], candidates, true);
+        }
+        else if (field?.kind === "relation") {
+            collectRelationDirectives(at(position, fieldName), field, value, candidates);
+        }
+    }
+}
+export function collectTransactionReferenceCandidates(contract, request, index, args) {
+    const candidates = [];
+    const root = {
+        contract,
+        resource: request.resource,
+        path: planOperationArgumentsPath(index),
+    };
+    const where = lookupOwn(args, "where");
+    if (request.variant === "unique") {
+        collectKey(at(root, "where"), where, candidates);
+    }
+    else {
+        collectWhere(at(root, "where"), where, candidates);
+    }
+    collectKey(at(root, "cursor"), lookupOwn(args, "cursor"), candidates);
+    if (request.family === "create") {
+        const data = lookupOwn(args, "data");
+        if (request.variant === "many" || request.variant === "count") {
+            if (Array.isArray(data)) {
+                data.forEach((entry, dataIndex) => {
+                    collectData(at(root, "data", dataIndex), entry, candidates);
+                });
+            }
+        }
+        else {
+            collectData(at(root, "data"), data, candidates);
+        }
+    }
+    else if (request.family === "update") {
+        collectData(at(root, "data"), lookupOwn(args, "data"), candidates);
+    }
+    else if (request.family === "upsert") {
+        for (const stage of ["create", "update"]) {
+            collectData(at(root, stage), lookupOwn(args, stage), candidates);
+        }
+    }
+    return candidates;
+}

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

@@ -10,17 +10,14 @@ export type ResolvedTransactionArguments = {
 };
 /**
  * Substitutes every validated `$ref` placeholder of one operation from the results
- * ledger: each earlier operation's final `data`, exactly the value at its index in
- * the `A1009` results array. Validation already proved index, source fingerprint,
- * projected path and type, and none of that is re-run here; only what can change
- * at runtime is checked. A `null` or non-record source, or a source lacking the
- * referenced own key, resolves to no value at the full reference path. The result
- * is a fresh argument graph: only the ancestors of substituted slots are cloned,
- * so the validated plan is never mutated, and every substituted value is a
- * framework-owned copy of the source's value, so a dependent operation mutating
- * its arguments cannot alter the source's committed result.
- *
- * Reading final data runs developer-produced accessors; a throw from here is the
- * framework's own per-operation failure, classified by the caller.
+ * ledger: each earlier operation's final `data`, exactly the value at its index in the
+ * `A1009` results array. Validation already proved index, source fingerprint,
+ * projected path and type, and none of that is re-run here; only what can change at
+ * runtime is checked. A `null` or non-record source, or a source lacking the
+ * referenced own key, resolves to no value at the full reference path. The result is a
+ * fresh argument graph: only the ancestors of substituted slots are cloned, so the
+ * validated plan is never mutated, and every substituted value is a framework-owned
+ * copy of the source's value, so a dependent operation mutating its arguments cannot
+ * alter the source's committed result.
  */
 export declare function resolveTransactionReferences(operation: ValidatedTransactionOperation, results: readonly unknown[]): ResolvedTransactionArguments;

package/dist/transactions/transaction-reference-resolver.js

@@ -1,11 +1,12 @@
 import { validationIssue } from "../operations/validation-code.js";
-import { copyScalarFieldValue } from "../runtime/scalar-runtime.js";
+import { copyScalarFieldValue, jsonShapeIssues, } from "../runtime/scalar-runtime.js";
 import { replaceTransactionSlotValues } from "./transaction-slot-writer.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export function resolveTransactionReferences(operation, results) {
     const substitutions = [];
+    const shapeIssues = [];
     for (const slot of operation.references) {
         const { operation: source, path: [segment], } = slot.reference.$ref;
         const row = results[source];
@@ -17,10 +18,14 @@ export function resolveTransactionReferences(operation, results) {
                 ],
             };
         }
-        substitutions.push({
-            path: slot.path,
-            value: copyScalarFieldValue(slot.field, row[segment]),
-        });
+        const value = copyScalarFieldValue(slot.source, row[segment]);
+        if (slot.written) {
+            shapeIssues.push(...jsonShapeIssues(slot.field, value, slot.path));
+        }
+        substitutions.push({ path: slot.path, value });
+    }
+    if (shapeIssues.length > 0) {
+        return { ok: false, issues: shapeIssues };
     }
     return {
         ok: true,

package/dist/transactions/transaction-reference-validator.js

@@ -141,25 +141,28 @@ function containsUnpairedSurrogate(value) {
     }
     return false;
 }
-function sameType(source, destination) {
+function sameScalar(source, destination) {
     if ("scalar" in source.type) {
-        if (!("scalar" in destination.type)) {
-            return false;
-        }
-        if (source.type.scalar !== destination.type.scalar) {
-            return false;
-        }
+        return ("scalar" in destination.type &&
+            source.type.scalar === destination.type.scalar);
     }
-    else {
-        if (!("enum" in destination.type)) {
-            return false;
-        }
-        if (source.type.enum !== destination.type.enum) {
-            return false;
-        }
+    return ("enum" in destination.type && source.type.enum === destination.type.enum);
+}
+function isAssignable(source, destination, shape) {
+    if (!sameScalar(source, destination)) {
+        return false;
+    }
+    switch (shape) {
+        case "value":
+            return (source.list === destination.list &&
+                !(source.nullable && !destination.nullable));
+        case "nonNullValue":
+            return source.list === destination.list && !source.nullable;
+        case "entry":
+            return !source.list && !source.nullable;
+        case "entries":
+            return source.list && !source.nullable;
     }
-    return (source.list === destination.list &&
-        !(source.nullable && !destination.nullable));
 }
 const CANDIDATE_KEYS = new Set(["$ref"]);
 const REFERENCE_KEYS = new Set(["operation", "fingerprint", "path"]);
@@ -234,7 +237,8 @@ export function validateTransactionReferences(operation, earlier) {
         if (sourceField === undefined) {
             return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
         }
-        if (sourceField.kind !== "scalar" || !sameType(sourceField, slot.field)) {
+        if (sourceField.kind !== "scalar" ||
+            !isAssignable(sourceField, slot.field, slot.shape)) {
             return failure(validationIssue("V1011", pathPath, "Transaction reference source type is not assignable to its destination."), operation.index);
         }
         const reference = Object.freeze({
@@ -247,6 +251,9 @@ export function validateTransactionReferences(operation, earlier) {
         references.push({
             path: Object.freeze([...slot.path]),
             field: slot.field,
+            shape: slot.shape,
+            written: slot.written,
+            source: sourceField,
             reference,
         });
     }

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

@@ -1,13 +1,18 @@
 import type { WriteScope } from "../contracts/capability.js";
 import type { Contract } from "../contracts/contract.js";
 import type { ScalarForms } from "../contracts/scalar-value-type.js";
-import type { CreateDataInput, OperationArgumentsFor, ResourceKey, UpdateDataInput, WritableRelationKey } from "../operations/operation-arguments.js";
+import type { CreateDataInput, OperationArgumentsFor, ResourceKey, UpdateDataInput } from "../operations/operation-arguments.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { OperationFingerprint } from "./deferred-operation.js";
 declare const REFERENCE_VALUE: unique symbol;
+/** Any object with a `$ref` key, before it is validated as a reference. */
 export type TransactionReferenceCandidate = {
     readonly $ref: unknown;
 } & Readonly<Record<string, unknown>>;
+/**
+ * A reference to a field of an earlier operation's result in the same
+ * transaction plan: `{ $ref: { operation, fingerprint, path } }`.
+ */
 export type TransactionReference<Value = unknown> = {
     readonly $ref: {
         readonly operation: number;
@@ -16,6 +21,7 @@ export type TransactionReference<Value = unknown> = {
     };
     readonly [REFERENCE_VALUE]?: Value;
 };
+/** Whether a value is an ordinary value or a `$ref` candidate. */
 export type TransactionReferenceCandidateRoute = {
     readonly kind: "ordinary";
 } | {
@@ -27,15 +33,11 @@ export type TransactionReferenceCandidateRoute = {
     readonly kind: "reflection-failure";
     readonly candidate: unknown;
 };
-/**
- * Total descriptor-only routing for a scalar value at a transaction-reference
- * position.
- */
+/** Whether a scalar value at a reference position is an ordinary value or a `$ref` candidate. */
 export declare function routeTransactionReferenceCandidate(value: unknown): TransactionReferenceCandidateRoute;
+/** Whether `value` is an object with a `$ref` key; it is not validated here. */
 export declare function isTransactionReferenceCandidate(value: unknown): value is TransactionReferenceCandidate;
-/**
- * Narrows a structurally complete `$ref` object.
- */
+/** Whether `value` is a complete `$ref` object. */
 export declare function isTransactionReferenceObject(value: unknown): value is TransactionReference;
 /**
  * A scalar mutation value inside a plan: the value itself, or a reference to an
@@ -43,68 +45,33 @@ export declare function isTransactionReferenceObject(value: unknown): value is T
  */
 export type TransactionScalarValue<Value> = Value | TransactionReference<Value>;
 /**
- * A reference carries its source's final data, which every scope returns in the
- * application forms; so a client-origin builder writes wire forms and still takes
- * a `$ref` typed by the application form of the same Contract field — strict type
- * compatibility compares Contract field types, never their forms. Unstated, both
- * are the same map and this is {@link TransactionScalarValue}.
- */
-type ReferenceableValue<Value, ReferenceValue> = Value | TransactionReference<ReferenceValue>;
-type MemberOf<Data, Key> = Key extends keyof Data ? Data[Key] : never;
-/**
- * The exported {@link TransactionCreateDataInput} is it with neither form stated;
- * the typed builders state both.
- */
-export type ReferenceableCreateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in keyof CreateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "create", Scope> ? CreateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<CreateDataInput<C, K, Scope, Forms>[F], MemberOf<CreateDataInput<C, K, Scope, ReferenceForms>, F>>;
-}>;
-export type ReferenceableUpdateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
-    [F in keyof UpdateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "update", Scope> ? UpdateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<UpdateDataInput<C, K, Scope, Forms>[F], MemberOf<UpdateDataInput<C, K, Scope, ReferenceForms>, F>>;
-}>;
-/**
- * Only top-level scalar fields accept a `$ref`; a relation field keeps its
- * relation mutation action, where a `$ref` is an ordinary invalid value.
+ * What a Transaction Slot holds of its destination field, which decides the source
+ * fields a reference there accepts — always the same scalar or enum, no coercion:
  *
- * The position is the standalone surface's, read the same way: both surfaces read
- * one capability value and differ only in where they bind it, so a plan's flat
- * bulk write refuses a nested-only relation exactly as `create.many` does outside
- * a plan. The default is the unrestricted position, as on `CreateDataInput`.
+ * - `"value"` — the field's whole value, where a `null` means something: a mutation
+ *   value, or an equality filter (`null` matches the rows the field is unset on). A
+ *   nullable source only into a nullable field.
+ * - `"nonNullValue"` — the field's whole value, where a `null` identifies or orders
+ *   nothing: a unique key, a `cursor`, an ordering or text comparison. The source is
+ *   never nullable.
+ * - `"entry"` — one entry of a list field (`has`): a non-null, non-list source.
+ * - `"entries"` — a list of entries (`in`, `notIn`, `hasEvery`, `hasSome`): a
+ *   non-null list source.
  */
-export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableCreateData<C, K, Scope, ScalarForms, ScalarForms>;
+export type TransactionSlotShape = "value" | "nonNullValue" | "entry" | "entries";
 /**
- * See {@link TransactionCreateDataInput}.
+ * Create data inside a transaction plan, at one write position: its scalar values
+ * and the unique keys its relation directives name may hold a `$ref`. The default
+ * is the unrestricted position, as on `CreateDataInput`.
  */
-export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableUpdateData<C, K, Scope, ScalarForms, ScalarForms>;
+export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = CreateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
+/** Update data inside a transaction plan. See {@link TransactionCreateDataInput}. */
+export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = UpdateDataInput<C, K, Scope, ScalarForms, ScalarForms>;
 /**
- * The typed builders read it with both forms stated; the exported {@link
- * TransactionOperationArgumentsFor} is it with neither.
+ * Operation arguments inside a transaction plan, under one value form and one
+ * reference form: `OperationArgumentsFor` with its reference positions opened.
  */
-export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = I extends {
-    family: "create";
-    variant: "one";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableCreateData<C, K, "nested", Forms, ReferenceForms>;
-} : I extends {
-    family: "create";
-    variant: "many" | "count";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: readonly ReferenceableCreateData<C, K, "bulkWrite", Forms, ReferenceForms>[];
-} : I extends {
-    family: "update";
-    variant: "first" | "unique";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableUpdateData<C, K, "nested", Forms, ReferenceForms>;
-} : I extends {
-    family: "update";
-    variant: "many" | "count";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "data"> & {
-    data: ReferenceableUpdateData<C, K, "bulkWrite", Forms, ReferenceForms>;
-} : I extends {
-    family: "upsert";
-} ? Omit<OperationArgumentsFor<C, K, I, Forms>, "create" | "update"> & {
-    create: ReferenceableCreateData<C, K, "nested", Forms, ReferenceForms>;
-    update: ReferenceableUpdateData<C, K, "nested", Forms, ReferenceForms>;
-} : OperationArgumentsFor<C, K, I, Forms>;
+export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = OperationArgumentsFor<C, K, I, Forms, ReferenceForms>;
 /** Operation arguments inside a transaction plan, no scalar form stated. */
 export type TransactionOperationArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity> = ReferenceableArgumentsFor<C, K, I, ScalarForms, ScalarForms>;
 export {};

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

@@ -4,25 +4,23 @@ type TransactionRequestBase = {
     readonly requestId: string;
     readonly plan: unknown;
 };
+/** An in-process transaction request, run under the Application Contract. */
 export type ApplicationTransactionRequest = TransactionRequestBase & {
-    readonly scope: "application";
+    readonly origin: "application";
     readonly protocol?: never;
     readonly transport?: never;
 };
+/** A remote transaction request, run under the Client Contract. */
 export type ClientTransactionRequest = TransactionRequestBase & {
-    readonly scope: "client";
+    readonly origin: "client";
     readonly protocol: ClientProtocolIdentity;
     readonly transport?: PipelineTransportContext;
 };
+/** One transaction request, as `framework.executeTransaction` takes it. */
 export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest;
 /**
  * The origin one plan operation runs under: its own layer's Contract, its own
  * pipelines, and — for a client step — the protocol identity it is accepted with.
- * The untyped seam derives every operation's origin from the request; the typed
- * runner states one per handle.
- *
- * Internal to the transaction runtime, and deliberately not a member of the
- * request: the public seam's request cannot smuggle a per-operation origin.
  */
-export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "scope"> | Pick<ClientTransactionRequest, "scope" | "protocol" | "transport">;
+export type TransactionOperationOrigin = Pick<ApplicationTransactionRequest, "origin"> | Pick<ClientTransactionRequest, "origin" | "protocol" | "transport">;
 export {};

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

@@ -1,17 +1,20 @@
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
-/**
- * A committed plan: each operation's final `data`, in plan order.
- *
- * `T` mirrors `OperationResponse<T>`: the untyped seam (`executeTransaction`)
- * answers the default `readonly unknown[]`, and the typed runner
- * (`framework.transaction`) supplies the per-position tuple its handles derive.
- */
+/** A committed plan: each operation's final `data`, in plan order. */
 export type TransactionCommittedResponse<T = readonly unknown[]> = {
     readonly data: T;
     readonly code: "A1009";
     readonly cause: null;
 };
+/** What a transaction answers: committed (`A1009`) or a failure. */
 export type TransactionResponse = TransactionCommittedResponse | OperationFailureResponse;
+/** Builds the committed response. */
 export declare function transactionCommitted(results: readonly unknown[]): TransactionCommittedResponse;
+/**
+ * Builds the failure response of a plan step: the step named in
+ * `cause.operation`, and each issue at its full plan location —
+ * `["operations", operation, "args", …]` for the step's arguments,
+ * `["operations", operation, …]` for the step itself.
+ */
 export declare function transactionOperationFailure(failure: OperationFailureResponse, operation: number): OperationFailureResponse;
+/** Builds the `A3002` response for a transaction that itself failed. */
 export declare function transactionInfrastructureFailure(operation?: number): OperationFailureResponse;

package/dist/transactions/transaction-response.js

@@ -1,13 +1,36 @@
+import { OPERATION_ARGUMENTS_PATH, planOperationArgumentsPath, planStepPath, } from "../runtime/error-boundary.js";
 import { operationFailure } from "../runtime/operation-response.js";
 export function transactionCommitted(results) {
     return { data: results, code: "A1009", cause: null };
 }
 export function transactionOperationFailure(failure, operation) {
+    const { issues, ...cause } = failure.cause;
     return operationFailure(failure.code, {
-        ...failure.cause,
+        ...cause,
+        ...(issues === undefined
+            ? {}
+            : { issues: issues.map((issue) => atPlanLocation(issue, operation)) }),
         operation,
     });
 }
+function isPlanLocated(path) {
+    return path[0] === "operations" && typeof path[1] === "number";
+}
+function atPlanLocation(issue, operation) {
+    const { path } = issue;
+    if (path === undefined || isPlanLocated(path)) {
+        return issue;
+    }
+    return {
+        ...issue,
+        path: path[0] === OPERATION_ARGUMENTS_PATH[0]
+            ? [
+                ...planOperationArgumentsPath(operation),
+                ...path.slice(OPERATION_ARGUMENTS_PATH.length),
+            ]
+            : [...planStepPath(operation), ...path],
+    };
+}
 export function transactionInfrastructureFailure(operation) {
     return operationFailure("A3002", {
         message: "Transaction failed.",

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

@@ -1,6 +1,7 @@
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { TransactionDiagnosticsChannel } from "../runtime/diagnostics-reporter.js";
 import type { OperationRuntimeDependencies } from "../runtime/operation-runtime.js";
+import type { PlanArguments } from "./transaction-plan-validator.js";
 import type { FrameworkTransactionRequest, TransactionOperationOrigin } from "./transaction-request.js";
 import type { TransactionResponse } from "./transaction-response.js";
 /**
@@ -9,12 +10,13 @@ import type { TransactionResponse } from "./transaction-response.js";
  * hands it in, so every report of a plan travels the same route.
  *
  * `origins`, when given, states each operation's own origin (the typed
- * runner's mixed plans); see `validateTransactionPlan`.
+ * 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[]) => Promise<TransactionResponse>;
+export type FrameworkTransactionExecutor = (request: FrameworkTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins: readonly TransactionOperationOrigin[] | undefined, planArguments: PlanArguments) => Promise<TransactionResponse>;
 /**
- * Validates a whole plan through the Framework Validation Layer, then runs it
- * inside exactly one Adapter transaction. Guards, pipes, hooks and interceptors of
- * every plan operation run while the provider transaction is open.
+ * Validates a whole plan through the Framework Validation Layer, then runs it inside
+ * exactly one Adapter transaction. Guards, pipes, hooks and interceptors of every plan
+ * operation run while the provider transaction is open.
  */
 export declare function createTransactionRuntime<M extends AdapterModel>(dependencies: OperationRuntimeDependencies<M>): FrameworkTransactionExecutor;

package/dist/transactions/transaction-runtime.js

@@ -1,3 +1,4 @@
+import { recordWriteFactsOf } from "../runtime/create-requirement.js";
 import { planOperationArgumentsPath } from "../runtime/error-boundary.js";
 import { internalFailure } from "../runtime/operation-response.js";
 import { executeValidatedOperation } from "../runtime/operation-runtime.js";
@@ -12,14 +13,14 @@ export function createTransactionRuntime(dependencies) {
     const { adapter, ...runtimeDependencies } = dependencies;
     const pipelineDependencies = {
         ...runtimeDependencies,
-        createRequirements: adapter.createRequirements ?? {},
+        recordWrites: recordWriteFactsOf(adapter),
     };
     const planDependencies = {
         ...pipelineDependencies,
         cascades: resolveCascadeClosure(adapter.referentialActions),
     };
-    return async (request, diagnostics, origins) => {
-        const validation = await validateTransactionPlan(planDependencies, request, origins);
+    return async (request, diagnostics, origins, planArguments) => {
+        const validation = await validateTransactionPlan(planDependencies, request, origins, planArguments);
         if (!validation.ok) {
             return validation.response;
         }

package/dist/transactions/transaction-slot-path-error.d.ts

@@ -1,22 +1,12 @@
 /**
- * The ways a transaction slot path can fail to name a member of the argument view
- * it is written into. Every slot path was collected from an argument view by the
- * plan validator, so any of these is a framework defect rather than a caller
- * error; the violation is the only thing that tells them apart, so it is
- * structured data rather than message text.
- *
- * - `slot-prefix`: the path does not begin `["operations", <this operation>,
- *   "args", <member>]`, or the view itself is not an object.
- * - `absent-member`: a segment names no own member of its container.
- * - `non-object-ancestor`: a segment descends through a non-object value.
+ * The ways a transaction slot path can fail to name a member of its argument
+ * view. Each is a framework defect, not a caller error.
  */
 export type TransactionSlotPathViolation = "slot-prefix" | "absent-member" | "non-object-ancestor";
 /**
- * The framework-owned failure thrown when a slot path does not name a member of
- * the argument view. It never reaches the wire: inside a plan's transaction
- * callback it becomes that operation's `A3000`, during validation the totality
- * guard's `A3000`. It reaches a diagnostics sink as the raw `error`, where the
- * violation discriminates the three defects.
+ * Thrown internally when a slot path does not name a member of its argument
+ * view; the caller receives `A3000`, and the diagnostics sink receives this
+ * error.
  */
 export declare class TransactionSlotPathError extends Error {
     readonly violation: TransactionSlotPathViolation;