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

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

@@ -0,0 +1,65 @@
+import { parseOperationIdentity } from "../operations/operation-identity.js";
+import { validationIssue } from "../operations/validation-code.js";
+import { CallerDataError, copyCallerData, } from "./caller-data.copier.js";
+export function misuseIdentityOf(request) {
+    const origin = request.origin === "application" || request.origin === "client"
+        ? request.origin
+        : undefined;
+    const identity = typeof request.family === "string" && typeof request.variant === "string"
+        ? parseOperationIdentity(request.family, request.variant)
+        : undefined;
+    return {
+        ...(origin === undefined ? {} : { origin }),
+        ...(typeof request.resource === "string"
+            ? { resource: request.resource }
+            : {}),
+        ...(identity === undefined
+            ? {}
+            : { family: identity.family, variant: identity.variant }),
+    };
+}
+export function refuseCallerData(error, address, identity, misuse) {
+    const path = [...address, ...error.path];
+    misuse({ kind: error.kind, path, ...identity });
+    return validationIssue("V1001", path, error.message);
+}
+export function copyAtDoor(value, policy) {
+    try {
+        return { ok: true, value: copyCallerData(value, policy) };
+    }
+    catch (error) {
+        if (error instanceof CallerDataError) {
+            return { ok: false, error };
+        }
+        throw error;
+    }
+}
+export function copyEnvelopeAtDoor(request, members) {
+    const shallow = copyAtDoor(request, {
+        keep: (value) => value !== request,
+    });
+    if (!shallow.ok ||
+        typeof shallow.value !== "object" ||
+        shallow.value === null ||
+        Array.isArray(shallow.value)) {
+        return shallow;
+    }
+    const envelope = shallow.value;
+    for (const member of members) {
+        if (!Object.hasOwn(envelope, member)) {
+            continue;
+        }
+        const copy = copyAtDoor(envelope[member]);
+        if (!copy.ok) {
+            return {
+                ok: false,
+                error: new CallerDataError(copy.error.kind, [
+                    member,
+                    ...copy.error.path,
+                ]),
+            };
+        }
+        envelope[member] = copy.value;
+    }
+    return { ok: true, value: envelope };
+}

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

@@ -1,6 +1,5 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
-import { FrameworkError } from "./framework-error.js";
-import { INTERNAL_FAILURE_MESSAGE } from "./operation-response.js";
+import { ComputedValueError } from "./computed-value.error.js";
 import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -274,12 +273,6 @@ export function planReadOperation(core, active, behaviors, request, args) {
         materialize: defaults.plan.computed.length > 0,
     };
 }
-function behaviorFailure(issues) {
-    throw new FrameworkError("A3000", {
-        message: INTERNAL_FAILURE_MESSAGE,
-        issues,
-    });
-}
 async function materializeRelation(active, behaviors, request, relation, value, contextFactory) {
     if (value === null || value === undefined) {
         return value;
@@ -308,7 +301,7 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
             continue;
         }
         const computedValue = await behavior.compute({
-            scope: request.scope,
+            origin: request.origin,
             resource: plan.resource,
             field: fieldName,
             value: record[fieldName],
@@ -320,7 +313,7 @@ async function materializeRecord(active, behaviors, request, plan, value, contex
         }
         const validation = normalizeScalarFieldValue(active, field, computedValue, "runtime", ["behaviors", plan.resource, fieldName, "read"]);
         if (!validation.ok) {
-            behaviorFailure(validation.issues);
+            throw new ComputedValueError(plan.resource, fieldName, "read", validation.issues);
         }
         record[fieldName] = validation.value;
     }

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

@@ -0,0 +1,13 @@
+import type { ValidationIssue } from "../operations/validation-code.js";
+/**
+ * What the diagnostics channel receives when a computed value — a read or write
+ * behavior's return — is one its Contract refuses: 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.
+ */
+export declare class ComputedValueError extends Error {
+    readonly issues: readonly ValidationIssue[];
+    readonly name = "ComputedValueError";
+    constructor(resource: string, field: string, stage: "read" | "create" | "update", issues: readonly ValidationIssue[]);
+}

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

@@ -0,0 +1,9 @@
+export class ComputedValueError extends Error {
+    issues;
+    name = "ComputedValueError";
+    constructor(resource, field, stage, issues) {
+        const [first] = issues;
+        super(`The ${stage} behavior 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,6 +1,7 @@
 import type { Contract } from "../contracts/contract.js";
 import type { OperationIdentity } from "../operations/operation-identity.js";
 import type { ValidationIssue } from "../operations/validation-code.js";
+import type { ReferentialActionTable } from "./referential-action.js";
 /**
  * Core's create-requirement vocabulary, and the check that reads it.
  *
@@ -22,6 +23,24 @@ import type { ValidationIssue } from "../operations/validation-code.js";
  * which reaches the caller as an internal failure. A missing value is the
  * caller's to fix, so it answers `A2004` with a `V1000` issue at the path where
  * the value belongs.
+ *
+ * **One value, two spellings.** A relation that holds a reference has scalar
+ * fields that hold it too — the Adapter states which, on the relation's
+ * referential edge (`ReferentialEdge.references`), for every such relation,
+ * required or optional. A write that sets both — `authorId` and
+ * `author: { $connect: … }` in one record, at create or update — names the
+ * reference twice. No store can honour both, and which one the caller meant is
+ * not the framework's to guess, so it is the caller's `A2004` too: a `V1012`
+ * issue at the relation, in every record the check walks, before any Adapter
+ * work. The same edge is what a required relation may instead be written
+ * through, so the pairing has one source.
+ *
+ * **One store, one spelling per record.** A store may take a record's
+ * references only one way at a time — every relation that holds one written as
+ * a relation, or every one through its fields — and state it as the Contract's
+ * `referenceWrites: "uniform"`. Under it, a record that writes a relation
+ * holding a reference beside another relation's reference field is the caller's
+ * `A2004` as well: a `V1012` issue at the relation write.
  */
 /** A relation edge, named by the Resource that holds it and its field there. */
 export type CreateRequirementEdge = {
@@ -34,9 +53,11 @@ export type CreateRequirementEdge = {
  * - `field` — a scalar with no default, generated value or other source: it
  *   must be written.
  * - `relation` — a required to-one relation: it must be written (connected or
- *   created), or every one of `orFields` must be — the scalar fields that hold
- *   the reference. When the row is created **through** the relation's other end
- *   (`inverse`), the parent supplies it, and it is not required.
+ *   created), or every field that holds its reference must be — the
+ *   `references` of the relation's referential edge, less any the store fills
+ *   itself (`DEFAULTED` or `GENERATED_ON_CREATE`). When the row is created
+ *   **through** the relation's other end (`inverse`), the parent supplies it,
+ *   and it is not required.
  */
 export type CreateRequirement = {
     readonly kind: "field";
@@ -44,7 +65,6 @@ export type CreateRequirement = {
 } | {
     readonly kind: "relation";
     readonly relation: string;
-    readonly orFields: readonly string[];
     readonly inverse?: CreateRequirementEdge;
 };
 /**
@@ -53,13 +73,29 @@ export type CreateRequirement = {
  */
 export type CreateRequirementTable = Readonly<Record<string, readonly CreateRequirement[]>>;
 type Path = readonly (string | number)[];
+/**
+ * What the Adapter stated that the check reads: its create requirements, and
+ * its referential edges for the fields that hold each reference. Read once when
+ * the Framework is constructed.
+ */
+export type RecordWriteFacts = {
+    readonly requirements: CreateRequirementTable;
+    readonly references: ReferentialActionTable;
+};
+/** The facts an Adapter stated, read off it once; an absent table states nothing. */
+export declare function recordWriteFactsOf(adapter: {
+    readonly createRequirements?: CreateRequirementTable;
+    readonly referentialActions?: ReferentialActionTable;
+}): RecordWriteFacts;
 /**
  * The `V1000` issues for every create position in one operation's arguments
  * that lacks a value the Adapter requires — `create.*`'s `data`, `upsert`'s
- * `create`, and every nested create under any write — in argument order.
- * Empty when nothing is missing. Total over malformed input.
+ * `create`, and every nested create under any write — and the `V1012` issues
+ * for every write record, create or update, that sets a relation and its
+ * reference both, in argument order. Empty when there are none. Total over
+ * malformed input.
  */
-export declare function missingCreateValues(contract: Contract, table: CreateRequirementTable, request: OperationIdentity & {
+export declare function createRequirementIssues(contract: Contract, facts: RecordWriteFacts, request: OperationIdentity & {
     readonly resource: string;
 }, args: unknown, argumentsPath: Path): readonly ValidationIssue[];
 export {};

package/dist/runtime/create-requirement.js

@@ -12,6 +12,23 @@ function requirementsOf(table, resource) {
     const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
     return Array.isArray(listed) ? listed : [];
 }
+function edgesOf(table, resource) {
+    const listed = Object.hasOwn(table, resource) ? table[resource] : undefined;
+    return Array.isArray(listed) ? listed : [];
+}
+function referencesOf(edge) {
+    return Array.isArray(edge.references) ? edge.references : [];
+}
+function referenceFieldsOf(table, resource, relation) {
+    const edge = edgesOf(table, resource).find((candidate) => candidate.field === relation);
+    return edge === undefined ? [] : referencesOf(edge);
+}
+function storeSupplied(contract, resource, field) {
+    const found = lookupField(lookupResource(contract, resource), field);
+    return (found?.kind === "scalar" &&
+        (found.lifecycle.includes("DEFAULTED") ||
+            found.lifecycle.includes("GENERATED_ON_CREATE")));
+}
 function creatableScalar(contract, resource, field) {
     const found = lookupField(lookupResource(contract, resource), field);
     return found?.kind === "scalar" && found.capabilities.create !== undefined;
@@ -26,7 +43,9 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
         return;
     }
     const { contract, issues } = context;
-    for (const requirement of requirementsOf(context.table, resource)) {
+    const conflicted = referenceConflicts(context, resource, record, path);
+    mixedReferenceWrites(context, resource, record, path, conflicted);
+    for (const requirement of requirementsOf(context.requirements, resource)) {
         if (requirement.kind === "field") {
             if (!written(record, requirement.field) &&
                 creatableScalar(contract, resource, requirement.field)) {
@@ -38,14 +57,15 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
             }
             continue;
         }
+        if (conflicted.has(requirement.relation)) {
+            continue;
+        }
         if (via !== undefined &&
             requirement.inverse?.resource === via.resource &&
             requirement.inverse.relation === via.relation) {
             continue;
         }
-        const orFields = Array.isArray(requirement.orFields)
-            ? requirement.orFields
-            : [];
+        const orFields = referenceFieldsOf(context.references, resource, requirement.relation).filter((field) => !storeSupplied(contract, resource, field));
         if (written(record, requirement.relation) ||
             (orFields.length > 0 && orFields.every((field) => written(record, field)))) {
             continue;
@@ -69,6 +89,55 @@ function checkCreateRecord(context, resource, record, path, scope, via) {
     }
     walkNestedCreates(context, resource, record, path);
 }
+function referenceConflicts(context, resource, record, path) {
+    const conflicted = new Set();
+    for (const edge of edgesOf(context.references, resource)) {
+        if (!written(record, edge.field)) {
+            continue;
+        }
+        const fields = referencesOf(edge).filter((field) => written(record, field));
+        if (fields.length === 0) {
+            continue;
+        }
+        conflicted.add(edge.field);
+        context.issues.push({
+            code: "V1012",
+            path: [...path, edge.field],
+            message: `Set ${fields.map((field) => `"${field}"`).join(" and ")} or "${edge.field}", not both.`,
+        });
+    }
+    return conflicted;
+}
+function mixedReferenceWrites(context, resource, record, path, conflicted) {
+    if (context.contract.referenceWrites !== "uniform") {
+        return;
+    }
+    const edges = edgesOf(context.references, resource);
+    const referenceFields = [...new Set(edges.flatMap(referencesOf))];
+    for (const edge of edges) {
+        if (!written(record, edge.field) || conflicted.has(edge.field)) {
+            continue;
+        }
+        const fields = referenceFields.filter((field) => written(record, field));
+        if (fields.length === 0) {
+            continue;
+        }
+        const named = fields.map((field) => `"${field}"`).join(" and ");
+        context.issues.push({
+            code: "V1012",
+            path: [...path, edge.field],
+            message: `Use relation fields only, or reference fields only, in one record: ${named} ${fields.length === 1 ? "is a reference field" : "are reference fields"} and "${edge.field}" is a relation.`,
+        });
+    }
+}
+function checkUpdateRecord(context, resource, record, path) {
+    if (!isRecord(record)) {
+        return;
+    }
+    const conflicted = referenceConflicts(context, resource, record, path);
+    mixedReferenceWrites(context, resource, record, path, conflicted);
+    walkNestedCreates(context, resource, record, path);
+}
 function walkNestedCreates(context, resource, record, path) {
     if (!isRecord(record)) {
         return;
@@ -100,18 +169,29 @@ function walkNestedCreates(context, resource, record, path) {
                         checkCreateRecord(context, field.target, siteRecord, sitePath, NESTED_WRITE_SCOPE, via);
                     }
                     else {
-                        walkNestedCreates(context, field.target, siteRecord, sitePath);
+                        checkUpdateRecord(context, field.target, siteRecord, sitePath);
                     }
                 }
             }
         }
     }
 }
-export function missingCreateValues(contract, table, request, args, argumentsPath) {
+export function recordWriteFactsOf(adapter) {
+    return {
+        requirements: adapter.createRequirements ?? {},
+        references: adapter.referentialActions ?? {},
+    };
+}
+export function createRequirementIssues(contract, facts, request, args, argumentsPath) {
     if (!isRecord(args)) {
         return [];
     }
-    const context = { contract, table, issues: [] };
+    const context = {
+        contract,
+        requirements: facts.requirements,
+        references: facts.references,
+        issues: [],
+    };
     const scope = resolveWriteScope(lookupResource(contract, request.resource), request);
     if (request.family === "create" && written(args, "data")) {
         const data = args.data;
@@ -126,13 +206,13 @@ export function missingCreateValues(contract, table, request, args, argumentsPat
     }
     if (request.family === "upsert") {
         checkCreateRecord(context, request.resource, args.create, [...argumentsPath, "create"], scope, undefined);
-        walkNestedCreates(context, request.resource, args.update, [
+        checkUpdateRecord(context, request.resource, args.update, [
             ...argumentsPath,
             "update",
         ]);
     }
     if (request.family === "update") {
-        walkNestedCreates(context, request.resource, args.data, [
+        checkUpdateRecord(context, request.resource, args.data, [
             ...argumentsPath,
             "data",
         ]);

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

@@ -5,19 +5,28 @@ import type { FrameworkOperationRequest } from "./operation-request.js";
 import type { OperationErrorCode } from "./operation-response.js";
 /**
  * One unplanned failure of an operation: the raw error, the code the caller
- * received, and the operation and request it happened in. Server-side only:
+ * received, and the operation and request it happened in — or a developer's
+ * deliberate internal failure, marked `deliberate`. Server-side only:
  * diagnostics are never sent to the caller.
  */
 export type OperationDiagnostic = {
     readonly kind: "operation";
     readonly error: unknown;
     readonly code: OperationErrorCode;
-    readonly scope: RequestOrigin;
+    readonly origin: RequestOrigin;
     readonly resource: string;
     readonly family: OperationFamily;
     readonly variant: string;
     readonly requestId: string;
     readonly operation?: number;
+    /**
+     * `true` when `error` is a `FrameworkError` its thrower — a pipeline
+     * callback, a behavior, a filter or an Adapter — raised deliberately with an
+     * internal (`A3xxx`) code: the developer's own failure, whose message and
+     * issues the caller never receives. Absent for a failure the framework did not
+     * expect.
+     */
+    readonly deliberate?: true;
 };
 /**
  * One unplanned failure of a transaction: the raw error, the code the caller
@@ -27,9 +36,14 @@ export type TransactionDiagnostic = {
     readonly kind: "transaction";
     readonly error: unknown;
     readonly code: OperationErrorCode;
-    readonly scope: RequestOrigin;
+    readonly origin: RequestOrigin;
     readonly requestId: string;
     readonly operation?: number;
+    /**
+     * Never present: only an operation diagnostic is marked `deliberate`. Declared
+     * so the mark can be read on any {@link FrameworkDiagnostic}.
+     */
+    readonly deliberate?: never;
 };
 /** One diagnostic: of an operation, or of a transaction as a whole. */
 export type FrameworkDiagnostic = OperationDiagnostic | TransactionDiagnostic;
@@ -43,7 +57,9 @@ export type FrameworkDiagnosticsSink = (diagnostic: FrameworkDiagnostic) => void
  * error and the code being emitted. Total by construction — it returns
  * before the sink has finished and swallows everything the sink does.
  */
-export type DiagnosticsReporter = (error: unknown, code: OperationErrorCode) => void;
+export type DiagnosticsReporter = (error: unknown, code: OperationErrorCode, marks?: DiagnosticMarks) => void;
+/** What a report states about its error beyond the code: today, whether it was deliberate. */
+export type DiagnosticMarks = Pick<OperationDiagnostic, "deliberate">;
 /** The identifying half of a diagnostic, captured once per request. */
 type OperationDiagnosticIdentity = Omit<OperationDiagnostic, "error" | "code">;
 type TransactionDiagnosticIdentity = Omit<TransactionDiagnostic, "error" | "code">;

package/dist/runtime/diagnostics-reporter.js

@@ -10,9 +10,16 @@ export function createReporter(sink, identity) {
     if (sink === undefined) {
         return IGNORE_DIAGNOSTIC;
     }
-    return (error, code) => {
+    return (error, code, marks) => {
         try {
-            const settled = sink({ ...identity, error, code });
+            const settled = sink(identity.kind === "operation"
+                ? {
+                    ...identity,
+                    error,
+                    code,
+                    ...(marks?.deliberate === true ? { deliberate: true } : {}),
+                }
+                : { ...identity, error, code });
             if (isThenable(settled)) {
                 settled.then(undefined, () => undefined);
             }
@@ -36,7 +43,7 @@ export function createDiagnosticsReporter(sink, request, operation) {
     try {
         identity = {
             kind: "operation",
-            scope: request.scope,
+            origin: request.origin,
             resource: request.resource,
             family: request.family,
             variant: request.variant,
@@ -54,7 +61,7 @@ export function createTransactionDiagnosticsChannel(sink, request) {
     try {
         identity = {
             kind: "transaction",
-            scope: request.scope,
+            origin: request.origin,
             requestId: request.requestId,
         };
     }

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

@@ -20,6 +20,8 @@ export declare class AdapterBoundary {
 export declare const SERIALIZATION_FAILURE_MESSAGE = "Result serialization failed.";
 /** Where a standalone operation's arguments sit in a framework issue path. */
 export declare const OPERATION_ARGUMENTS_PATH: readonly (string | number)[];
+/** Where one plan step sits in a framework issue path: its node in the request. */
+export declare function planStepPath(index: number): readonly (string | number)[];
 /** Where one plan operation's arguments sit in a framework issue path. */
 export declare function planOperationArgumentsPath(index: number): readonly (string | number)[];
 /**
@@ -31,6 +33,12 @@ export type CallerArgumentsView = {
     readonly path: readonly (string | number)[];
     readonly arguments: unknown;
 };
+/**
+ * The longest issue message a developer's code may send to the caller, in UTF-16
+ * code units. A longer one, or one with no visible character, is replaced by the
+ * framework's text for its code and reported to the diagnostics channel.
+ */
+export declare const MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH = 1000;
 /**
  * Final framework sanitization, shared by every boundary. A deliberate
  * {@link FrameworkError} carries its own stable outcome; anything else is