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

package/dist/runtime/field-stage.runtime.js

@@ -0,0 +1,143 @@
+export function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const WRITE_KEYS = {
+    create: ["data"],
+    update: ["data"],
+    upsert: ["create", "update"],
+};
+function writeRecordsOf(family, args) {
+    const keys = WRITE_KEYS[family];
+    if (keys === undefined || !isPlainRecord(args)) {
+        return [];
+    }
+    const records = [];
+    for (const key of keys) {
+        if (!Object.hasOwn(args, key)) {
+            continue;
+        }
+        const value = args[key];
+        if (Array.isArray(value)) {
+            for (const [index, entry] of value.entries()) {
+                if (isPlainRecord(entry)) {
+                    records.push({ path: [key, index], record: entry });
+                }
+            }
+        }
+        else if (isPlainRecord(value)) {
+            records.push({ path: [key], record: value });
+        }
+    }
+    return records;
+}
+function sends(record, field) {
+    return Object.hasOwn(record, field) && record[field] !== undefined;
+}
+function isDirective(value) {
+    return (isPlainRecord(value) &&
+        Object.keys(value).some((key) => key.startsWith("$")));
+}
+export function stagedFieldsOf(contract, resource, stages, kind) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    if (fields === undefined) {
+        return [];
+    }
+    return Object.keys(fields).filter((field) => Object.hasOwn(stages, field) && (stages[field]?.[kind].length ?? 0) > 0);
+}
+export function valueAt(args, path) {
+    let current = args;
+    for (const key of path) {
+        if (Array.isArray(current) && typeof key === "number") {
+            current = current[key];
+        }
+        else if (isPlainRecord(current) && Object.hasOwn(current, key)) {
+            current = current[key];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+export function replaceAt(args, path, record) {
+    const [head, ...rest] = path;
+    if (head === undefined) {
+        return record;
+    }
+    if (Array.isArray(args)) {
+        const copy = [...args];
+        copy[head] = replaceAt(copy[head], rest, record);
+        return copy;
+    }
+    const container = args;
+    return {
+        ...container,
+        [head]: replaceAt(container[head], rest, record),
+    };
+}
+export function writeRecordPathsOf(family, args) {
+    return writeRecordsOf(family, args).map((entry) => entry.path);
+}
+export async function pipeSentFields(stages, fields, records, args, select) {
+    if (fields.length === 0) {
+        return { args, changed: false };
+    }
+    let current = args;
+    let changed = false;
+    for (const path of records) {
+        const record = valueAt(current, path);
+        if (!isPlainRecord(record)) {
+            continue;
+        }
+        let piped;
+        for (const field of fields) {
+            if (!sends(record, field) ||
+                isDirective(record[field]) ||
+                !select([...path, field])) {
+                continue;
+            }
+            let value = record[field];
+            for (const pipe of stages[field]?.pipes ?? []) {
+                const next = await pipe(value);
+                if (next !== undefined) {
+                    value = next;
+                    changed = true;
+                }
+            }
+            if (value !== record[field]) {
+                piped ??= { ...record };
+                piped[field] = value;
+            }
+        }
+        if (piped !== undefined) {
+            current = replaceAt(current, path, piped);
+        }
+    }
+    return { args: current, changed };
+}
+export async function guardSentFields(stages, fields, records, args, context) {
+    if (fields.length === 0) {
+        return true;
+    }
+    const sent = records.map((path) => valueAt(args, path)).filter(isPlainRecord);
+    for (const field of fields) {
+        for (const record of sent) {
+            if (!sends(record, field)) {
+                continue;
+            }
+            for (const guard of stages[field]?.guards ?? []) {
+                const told = context();
+                if ((await guard(record[field], told)) === false) {
+                    return false;
+                }
+            }
+        }
+    }
+    return true;
+}

package/dist/runtime/field-validator.runtime.d.ts

@@ -0,0 +1,11 @@
+import type { AvContract } from "../contracts/contract.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+import { type Path } from "./field-stage.runtime.js";
+import type { OperationExecutionRequest } from "./operation-request.js";
+import type { ReferentialActionTable } from "./referential-action.js";
+/**
+ * Every way the sent fields `select` admits break their validators: the
+ * operation's own records, then each nested write target's. Paths are the
+ * request's: `argumentsPath` and then the value's place in the arguments.
+ */
+export declare function fieldValidatorIssues(contract: AvContract, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path, select: (path: Path) => boolean): readonly AvValidationIssue[];

package/dist/runtime/field-validator.runtime.js

@@ -0,0 +1,87 @@
+import { validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { entryCheckIssues, fieldCheckIssues } from "./field-check.evaluator.js";
+import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
+import { nestedWriteTargetsOf } from "./nested-write.walker.js";
+import { jsonShapeIssues } from "./scalar-runtime.js";
+function isDirective(value) {
+    return (isPlainRecord(value) &&
+        Object.keys(value).some((key) => key.startsWith("$")));
+}
+function rulesOf(contract, compiled, resource, name) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    const field = fields !== undefined && Object.hasOwn(fields, name)
+        ? fields[name]
+        : undefined;
+    if (field?.kind === "scalar" && field.json !== undefined) {
+        return { kind: "shape", field };
+    }
+    const checks = Object.hasOwn(compiled, name) ? compiled[name] : undefined;
+    return checks === undefined
+        ? undefined
+        : { kind: "checks", compiled: checks };
+}
+function valueIssues(rules, value, at) {
+    if (rules.kind === "shape") {
+        return jsonShapeIssues(rules.field, value, at);
+    }
+    const { compiled } = rules;
+    return fieldCheckIssues(compiled.checks, value, compiled.subject ?? "string", at, compiled.list);
+}
+function entryIssues(rules, entry, at) {
+    if (rules.kind === "shape") {
+        return jsonShapeIssues(rules.field, entry, at, "entry");
+    }
+    const { compiled } = rules;
+    return entryCheckIssues(compiled.checks, entry, compiled.subject ?? "string", at);
+}
+function recordIssues(contract, resource, records, args, argumentsPath, select) {
+    const compiled = validatedFieldsOf(contract, resource);
+    const issues = [];
+    for (const path of records) {
+        const record = valueAt(args, path);
+        if (!isPlainRecord(record)) {
+            continue;
+        }
+        for (const name of Object.keys(record)) {
+            const rules = rulesOf(contract, compiled, resource, name);
+            if (rules === undefined) {
+                continue;
+            }
+            const fieldPath = [...path, name];
+            const value = record[name];
+            const at = [...argumentsPath, ...fieldPath];
+            if (!isDirective(value)) {
+                if (select(fieldPath)) {
+                    issues.push(...valueIssues(rules, value, at));
+                }
+                continue;
+            }
+            const list = rules.kind === "shape" ? rules.field.list : rules.compiled.list;
+            if (!list || !Object.hasOwn(value, "$push")) {
+                continue;
+            }
+            const operand = value.$push;
+            const pushed = Array.isArray(operand)
+                ? operand.map((entry, index) => ({
+                    entry,
+                    path: [...fieldPath, "$push", index],
+                }))
+                : [{ entry: operand, path: [...fieldPath, "$push"] }];
+            for (const { entry, path: entryPath } of pushed) {
+                if (!isDirective(entry) && (select(fieldPath) || select(entryPath))) {
+                    issues.push(...entryIssues(rules, entry, [...argumentsPath, ...entryPath]));
+                }
+            }
+        }
+    }
+    return issues;
+}
+export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select) {
+    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args), args, argumentsPath, select);
+    for (const target of nestedWriteTargetsOf(contract, references, request, args)) {
+        issues.push(...recordIssues(contract, target.resource, target.records.map((site) => site.path), args, argumentsPath, select));
+    }
+    return issues;
+}

package/dist/runtime/framework-error-class.table.d.ts

@@ -0,0 +1,33 @@
+import type { AvOperationErrorCode } from "./operation-response.js";
+/** The `AvError` subclass every error code is thrown as, by class name. */
+export declare const FRAMEWORK_ERROR_CLASS_OF: {
+    readonly A2000: "AvProtocolError";
+    readonly A2001: "AvProtocolError";
+    readonly A2002: "AvProtocolError";
+    readonly A2003: "AvNotFoundError";
+    readonly A2004: "AvValidationError";
+    readonly A2005: "AvContractMismatchError";
+    readonly A2006: "AvProtocolError";
+    readonly A2007: "AvValidationError";
+    readonly A2008: "AvConflictError";
+    readonly A2009: "AvValidationError";
+    readonly A2010: "AvProtocolError";
+    readonly A2011: "AvProtocolError";
+    readonly A2012: "AvProtocolError";
+    readonly A2013: "AvConflictError";
+    readonly A2014: "AvConflictError";
+    readonly A3000: "AvInternalError";
+    readonly A3001: "AvInternalError";
+    readonly A3002: "AvInternalError";
+    readonly A3003: "AvInternalError";
+    readonly A3004: "AvInternalError";
+    readonly A4000: "AvAuthError";
+    readonly A4001: "AvAuthError";
+    readonly A4002: "AvAuthError";
+};
+/** The name of one `AvError` subclass. */
+export type AvErrorClassName = (typeof FRAMEWORK_ERROR_CLASS_OF)[AvOperationErrorCode];
+/** The error codes `AvError` subclass `N` is thrown for. */
+export type AvErrorCodeOf<N extends AvErrorClassName> = {
+    readonly [C in AvOperationErrorCode]: (typeof FRAMEWORK_ERROR_CLASS_OF)[C] extends N ? C : never;
+}[AvOperationErrorCode];

package/dist/runtime/framework-error-class.table.js

@@ -0,0 +1,25 @@
+export const FRAMEWORK_ERROR_CLASS_OF = {
+    A2000: "AvProtocolError",
+    A2001: "AvProtocolError",
+    A2002: "AvProtocolError",
+    A2003: "AvNotFoundError",
+    A2004: "AvValidationError",
+    A2005: "AvContractMismatchError",
+    A2006: "AvProtocolError",
+    A2007: "AvValidationError",
+    A2008: "AvConflictError",
+    A2009: "AvValidationError",
+    A2010: "AvProtocolError",
+    A2011: "AvProtocolError",
+    A2012: "AvProtocolError",
+    A2013: "AvConflictError",
+    A2014: "AvConflictError",
+    A3000: "AvInternalError",
+    A3001: "AvInternalError",
+    A3002: "AvInternalError",
+    A3003: "AvInternalError",
+    A3004: "AvInternalError",
+    A4000: "AvAuthError",
+    A4001: "AvAuthError",
+    A4002: "AvAuthError",
+};

package/dist/runtime/framework-error.d.ts

@@ -1,10 +1,82 @@
-import type { Cause, OperationErrorCode } from "./operation-response.js";
+import type { AvErrorCodeOf } from "./framework-error-class.table.js";
+import type { AvCause, AvOperationErrorCode } from "./operation-response.js";
 /**
- * Throw from a pipeline, behavior or Adapter to answer the request with one
- * framework error code and cause.
+ * Throw from a pipeline, compute stage or Adapter to answer the request with one
+ * framework error code and cause. Every in-process call that fails
+ * (`framework.application`, `framework.client`, `framework.transaction`, a ctx
+ * call) throws one too, as the subclass of its code's class:
+ * {@link AvValidationError}, {@link AvNotFoundError}, {@link AvConflictError},
+ * {@link AvAuthError}, {@link AvInternalError}, {@link AvProtocolError} or
+ * {@link AvContractMismatchError}. Branch on the class or on `code`, never on the
+ * message.
+ *
+ * For any code outside `A3xxx`, `cause.message` is sent to the caller exactly as
+ * written: put nothing in it you would not show the caller (no database text,
+ * SQL, stack, path or secret). So is each issue's `message`, when your own code
+ * (a pipe, guard, hook, interceptor, filter or compute stage) throws it and it is not
+ * blank and at most 1,000 characters; otherwise, and for an issue an Adapter
+ * throws, the caller receives the framework's own text for the issue's code. An
+ * issue's `code` must be a validation code (`V1000` and up) and its `path` must
+ * name a member of the request's own arguments, or the issue, or the path, is
+ * not sent. For an `A3xxx` code the caller receives the framework's generic
+ * message instead, and nothing of the cause; the error itself reaches the root
+ * `diagnostics` sink once, marked `deliberate: true`.
  */
-export declare class FrameworkError extends Error {
-    readonly code: OperationErrorCode;
-    readonly cause: Cause;
-    constructor(code: OperationErrorCode, cause: Cause | string);
+export declare class AvError<C extends AvOperationErrorCode = AvOperationErrorCode> extends Error {
+    readonly name: string;
+    /** The outcome code. Branch on this, never on the message. */
+    readonly code: C;
+    /** The cause: its message, and its issues or failing step when there are any. */
+    readonly cause: AvCause;
+    constructor(code: C, cause: AvCause | string);
+}
+/**
+ * The request broke a Contract rule: a field, type, capability, projection,
+ * reference or limit. The cause's issues say which, by code and path. Thrown for
+ * A2004, A2007 and A2009.
+ */
+export declare class AvValidationError extends AvError<AvErrorCodeOf<"AvValidationError">> {
+    readonly name: string;
+}
+/** A strict unique target does not exist. Thrown for A2003. */
+export declare class AvNotFoundError extends AvError<AvErrorCodeOf<"AvNotFoundError">> {
+    readonly name: string;
+}
+/**
+ * The operation conflicted with stored state, and nothing was written. A2008
+ * fails the same way if sent again; A2013 and A2014 may succeed if sent again,
+ * and no retry is automatic. Thrown for A2008, A2013 and A2014.
+ */
+export declare class AvConflictError extends AvError<AvErrorCodeOf<"AvConflictError">> {
+    readonly name: string;
+}
+/**
+ * The caller is not authenticated, or is not permitted to run the operation.
+ * Thrown for A4000, A4001 and A4002.
+ */
+export declare class AvAuthError extends AvError<AvErrorCodeOf<"AvAuthError">> {
+    readonly name: string;
+}
+/**
+ * The server failed. Nothing in its cause is actionable; the diagnostics are in
+ * the `diagnostics` sink. Thrown for A3000 to A3004.
+ */
+export declare class AvInternalError extends AvError<AvErrorCodeOf<"AvInternalError">> {
+    readonly name: string;
+}
+/**
+ * The request was not one the server could route or interpret: an unknown
+ * Resource or operation, a protocol version it does not speak, or a body, media
+ * type, size or method it refuses. Thrown for A2000, A2001, A2002, A2006, A2010,
+ * A2011 and A2012.
+ */
+export declare class AvProtocolError extends AvError<AvErrorCodeOf<"AvProtocolError">> {
+    readonly name: string;
+}
+/**
+ * The caller's ClientContract hash is not the one the server serves (a stale
+ * generated client). Thrown for A2005.
+ */
+export declare class AvContractMismatchError extends AvError<AvErrorCodeOf<"AvContractMismatchError">> {
+    readonly name: string;
 }

package/dist/runtime/framework-error.factory.d.ts

@@ -0,0 +1,4 @@
+import { type AvError } from "./framework-error.js";
+import type { AvOperationFailureResponse } from "./operation-response.js";
+/** The `AvError` subclass a failure response throws in process, with its code and cause. */
+export declare function thrownFailure(response: AvOperationFailureResponse): AvError;

package/dist/runtime/framework-error.factory.js

@@ -0,0 +1,15 @@
+import { AvAuthError, AvConflictError, AvContractMismatchError, AvInternalError, AvNotFoundError, AvProtocolError, AvValidationError, } from "./framework-error.js";
+import { FRAMEWORK_ERROR_CLASS_OF, } from "./framework-error-class.table.js";
+const ERROR_CLASSES = {
+    AvAuthError,
+    AvConflictError,
+    AvContractMismatchError,
+    AvInternalError,
+    AvNotFoundError,
+    AvProtocolError,
+    AvValidationError,
+};
+export function thrownFailure(response) {
+    const ErrorClass = ERROR_CLASSES[FRAMEWORK_ERROR_CLASS_OF[response.code]];
+    return new ErrorClass(response.code, response.cause);
+}

package/dist/runtime/framework-error.js

@@ -1,11 +1,32 @@
-export class FrameworkError extends Error {
+export class AvError extends Error {
+    name = "AvError";
     code;
     cause;
     constructor(code, cause) {
         const normalizedCause = typeof cause === "string" ? { message: cause } : cause;
         super(normalizedCause.message);
-        this.name = "FrameworkError";
         this.code = code;
         this.cause = normalizedCause;
     }
 }
+export class AvValidationError extends AvError {
+    name = "AvValidationError";
+}
+export class AvNotFoundError extends AvError {
+    name = "AvNotFoundError";
+}
+export class AvConflictError extends AvError {
+    name = "AvConflictError";
+}
+export class AvAuthError extends AvError {
+    name = "AvAuthError";
+}
+export class AvInternalError extends AvError {
+    name = "AvInternalError";
+}
+export class AvProtocolError extends AvError {
+    name = "AvProtocolError";
+}
+export class AvContractMismatchError extends AvError {
+    name = "AvContractMismatchError";
+}

package/dist/runtime/interceptor-next.error.d.ts

@@ -0,0 +1,5 @@
+/** What the diagnostics channel receives when an operation interceptor calls `next()` twice. */
+export declare class AvInterceptorNextError extends Error {
+    readonly name = "AvInterceptorNextError";
+    constructor();
+}

package/dist/runtime/interceptor-next.error.js

@@ -0,0 +1,6 @@
+export class AvInterceptorNextError extends Error {
+    name = "AvInterceptorNextError";
+    constructor() {
+        super("An interceptor called next() more than once; next() runs the operation once.");
+    }
+}

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

@@ -1,7 +1,7 @@
 /**
  * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * A `Date`, a `bigint`, a `Uint8Array`, a {@link Decimal}, any other class
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal}, any other class
  * instance and an `undefined` property are refused (`V1001`), as are a
  * non-finite `number` (`V1004`) and a cycle (`V1001`).
  *
@@ -10,6 +10,6 @@
  * A `json` field's value is this without its top-level `null`: a field-level
  * `null` is the field's absence, which only `nullable: true` admits.
  */
-export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
-    readonly [key: string]: JsonValue;
+export type AvJsonValue = string | number | boolean | null | readonly AvJsonValue[] | {
+    readonly [key: string]: AvJsonValue;
 };

package/dist/runtime/level-lifecycle.runtime.d.ts

@@ -0,0 +1,25 @@
+/** One level's lifecycle registrations, as an operation or a transaction level holds them. */
+export type LifecycleLevel<Context> = {
+    readonly hooks: {
+        readonly before: readonly ((context: Context) => unknown)[];
+        readonly after: readonly ((result: unknown, context: Context) => unknown)[];
+    };
+    readonly interceptors: readonly ((context: Context, next: () => Promise<unknown>) => Promise<unknown>)[];
+};
+/**
+ * The record of a `next()` called more than once: the first refusal, kept so a
+ * caller can refuse the whole call even when the interceptor swallowed it.
+ */
+export type NextReuse<Refusal extends Error = Error> = {
+    refusal: Refusal | undefined;
+};
+/**
+ * Runs `levels`' lifecycle around `inner`: every interceptor, outer to inner,
+ * around every before hook, `inner`, and every after hook. `settle` turns what
+ * `inner` or an interceptor below resolved into what the stage above sees (the
+ * operation read-materializes it). An after hook is told a deep-frozen copy of
+ * the result; the result itself goes on to the interceptors, which may answer a
+ * different one. Every `next()` is single use: a second call rejects with
+ * `refuse()`'s error, recorded in `reuse`, and runs nothing.
+ */
+export declare function runLevelLifecycle<Context, Refusal extends Error>(levels: readonly LifecycleLevel<Context>[], context: () => Context, inner: () => Promise<unknown>, settle: (result: unknown) => Promise<unknown>, reuse: NextReuse<Refusal>, refuse: () => Refusal): Promise<unknown>;

package/dist/runtime/level-lifecycle.runtime.js

@@ -0,0 +1,42 @@
+import { frozenCopy } from "./readonly-value.js";
+export async function runLevelLifecycle(levels, context, inner, settle, reuse, refuse) {
+    const once = (run) => {
+        let called = false;
+        return () => {
+            if (called) {
+                const refusal = refuse();
+                reuse.refusal ??= refusal;
+                return Promise.reject(refusal);
+            }
+            called = true;
+            return run();
+        };
+    };
+    const hooked = async () => {
+        for (const level of levels) {
+            for (const hook of level.hooks.before) {
+                await hook(context());
+            }
+        }
+        const result = await settle(await inner());
+        const after = [...levels].reverse().flatMap((level) => level.hooks.after);
+        if (after.length > 0) {
+            const told = frozenCopy(result);
+            for (const hook of after) {
+                await hook(told, context());
+            }
+        }
+        return result;
+    };
+    const interceptors = levels.flatMap((level) => level.interceptors);
+    let next = hooked;
+    for (let index = interceptors.length - 1; index >= 0; index -= 1) {
+        const interceptor = interceptors[index];
+        if (interceptor === undefined) {
+            continue;
+        }
+        const continuation = once(next);
+        next = () => interceptor(context(), async () => settle(await continuation()));
+    }
+    return next();
+}

package/dist/runtime/misuse-reporter.d.ts

@@ -0,0 +1,32 @@
+import type { AvRequestOrigin } from "../config/config-layer.js";
+import type { AvOperationFamily } from "../operations/operation-identity.js";
+/**
+ * One caller value the framework refused because it could not be read
+ * (`"unreadable-value"`: a revoked Proxy, a throwing getter or trap) or is not plain
+ * data (`"non-plain-value"`: a class instance other than `Date`, `AvDecimal` or
+ * `Uint8Array`). The caller received `A2004` with one `V1001` at `path`.
+ *
+ * The operation's identity is present when the framework could read it (absent for
+ * a request whose own envelope could not be read), and `operation` is the step's
+ * index in a transaction plan.
+ */
+export type AvMisuseEvent = {
+    readonly kind: "unreadable-value" | "non-plain-value";
+    /** The issue path the caller received. */
+    readonly path: readonly (string | number)[];
+    readonly origin?: AvRequestOrigin;
+    readonly resource?: string;
+    readonly family?: AvOperationFamily;
+    readonly variant?: string;
+    readonly operation?: number;
+};
+/**
+ * Receives a {@link AvMisuseEvent} for every caller value the framework
+ * refused as unreadable or not plain data. Set once, as the root configuration's
+ * `misuse`. What it returns, throws or rejects with never reaches the response.
+ */
+export type AvMisuseSink = (event: AvMisuseEvent) => void | Promise<void>;
+/** The channel as the runtime holds it: total, never awaited. */
+export type MisuseReporter = (event: AvMisuseEvent) => void;
+/** Binds the configured sink; without one, nothing is observed. */
+export declare function createMisuseReporter(sink: AvMisuseSink | undefined): MisuseReporter;

package/dist/runtime/misuse-reporter.js

@@ -0,0 +1,19 @@
+const IGNORE_MISUSE = () => undefined;
+export function createMisuseReporter(sink) {
+    if (sink === undefined) {
+        return IGNORE_MISUSE;
+    }
+    return (event) => {
+        try {
+            const settled = sink(event);
+            if (typeof settled === "object" &&
+                settled !== null &&
+                typeof settled.then === "function") {
+                settled.then(undefined, () => undefined);
+            }
+        }
+        catch {
+            return;
+        }
+    };
+}

package/dist/runtime/mutation-planner.d.ts

@@ -1,8 +1,9 @@
-import type { FrameworkBehaviorsConfig } from "../config/framework-behaviors-config.js";
-import type { RelationMutationDirective } from "../contracts/capability.js";
-import type { Contract, CoreContract } from "../contracts/contract.js";
+import type { ResolvedComputeConfig } from "../config/field-compute.resolver.js";
+import type { AvRelationMutationDirective } from "../contracts/capability.js";
+import type { AvContract, AvContractCore } from "../contracts/contract.js";
+import type { AvComputeContext } from "./field-compute.js";
+import type { NestedWriteTarget } from "./nested-write.walker.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
-import type { PipelineContext } from "./pipeline.js";
 /**
  * The two Contracts a write reads. The Core Contract decides what the Adapter is asked
  * to store; the active Contract adds the fields its scope declared under
@@ -10,11 +11,11 @@ import type { PipelineContext } from "./pipeline.js";
  * virtual: its behaviours run and its value is stripped before the Adapter call.
  */
 export type WriteContracts = {
-    readonly core: CoreContract;
-    readonly active: Contract;
+    readonly core: AvContractCore;
+    readonly active: AvContract;
 };
 type WriteStage = "create" | "update";
-type ContextFactory = (args: unknown) => PipelineContext;
+type ContextFactory = (args: unknown) => AvComputeContext;
 export type RelationRecordSite = {
     readonly key: string | undefined;
     readonly stage: WriteStage;
@@ -53,9 +54,17 @@ export declare const RELATION_MUTATION_RECORD_SITES: {
  * membership, not an assertion: `Object.prototype` members resolve through the
  * prototype chain and would otherwise reach a site loop with a non-iterable.
  */
-export declare function isRelationMutationDirective(key: string): key is RelationMutationDirective;
-/** Apply effective computed create/update field behavior to post-pipe logical args. */
-export declare function applyWriteFieldBehaviors(contracts: WriteContracts, behaviors: FrameworkBehaviorsConfig | undefined, request: OperationExecutionRequest, args: unknown, contextFactory: ContextFactory): Promise<unknown>;
+export declare function isRelationMutationDirective(key: string): key is AvRelationMutationDirective;
+/** Apply the effective create/update compute stages to the post-pipe logical args. */
+export declare function applyWriteCompute(contracts: WriteContracts, compute: ResolvedComputeConfig | undefined, request: OperationExecutionRequest, args: unknown, contextFactory: ContextFactory): Promise<unknown>;
+/**
+ * Applies each nested target's write compute, in the targets' order, to its
+ * records: `compute.create` on a created row (an `$upsert`'s `create` branch
+ * too), `compute.update` on an updated one. Each target's stages are told
+ * `context(target, payload)`, the nested target's own context. The arguments
+ * are copied where a record changes, never written.
+ */
+export declare function applyNestedWriteCompute(contracts: WriteContracts, compute: ResolvedComputeConfig | undefined, args: unknown, targets: readonly NestedWriteTarget[], context: (target: NestedWriteTarget, payload: unknown) => AvComputeContext): Promise<unknown>;
 /** Strip VIRTUAL scalar input only at the persistence boundary. */
 export declare function stripVirtualMutationInput(contracts: WriteContracts, request: OperationExecutionRequest, args: unknown): Promise<unknown>;
 export {};