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

package/dist/runtime/caller-data.copier.js

@@ -268,7 +268,7 @@ function pathSegment(array, key) {
     }
     return key;
 }
-function mirrorControlData(value) {
+function mirrorControlData(value, members) {
     const shape = reflectNode(value);
     if (shape === undefined) {
         throw new AvCallerDataError("unreadable-value", []);
@@ -375,6 +375,20 @@ function mirrorControlData(value) {
                 continue;
             }
             const memberLink = childLink(link, pathSegment(shape.array, key));
+            const byValue = members?.copyAt(pathOf(memberLink));
+            if (byValue !== undefined) {
+                try {
+                    store(copyCallerData(member, byValue));
+                }
+                catch (error) {
+                    if (!(error instanceof AvCallerDataError)) {
+                        throw error;
+                    }
+                    members?.refused(pathOf(memberLink), error);
+                    store(undefined);
+                }
+                continue;
+            }
             const memberShape = reflectNode(member);
             if (memberShape === undefined) {
                 store(UNREADABLE);
@@ -408,6 +422,9 @@ function mirrorControlData(value) {
     }
     return root;
 }
+export function mirrorCallerData(value, members) {
+    return mirrorControlData(value, members);
+}
 export function locateCallerDataError(error, copy) {
     const within = error.within;
     if (within === undefined) {

package/dist/runtime/caller-data.door.d.ts

@@ -6,13 +6,19 @@ import type { AvMisuseEvent, MisuseReporter } from "./misuse-reporter.js";
  *
  * - `"caller"`: a server-side caller's own objects — copied at the door.
  * - `"owned"`: data no caller holds a reference to — a body the protocol decoder
- *   parsed with `JSON.parse` for this request alone, or a plan the typed runner
- *   assembled from copies its builders took. It is never copied again.
+ *   parsed with `JSON.parse` for this request alone, a host's parsed body the
+ *   protocol's shortcut copied at the call, or a plan the typed runner assembled
+ *   from copies its builders took. It is never copied again.
  *
- * Only core's own modules choose `"owned"`: the public `framework.execute` and
- * `executeTransaction` always pass `"caller"`.
+ * - `{ refused }`: a body the protocol's shortcut copied at the call, whose copy
+ *   failed — answered at the door as `"caller"` would answer it, never read again.
+ *
+ * Only core's own modules choose anything but `"caller"`: the public
+ * `framework.execute` and `executeTransaction` always pass `"caller"`.
  */
-export type ArgumentsSource = "caller" | "owned";
+export type ArgumentsSource = "caller" | "owned" | {
+    readonly refused: AvCallerDataError;
+};
 /** The operation identity a misuse event may name, as far as it could be read. */
 export type MisuseIdentity = Omit<AvMisuseEvent, "kind" | "path">;
 /**

package/dist/runtime/computed-read-runtime.js

@@ -1,5 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { AvComputedValueError } from "./computed-value.error.js";
+import { frozenCopy } from "./readonly-value.js";
 import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -36,6 +37,12 @@ function appendUniqueProjection(values, value) {
         values.push(value);
     }
 }
+function adapterIdentifier(model, resource) {
+    const resources = model.resources;
+    return ((Object.hasOwn(resources, resource)
+        ? resources[resource]?.identifiers?.[0]
+        : undefined) ?? []);
+}
 function supportsProjection(request) {
     if (request.family === "upsert") {
         return true;
@@ -51,6 +58,11 @@ function addScalarProjection(core, model, active, compute, resourceName, fieldNa
     const stage = readCompute(compute?.[resourceName]?.[fieldName]?.read);
     if (stage !== undefined) {
         appendUnique(computed, fieldName);
+        if (stage.dependsOn.length === 0) {
+            for (const member of adapterIdentifier(model, resourceName)) {
+                appendUniqueProjection(adapterSelect, member);
+            }
+        }
         for (const dependency of stage.dependsOn) {
             if (storedScalar(model, resourceName, dependency)) {
                 appendUniqueProjection(adapterSelect, dependency);
@@ -307,10 +319,11 @@ async function materializeRecord(active, compute, request, plan, value, contextF
         if (field?.kind !== "scalar" || stage === undefined) {
             continue;
         }
+        const view = frozenCopy(record);
         const computedValue = await stage.compute({
             field: fieldName,
-            value: record[fieldName],
-            record,
+            value: view[fieldName],
+            record: view,
             ctx: contextFactory(),
         });
         if (computedValue === undefined) {

package/dist/runtime/computed-value.error.d.ts

@@ -1,7 +1,8 @@
 import type { AvValidationIssue } from "../operations/validation-code.js";
 /**
  * What the diagnostics channel receives when a computed value — a read or write
- * compute stage's return — is one its Contract refuses: the developer's broken code,
+ * compute stage's return — is one its Contract refuses, or a `compute.create`
+ * stage returned `undefined` for a field a create cannot do without (rc.2): the developer's broken code,
  * never the caller's. It is thrown, not a deliberate outcome, so the framework's
  * boundary answers the caller the generic `A3000` and reports this error, with the
  * issues, exactly once.
@@ -9,5 +10,5 @@ import type { AvValidationIssue } from "../operations/validation-code.js";
 export declare class AvComputedValueError extends Error {
     readonly issues: readonly AvValidationIssue[];
     readonly name = "AvComputedValueError";
-    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly AvValidationIssue[]);
+    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly AvValidationIssue[], message?: string);
 }

package/dist/runtime/computed-value.error.js

@@ -1,9 +1,10 @@
 export class AvComputedValueError extends Error {
     issues;
     name = "AvComputedValueError";
-    constructor(resource, field, stage, issues) {
+    constructor(resource, field, stage, issues, message) {
         const [first] = issues;
-        super(`The compute.${stage} stage of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
+        super(message ??
+            `The compute.${stage} stage of ${resource}.${field} returned a value its Contract refuses${first === undefined ? "." : ` (${first.code}: ${first.message})`}`);
         this.issues = issues;
     }
 }

package/dist/runtime/create-requirement.d.ts

@@ -1,20 +1,32 @@
 import type { AvContract } from "../contracts/contract.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
 import type { AvOperationIdentity } from "../operations/operation-identity.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
 import type { ReferentialActionTable } from "./referential-action.js";
 type Path = readonly (string | number)[];
+/** One required field a `compute.create` stage was to fill and left missing. */
+export type ComputedRequirementGap = {
+    readonly resource: string;
+    readonly field: string;
+    readonly issue: AvValidationIssue;
+};
 /**
- * What the Adapter stated beside its model that the check reads: its
- * referential edges, for the fields that hold each reference. Read once when
- * the Framework is constructed. The requirements themselves are the active
- * Contract's.
+ * What the Adapter stated that the checks read: its referential edges, for the
+ * fields that hold each reference, and its own create requirements per
+ * Resource, before any layer projected them (what write compute must not leave
+ * missing). Read once when the Framework is constructed. The requirements the
+ * caller is held to are the active Contract's.
  */
 export type RecordWriteFacts = {
     readonly references: ReferentialActionTable;
+    readonly stated: (resource: string) => AvCreateRequirements | undefined;
 };
 /** The facts an Adapter stated, read off it once; an absent table states nothing. */
 export declare function recordWriteFactsOf(adapter: {
     readonly referentialActions?: ReferentialActionTable;
+    readonly model?: {
+        readonly resources: Readonly<Record<string, unknown>>;
+    };
 }): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
@@ -24,7 +36,31 @@ export declare function recordWriteFactsOf(adapter: {
  * reference both, in argument order. Empty when there are none. Total over
  * malformed input.
  */
-export declare function createRequirementIssues(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
+export declare function createRequirementIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
     readonly resource: string;
 }, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * The `V1000` issues for every create position of one operation's arguments
+ * that lacks a value the active Contract requires, and the `V1012` issues for
+ * every write record that sets a relation and its reference both, on the
+ * arguments as the caller sent them, before any pipeline stage runs. Empty when
+ * there are none.
+ */
+export declare function preliminaryRecordIssues(contract: AvContract, facts: Pick<RecordWriteFacts, "references">, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path): readonly AvValidationIssue[];
+/**
+ * Every required field a `compute.create` stage was to fill and that is still
+ * missing after write compute, at every create position of one operation's
+ * arguments (`create.*`'s `data`, `upsert`'s `create`, every nested create),
+ * in argument order, read against the Adapter's own statement of each
+ * Resource's create requirements; `computed` names the fields a Resource's
+ * `compute.create` stages fill.
+ * A field the parent supplies to a nested create, a group whose relation the
+ * record writes, and a value the caller sent are not missing. Empty when
+ * nothing is.
+ */
+export declare function computedRequirementGapsOf(contract: AvContract, facts: RecordWriteFacts, request: AvOperationIdentity & {
+    readonly resource: string;
+}, args: unknown, argumentsPath: Path, computed: (resource: string) => ReadonlySet<string>): readonly ComputedRequirementGap[];
 export {};

package/dist/runtime/create-requirement.js

@@ -1,6 +1,6 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { advertisedDirectivesAt } from "../contracts/field.js";
-import { NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
+import { LOOPBACK_WRITE_SCOPE, NESTED_WRITE_SCOPE, resolveWriteScope, } from "../operations/write-scope.resolver.js";
 import { isRelationMutationDirective, RELATION_MUTATION_RECORD_SITES, } from "./mutation-planner.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -63,9 +63,19 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
     if (!isRecord(record)) {
         return;
     }
+    if (context.computed !== undefined) {
+        computedRequirementGaps(context, resource, record, path, via);
+        walkNestedCreates(context, resource, record, path);
+        return;
+    }
     const { contract, issues } = context;
-    const conflicted = referenceConflicts(context, resource, record, path);
-    mixedReferenceWrites(context, resource, record, path, conflicted);
+    const looped = loopbackWrites(context, resource, record, path, via, "create");
+    const conflicted = looped.size > 0
+        ? looped
+        : referenceConflicts(context, resource, record, path);
+    if (looped.size === 0) {
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
     const requirements = requirementsOf(contract, resource);
     if (requirements !== undefined) {
         const supplied = suppliedThrough(requirements, via);
@@ -157,14 +167,93 @@ function mixedReferenceWrites(context, resource, record, path, conflicted) {
         });
     }
 }
-function checkUpdateRecord(context, resource, record, path) {
+function checkUpdateRecord(context, resource, record, path, via) {
     if (!isRecord(record)) {
         return;
     }
-    const conflicted = referenceConflicts(context, resource, record, path);
-    mixedReferenceWrites(context, resource, record, path, conflicted);
+    if (context.computed === undefined &&
+        loopbackWrites(context, resource, record, path, via, "update").size === 0) {
+        const conflicted = referenceConflicts(context, resource, record, path);
+        mixedReferenceWrites(context, resource, record, path, conflicted);
+    }
     walkNestedCreates(context, resource, record, path);
 }
+function loopbackWrites(context, resource, record, path, via, stage) {
+    const refused = new Set();
+    if (via === undefined) {
+        return refused;
+    }
+    const { contract } = context;
+    const edge = lookupField(lookupResource(contract, via.resource), via.relation);
+    if (edge?.kind !== "relation" || typeof edge.inverse !== "string") {
+        return refused;
+    }
+    const inverse = edge.inverse;
+    const other = lookupField(lookupResource(contract, resource), inverse);
+    if (other?.kind === "relation" &&
+        advertisedDirectivesAt(other.capabilities[stage], LOOPBACK_WRITE_SCOPE) !==
+            undefined) {
+        return refused;
+    }
+    const references = edgesOf(context.references, resource).find((candidate) => candidate.field === inverse) ?? undefined;
+    for (const field of [
+        inverse,
+        ...(references === undefined ? [] : referencesOf(references)),
+    ]) {
+        if (!written(record, field)) {
+            continue;
+        }
+        refused.add(field);
+        context.issues.push({
+            code: "V1012",
+            path: [...path, field],
+            message: field === inverse
+                ? `Relation "${field}" is the relation this ${resource} is written through, from its other end ("${via.resource}.${via.relation}"): the write it sits in supplies it.`
+                : `Field "${field}" holds the reference of "${inverse}", the relation this ${resource} is written through ("${via.resource}.${via.relation}"): the write it sits in supplies it.`,
+        });
+    }
+    return refused;
+}
+function computedRequirementGaps(context, resource, record, path, via) {
+    const reader = context.computed;
+    const computed = reader?.computed(resource);
+    const stated = reader?.stated(resource);
+    if (computed === undefined || computed.size === 0 || stated === undefined) {
+        return;
+    }
+    const supplied = suppliedThrough(stated, via);
+    const gap = (field) => {
+        context.gaps?.push({
+            resource,
+            field,
+            issue: {
+                code: "V1000",
+                path: [...path, field],
+                message: `compute.create on ${resource}.${field} returned undefined for a required field.`,
+            },
+        });
+    };
+    for (const field of namesOf(stated.required)) {
+        if (computed.has(field) &&
+            !supplied.has(field) &&
+            !written(record, field)) {
+            gap(field);
+        }
+    }
+    const groups = Array.isArray(stated.oneOf) ? stated.oneOf : [];
+    for (const group of groups) {
+        const [relation, ...references] = namesOf(group);
+        const left = references.find((field) => computed.has(field) && !written(record, field));
+        if (relation === undefined ||
+            left === undefined ||
+            supplied.has(relation) ||
+            references.some((field) => supplied.has(field)) ||
+            written(record, relation)) {
+            continue;
+        }
+        gap(left);
+    }
+}
 function walkNestedCreates(context, resource, record, path) {
     if (!isRecord(record)) {
         return;
@@ -196,7 +285,7 @@ function walkNestedCreates(context, resource, record, path) {
                         checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
                     }
                     else {
-                        checkUpdateRecord(context, field.target, siteRecord, sitePath);
+                        checkUpdateRecord(context, field.target, siteRecord, sitePath, via);
                     }
                 }
             }
@@ -204,17 +293,52 @@ function walkNestedCreates(context, resource, record, path) {
     }
 }
 export function recordWriteFactsOf(adapter) {
-    return { references: adapter.referentialActions ?? {} };
+    const resources = adapter.model?.resources ?? {};
+    return {
+        references: adapter.referentialActions ?? {},
+        stated: (resource) => {
+            const found = Object.hasOwn(resources, resource)
+                ? resources[resource]
+                : undefined;
+            const stated = isRecord(found) ? found.createRequirements : undefined;
+            return isRecord(stated) ? stated : undefined;
+        },
+    };
 }
 export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
-    if (!isRecord(args)) {
-        return [];
-    }
     const context = {
         contract,
         references: facts.references,
         issues: [],
     };
+    walkOperation(context, request, args, argumentsPath);
+    return context.issues;
+}
+export function preliminaryRecordIssues(contract, facts, request, args, argumentsPath) {
+    const context = {
+        contract,
+        references: facts.references,
+        issues: [],
+    };
+    walkOperation(context, request, args, argumentsPath);
+    return context.issues;
+}
+export function computedRequirementGapsOf(contract, facts, request, args, argumentsPath, computed) {
+    const gaps = [];
+    walkOperation({
+        contract,
+        references: facts.references,
+        issues: [],
+        computed: { stated: facts.stated, computed },
+        gaps,
+    }, request, args, argumentsPath);
+    return gaps;
+}
+function walkOperation(context, request, args, argumentsPath) {
+    if (!isRecord(args)) {
+        return;
+    }
+    const contract = context.contract;
     const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
     if (request.family === "create" && written(args, "data")) {
         const data = args.data;
@@ -229,16 +353,9 @@ export function createRequirementIssues(contract, facts, request, args, argument
     }
     if (request.family === "upsert") {
         checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
-        checkUpdateRecord(context, request.resource, args.update, [
-            ...argumentsPath,
-            "update",
-        ]);
+        checkUpdateRecord(context, request.resource, args.update, [...argumentsPath, "update"], undefined);
     }
     if (request.family === "update") {
-        checkUpdateRecord(context, request.resource, args.data, [
-            ...argumentsPath,
-            "data",
-        ]);
+        checkUpdateRecord(context, request.resource, args.data, [...argumentsPath, "data"], undefined);
     }
-    return context.issues;
 }

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

@@ -47,7 +47,8 @@ export type AvTransactionDiagnostic = {
 };
 /**
  * One unplanned failure of the MCP endpoint itself, outside any tool call's
- * operation: the raw error, answered `500` with no detail.
+ * operation: the raw error, answered `500` with no detail, or `401` when it is
+ * the throw of `mcp.authorization.verify`.
  */
 export type AvMcpDiagnostic = {
     readonly kind: "mcp";

package/dist/runtime/error-boundary.js

@@ -1,3 +1,4 @@
+import { isDatabaseRefusalMessage } from "../operations/database-refusal.js";
 import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
 import { AvError } from "./framework-error.js";
 import { INTERNAL_FAILURE_MESSAGE, internalFailure, OPERATION_CODES, operationFailure, } from "./operation-response.js";
@@ -164,6 +165,9 @@ function projectIssue(value, unvouched, view, author) {
             unvouched.push(supplied);
         }
     }
+    else if (isDatabaseRefusalMessage(code, supplied)) {
+        message = supplied;
+    }
     if (rawPath === undefined) {
         return { code, message };
     }

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

@@ -0,0 +1,12 @@
+/** Why a code is answered, and what the one who meets it should do. */
+export type ErrorCodeGuidance = {
+    /** What typically produced the code, in a sentence or two. */
+    readonly cause: string;
+    /** What to change so it does not happen again. */
+    readonly fix: string;
+};
+/** Guidance for a code whose table holds no message of its own. */
+export type ErrorCodeDescription = ErrorCodeGuidance & {
+    /** The code's meaning, in one short sentence. */
+    readonly message: string;
+};

package/dist/runtime/error-guidance.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/error.catalog.d.ts

@@ -0,0 +1,49 @@
+import type { AvAdapterDiscoveryDiagnosticCode } from "../adapters/adapter-discovery-diagnostic.js";
+import type { AvContractCompilerDiagnosticCode } from "../compiler/contract-compiler-diagnostic.js";
+import type { AvConfigDiagnosticCode } from "../config/config-diagnostic.js";
+import type { AvConstructionStage } from "../framework/framework-construction.error.js";
+import { type AvValidationCode } from "../operations/validation-code.js";
+import { type AvOperationCode } from "./operation-response.js";
+/**
+ * The documentation page every catalog entry links into. Each code has its own
+ * anchor there: the code in lower case (`#a2004`, `#config_required`).
+ */
+export declare const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+/**
+ * What kind of code an entry is: an outcome code's family (`success` `A1xxx`,
+ * `request` `A2xxx`, `internal` `A3xxx`, `auth` `A4xxx`), a `validation` issue
+ * code (`V1xxx`), or a startup code, by the construction stage that reports it.
+ */
+export type AvErrorKind = "success" | "request" | "internal" | "auth" | "validation" | AvConstructionStage;
+/** Every code the catalog describes: outcome, validation and startup codes. */
+export type AvErrorCatalogCode = AvOperationCode | AvValidationCode | AvConfigDiagnosticCode | AvAdapterDiscoveryDiagnosticCode | AvContractCompilerDiagnosticCode;
+/** One code: what it means, why it happens, what to do, and where it is documented. */
+export type AvErrorCatalogEntry<C extends AvErrorCatalogCode = AvErrorCatalogCode> = {
+    readonly code: C;
+    readonly kind: AvErrorKind;
+    /** Its meaning in one sentence; for a V-code, the framework's message for it. */
+    readonly message: string;
+    /** What typically produces it. */
+    readonly cause: string;
+    /** What to change. */
+    readonly fix: string;
+    /** Its entry on the error-codes page. */
+    readonly docs: string;
+};
+/** The error catalog's type: one entry per code. */
+export type AvErrorCatalog = {
+    readonly [C in AvErrorCatalogCode]: AvErrorCatalogEntry<C>;
+};
+/** The documentation URL of one code: the error-codes page at its anchor. */
+export declare function errorDocsUrl(code: AvErrorCatalogCode): string;
+/**
+ * Every code Aventara answers or refuses with, by code: its `kind`, `message`,
+ * `cause`, `fix` and `docs` URL. An operation's `code`, a validation issue's
+ * `code` and a startup diagnostic's `code` are all keys of it:
+ *
+ * ```ts
+ * AvErrorCatalog[error.code].fix;
+ * AvErrorCatalog.V1000.docs; // https://aventara-framework.vercel.app/docs/error-codes#v1000
+ * ```
+ */
+export declare const AvErrorCatalog: AvErrorCatalog;

package/dist/runtime/error.catalog.js

@@ -0,0 +1,49 @@
+import { ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE } from "../adapters/adapter-discovery-diagnostic.guidance.js";
+import { CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE } from "../compiler/contract-compiler-diagnostic.guidance.js";
+import { CONFIG_DIAGNOSTIC_GUIDANCE } from "../config/config-diagnostic.guidance.js";
+import { VALIDATION_CODE_GUIDANCE } from "../operations/validation-code.guidance.js";
+import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
+import { OPERATION_CODE_GUIDANCE } from "./operation-code.guidance.js";
+import { OPERATION_CODES } from "./operation-response.js";
+export const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+export function errorDocsUrl(code) {
+    return `${ERROR_CODES_DOCS_URL}#${code.toLowerCase()}`;
+}
+const OUTCOME_KIND = {
+    "1": "success",
+    "2": "request",
+    "3": "internal",
+    "4": "auth",
+};
+function entry(code, kind, description) {
+    return Object.freeze({
+        code,
+        kind,
+        message: description.message,
+        cause: description.cause,
+        fix: description.fix,
+        docs: errorDocsUrl(code),
+    });
+}
+function entriesOf(table, kind) {
+    return Object.keys(table).map((code) => [
+        code,
+        entry(code, kind, table[code]),
+    ]);
+}
+export const AvErrorCatalog = Object.freeze(Object.fromEntries([
+    ...OPERATION_CODES.map((code) => [
+        code,
+        entry(code, OUTCOME_KIND[code[1]], OPERATION_CODE_GUIDANCE[code]),
+    ]),
+    ...VALIDATION_CODES.map((code) => [
+        code,
+        entry(code, "validation", {
+            message: VALIDATION_CODE_MESSAGES[code],
+            ...VALIDATION_CODE_GUIDANCE[code],
+        }),
+    ]),
+    ...entriesOf(CONFIG_DIAGNOSTIC_GUIDANCE, "configuration"),
+    ...entriesOf(ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE, "discovery"),
+    ...entriesOf(CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE, "contract-compilation"),
+]));

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

@@ -6,6 +6,8 @@ export type Path = readonly (string | number)[];
 type UnknownRecord = Readonly<Record<string, unknown>>;
 /** A plain object: what a write record, or a directive's operand, is. */
 export declare function isPlainRecord(value: unknown): value is UnknownRecord;
+/** The containers a family writes, by argument key. */
+export declare const WRITE_KEYS: Readonly<Partial<Record<AvOperationFamily, readonly string[]>>>;
 /** The fields of `resource` with stages, in the Resource's field order. */
 export declare function stagedFieldsOf(contract: AvContract, resource: string, stages: Readonly<Record<string, ResolvedFieldStages>>, kind: "pipes" | "guards"): readonly string[];
 /** The value at `path` in `args`, or `undefined` when nothing is there. */

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

@@ -1,3 +1,4 @@
+import { frozenCopy } from "./readonly-value.js";
 export function isPlainRecord(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         return false;
@@ -5,7 +6,7 @@ export function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-const WRITE_KEYS = {
+export const WRITE_KEYS = {
     create: ["data"],
     update: ["data"],
     upsert: ["create", "update"],
@@ -104,9 +105,12 @@ export async function pipeSentFields(stages, fields, records, args, select) {
             }
             let value = record[field];
             for (const pipe of stages[field]?.pipes ?? []) {
-                const next = await pipe(value);
+                const told = frozenCopy(value);
+                const next = await pipe(told);
                 if (next !== undefined) {
-                    value = next;
+                    if (next !== told) {
+                        value = next;
+                    }
                     changed = true;
                 }
             }
@@ -133,7 +137,7 @@ export async function guardSentFields(stages, fields, records, args, context) {
             }
             for (const guard of stages[field]?.guards ?? []) {
                 const told = context();
-                if ((await guard(record[field], told)) === false) {
+                if ((await guard(frozenCopy(record[field]), told)) === false) {
                     return false;
                 }
             }

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

@@ -1,11 +1,28 @@
 import type { AvContract } from "../contracts/contract.js";
 import type { AvValidationIssue } from "../operations/validation-code.js";
+import { AvComputedValueError } from "./computed-value.error.js";
 import { type Path } from "./field-stage.runtime.js";
 import type { OperationExecutionRequest } from "./operation-request.js";
 import type { ReferentialActionTable } from "./referential-action.js";
+/** The write phase of a record: a created row (an upsert's `create` branch too) or an updated one. */
+export type WriteStage = "create" | "update";
+/**
+ * The fields a judgment leaves for later: a plan step's (or a forced call's)
+ * literal values are judged before BEGIN, except a field a write compute stage
+ * of that phase may still change, which is judged after write compute.
+ */
+export type DeferredField = (resource: string, stage: WriteStage, field: string) => boolean;
 /**
  * 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[];
+export declare function fieldValidatorIssues(contract: AvContract, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path, select: (path: Path) => boolean, deferred?: DeferredField): readonly AvValidationIssue[];
+/**
+ * The server's defect when a value written to a field the active layer hides
+ * breaks its validators or its Json shape, or `undefined`.
+ */
+export declare function hiddenFieldRefusal(contracts: {
+    readonly core: AvContract;
+    readonly active: AvContract;
+}, references: ReferentialActionTable, request: OperationExecutionRequest, args: unknown, argumentsPath: Path): AvComputedValueError | undefined;