@aventara/core 1.0.0-rc.11 → 1.0.0-rc.13

package/dist/compiler/contract.compiler.js

@@ -8,7 +8,7 @@ import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { advertisedDirectives, advertisedReducers, holdsInAnyScope, } from "../contracts/field.js";
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
 import { isRecord } from "../runtime/record.guard.js";
-import { checkCreateRequirements, checkHiddenRequirements, projectCreateRequirements, } from "./create-requirements.projector.js";
+import { checkCreateRequirements, checkHiddenRequirements, checkReadOnlyNestedWrites, projectCreateRequirements, withheldKey, withholdReadOnlyNestedWrites, } from "./create-requirements.projector.js";
 import { applyValidators, bindFieldValidators, checkLayerValidators, compileValidatorTable, } from "./field-validator.compiler.js";
 import { explainManagedRefusals, hideManagedElsewhere, managedElsewhereOf, managedWriteReason, markCoreResources, pruneManagedEnums, withholdManagedWrites, } from "./managed-elsewhere.projector.js";
 const UNIQUE_VARIANTS = [
@@ -491,6 +491,9 @@ function capabilityAxisFor(kind, key) {
 function unavailableCapability(path, message, diagnostics) {
     diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_CAPABILITY", path, message));
 }
+function parentLayerOf(walk) {
+    return walk.layer === "agent" ? (walk.parent ?? "client") : "root";
+}
 function otherOverlay(layer) {
     return layer === "client" ? "application" : "client";
 }
@@ -504,9 +507,23 @@ function exemptsWhole(entry) {
 }
 function exemptsAnything(entry) {
     return (entry === true ||
+        entry === READ ||
         (Array.isArray(entry) && entry.length > 0) ||
         isRecord(entry));
 }
+const READ = "read";
+const READ_CAPABILITIES = {
+    scalar: ["select", "filter", "order", "orderNulls"],
+    relation: ["select", "include", "filter", "order", "pagination", "reducers"],
+};
+const readCapabilitiesCovered = [true, true];
+void readCapabilitiesCovered;
+function readCapabilitiesOf(kind, parentCapabilities) {
+    return READ_CAPABILITIES[kind].filter((capability) => {
+        const axis = capabilityAxisFor(kind, capability);
+        return (axis !== undefined && memberOffered(axis, parentCapabilities[capability]));
+    });
+}
 function listedNames(entry, path) {
     if (!Array.isArray(entry)) {
         return [];
@@ -585,6 +602,34 @@ function offeredTokens(walk, axis, universeValue, listed, capability, label) {
     }
     return tokens;
 }
+const WITHHELD_LACKS = {
+    delete: ["has no delete operation", "a delete operation"],
+    update: [
+        "updates nothing",
+        "an update operation or a field writable on update",
+    ],
+    create: [
+        "creates nothing",
+        "a create operation or a field writable on create",
+    ],
+};
+function joined(names) {
+    return names.length <= 1
+        ? (names[0] ?? "")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+function withheldWrite(walk, universeField, label, path, directives, member, withheld) {
+    const target = String(universeField.target);
+    const above = parentLayerOf(walk);
+    const reasons = [
+        ...new Set(directives.flatMap((name) => withheld.get(name) ?? [])),
+    ];
+    const named = member ?? joined(directives);
+    const message = reasons.length === 1 && reasons[0] === "delete"
+        ? `the ${walk.layer} layer lets relation ${label} delete rows of resource "${target}" ($delete), but "${target}" has no delete operation in ${above}, the layer ${walk.layer} starts from, so ${above} offers no $delete on ${label}${member === undefined ? "" : ` and no ${member} at all, $delete being all it had`}; take ${named} off ${label}, or give "${target}" a delete operation in ${above}`
+        : `the ${walk.layer} layer lets relation ${label} write rows of resource "${target}" (${joined(directives)}), but "${target}" ${reasons.map((reason) => WITHHELD_LACKS[reason][0]).join(", and ")} in ${above}, the layer ${walk.layer} starts from, so ${above} offers no ${joined(directives)} on ${label}${member === undefined ? "" : ` and no ${member} at all`}; take ${named} off ${label}, or give "${target}" ${reasons.map((reason) => WITHHELD_LACKS[reason][1]).join(", and ")} in ${above}`;
+    walk.diagnostics.push(diagnostic("COMPILER_READ_ONLY_NESTED_WRITE", path.replace(/(\[\d+\]|\.[^.[\]]+)$/, ""), message));
+}
 function exemptCapability(walk, universeField, parentCapabilities, result, capability, entry, label, path) {
     if (entry === undefined) {
         return;
@@ -624,7 +669,19 @@ function exemptCapability(walk, universeField, parentCapabilities, result, capab
     if (tokens !== undefined && tokens.length === 0) {
         return;
     }
+    const withheldHere = new Map();
+    const prefix = withheldKey(label.slice(1, -1), capability, "");
+    for (const [key, reason] of walk.withheldWrites ?? []) {
+        if (key.startsWith(prefix)) {
+            withheldHere.set(key.slice(prefix.length), reason);
+        }
+    }
     if (!parentHas) {
+        if (withheldHere.size > 0 &&
+            (tokens === undefined || tokens.every((token) => withheldHere.has(token)))) {
+            withheldWrite(walk, universeField, label, path, tokens ?? [...withheldHere.keys()], tokens === undefined ? capability : undefined, withheldHere);
+            return;
+        }
         widening(walk, "COMPILER_UNAVAILABLE_CAPABILITY", path, `capability "${capability}" of field ${label}`);
         return;
     }
@@ -635,7 +692,14 @@ function exemptCapability(walk, universeField, parentCapabilities, result, capab
     const parentTokens = memberTokens(axis, parentValue) ?? [];
     const hidden = tokens.filter((token) => !parentTokens.includes(token));
     if (hidden.length > 0) {
-        widening(walk, "COMPILER_UNAVAILABLE_CAPABILITY", path, `${hidden.map((token) => `"${token}"`).join(", ")} of capability "${capability}" of field ${label}`);
+        const withheld = hidden.filter((token) => withheldHere.has(token));
+        const widened = hidden.filter((token) => !withheldHere.has(token));
+        if (withheld.length > 0) {
+            withheldWrite(walk, universeField, label, path, withheld, undefined, withheldHere);
+        }
+        if (widened.length > 0) {
+            widening(walk, "COMPILER_UNAVAILABLE_CAPABILITY", path, `${widened.map((token) => `"${token}"`).join(", ")} of capability "${capability}" of field ${label}`);
+        }
         return;
     }
     result[capability] = withTokens(axis, parentValue, parentTokens.filter((token) => tokens.includes(token)));
@@ -650,7 +714,12 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
             }
         }
     }
-    if (Array.isArray(entry)) {
+    if (entry === READ) {
+        for (const capability of readCapabilitiesOf(universeField.kind, parentCapabilities)) {
+            exemptCapability(walk, universeField, parentCapabilities, result, capability, true, label, path);
+        }
+    }
+    else if (Array.isArray(entry)) {
         for (const [capability, capabilityPath] of listedNames(entry, path)) {
             exemptCapability(walk, universeField, parentCapabilities, result, capability, true, label, capabilityPath);
         }
@@ -670,7 +739,11 @@ function exemptField(walk, universeField, parentField, entry, label, path) {
     return { ...cloneValue(parentField), capabilities: result };
 }
 function exemptFields(walk, resourceName, universe, parent, entries, path) {
-    const named = isRecord(entries) ? entries : {};
+    const named = entries === READ
+        ? Object.fromEntries(Object.keys(parent.fields).map((name) => [name, READ]))
+        : isRecord(entries)
+            ? entries
+            : {};
     for (const fieldName of Object.keys(named)) {
         if (universe.fields[fieldName] === undefined) {
             walk.diagnostics.push(diagnostic("COMPILER_UNKNOWN_FIELD", `${path}.${fieldName}`, `field "${fieldName}" is neither discovered by the adapter nor defined at the root`));
@@ -866,9 +939,14 @@ function pruneEmptyOperationFamilies(operations) {
 function identifierLabel(identifier) {
     return identifier.map((name) => `\`${name}\``).join(" and ");
 }
+function isAddressable(field, parentField) {
+    return (field?.kind === "scalar" &&
+        (capabilityIsEnabled(field.capabilities.filter) ||
+            !capabilityIsEnabled(parentField?.capabilities?.filter)));
+}
 function reconcileIdentifiers(walk, resource, parent, path) {
     resource.identifiers = parent.identifiers
-        .filter((identifier) => identifier.every((name) => resource.fields[name]?.kind === "scalar"))
+        .filter((identifier) => identifier.every((name) => isAddressable(resource.fields[name], parent.fields[name])))
         .map((identifier) => [...identifier]);
     const first = parent.identifiers[0];
     if (resource.identifiers.length > 0 || first === undefined) {
@@ -882,8 +960,8 @@ function reconcileIdentifiers(walk, resource, parent, path) {
         }
         const variantPath = `${path}.operations.${family}.${variant}`;
         walk.diagnostics.push(diagnostic("COMPILER_MISSING_IDENTIFIER", variantPath, walk.style === "pick"
-            ? `${variantPath} needs an identifier field; pick ${identifierLabel(first)} (or another complete identifier) too`
-            : `${variantPath} needs an identifier field, and the exemptions hide every complete identifier; keep ${identifierLabel(first)} (or another complete identifier) exposed, or exempt the operation too`));
+            ? `${variantPath} needs an identifier field; pick ${identifierLabel(first)} with its filter (or another complete identifier) too`
+            : `${variantPath} needs an identifier field, and the exemptions hide (or stop filtering on) every complete identifier; keep ${identifierLabel(first)} (or another complete identifier) exposed and filterable, or exempt the operation too`));
     }
 }
 function validateScalarReference(projection, field, path, diagnostics) {
@@ -1020,8 +1098,8 @@ function resolveLimits(scope) {
 }
 function resolveTransactions(model, scopeName, scope, diagnostics) {
     const requested = scope.transactionsStyle ?? model.transactions;
-    if (requested === "interactive" && model.transactions === "none") {
-        diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_CAPABILITY", `${scopeName}.transactionsStyle`, 'transaction capability "interactive" is not available in the canonical adapter model'));
+    if (requested !== "none" && model.transactions === "none") {
+        diagnostics.push(diagnostic("COMPILER_UNAVAILABLE_CAPABILITY", `${scopeName}.transactionsStyle`, `transaction capability "${requested}" is not available in the canonical adapter model`));
     }
     return requested;
 }
@@ -1031,6 +1109,11 @@ function semanticObject(contract) {
 function exposureStyle(layer) {
     return layer.exposed === false ? "pick" : "omit";
 }
+function withholdOmittedWrites(style, projection) {
+    return style === "omit"
+        ? withholdReadOnlyNestedWrites(projection.resources)
+        : new Map();
+}
 function projectCore(model, config, diagnostics) {
     const scope = config.root;
     const managed = managedElsewhereOf(config.trees.root);
@@ -1049,13 +1132,15 @@ function projectCore(model, config, diagnostics) {
     const projection = projectExposure({ layer: "root", style: exposureStyle(scope), diagnostics }, baseline, baseline, scope.exemptions);
     qualifyFilterModes(projection);
     pruneHiddenPairings(projection, "shown");
+    const withheldWrites = withholdOmittedWrites(exposureStyle(scope), projection);
     projectCreateRequirements(model, projection.resources);
     const rootChecked = diagnostics.length;
     checkHiddenRequirements(model, "root", baseline.resources, unwithheld.resources, projection.resources, diagnostics);
+    checkReadOnlyNestedWrites("root", undefined, projection.resources, diagnostics);
     explainManagedRefusals(diagnostics, rootChecked, "root", baseline, managed);
     applyValidators(projection.resources, validators);
     validateProjection(projection, "root", diagnostics);
-    return { baseline, projection, validators };
+    return { baseline, projection, validators, withheldWrites };
 }
 function markGovernedFields(baseline, governed) {
     if (governed === undefined) {
@@ -1078,7 +1163,7 @@ function markGovernedFields(baseline, governed) {
         }
     }
 }
-function projectDerivedScope(model, scopeName, core, parentView, config, diagnostics) {
+function projectDerivedScope(model, scopeName, core, parentView, parentWithheld, config, diagnostics) {
     const scope = config[scopeName];
     const managed = managedElsewhereOf(config.trees.root);
     const baseline = cloneValue(core.baseline);
@@ -1105,6 +1190,7 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
         layer: scopeName,
         style: exposureStyle(scope),
         diagnostics,
+        withheldWrites: parentWithheld,
         ...(scopeName === "agent" ? { parent: config.agent.parent } : {}),
     }, baseline, parent, scope.exemptions);
     qualifyFilterModes(projection);
@@ -1112,13 +1198,18 @@ function projectDerivedScope(model, scopeName, core, parentView, config, diagnos
     if (unhidden !== parent) {
         pruneManagedEnums(projection, unhidden, managed);
     }
+    const withheldWrites = new Map([
+        ...parentWithheld,
+        ...withholdOmittedWrites(exposureStyle(scope), projection),
+    ]);
     projectCreateRequirements(model, projection.resources);
     const layerChecked = diagnostics.length;
     checkHiddenRequirements(model, scopeName, baseline.resources, unhidden.resources, projection.resources, diagnostics);
+    checkReadOnlyNestedWrites(scopeName, unhidden.resources, projection.resources, diagnostics);
     explainManagedRefusals(diagnostics, layerChecked, scopeName, baseline, managed);
     applyValidators(projection.resources, validators);
     validateProjection(projection, scopeName, diagnostics);
-    return { projection, validators };
+    return { projection, validators, withheldWrites };
 }
 function bindShapedFields(contract, definitions) {
     for (const [resourceName, resource] of Object.entries(contract.resources)) {
@@ -1140,14 +1231,18 @@ export async function compileContracts(model, config) {
     checkReservedResourceNames(model, diagnostics);
     checkCreateRequirements(model, diagnostics);
     const coreCompilation = projectCore(model, compilerConfig, diagnostics);
-    const applicationProjection = projectDerivedScope(model, "application", coreCompilation, coreCompilation.projection, compilerConfig, diagnostics);
-    const clientProjection = projectDerivedScope(model, "client", coreCompilation, coreCompilation.projection, compilerConfig, diagnostics);
+    const applicationProjection = projectDerivedScope(model, "application", coreCompilation, coreCompilation.projection, coreCompilation.withheldWrites, compilerConfig, diagnostics);
+    const clientProjection = projectDerivedScope(model, "client", coreCompilation, coreCompilation.projection, coreCompilation.withheldWrites, compilerConfig, diagnostics);
     const agentParent = compilerConfig.agent.parent;
     const agentProjection = projectDerivedScope(model, "agent", coreCompilation, agentParent === "root"
         ? coreCompilation.projection
         : agentParent === "application"
             ? applicationProjection.projection
-            : clientProjection.projection, compilerConfig, diagnostics);
+            : clientProjection.projection, agentParent === "root"
+        ? coreCompilation.withheldWrites
+        : agentParent === "application"
+            ? applicationProjection.withheldWrites
+            : clientProjection.withheldWrites, compilerConfig, diagnostics);
     markCoreResources(coreCompilation.projection, model, managedElsewhereOf(compilerConfig.trees.root));
     if (diagnostics.length > 0) {
         return { ok: false, diagnostics };

package/dist/compiler/create-requirements.projector.d.ts

@@ -12,11 +12,18 @@ type ProjectedResource = {
     readonly fields: Readonly<Record<string, ProjectedField>>;
     createRequirements?: AvCreateRequirements;
 };
+/**
+ * The Adapter's statement with the layer's non-null added fields required too.
+ * The runtime reads it over the Core Contract (`recordWriteFactsOf`): what write
+ * compute must not leave missing.
+ */
+export declare function withVirtualRequirements(stated: AvCreateRequirements | undefined, resource: ProjectedResource): AvCreateRequirements | undefined;
 /**
  * Sets every Resource's `createRequirements` in one layer's projection to the
- * Adapter's statement as that layer sees it, and removes it where nothing is
- * left. Reads the projection's final fields: its exposure, and the lifecycle
- * its compute stages gave them.
+ * Adapter's statement as that layer sees it, its non-null added (`VIRTUAL`)
+ * fields required too, and removes it where nothing is left. Reads the
+ * projection's final fields: its exposure, and the lifecycle its compute stages
+ * gave them.
  */
 export declare function projectCreateRequirements(model: AvAdapterModel, resources: Readonly<Record<string, ProjectedResource>>): void;
 /** A Resource's operations, as far as this check reads them. */
@@ -38,6 +45,41 @@ type ResourceWithOperations = ProjectedResource & {
  * its final view.
  */
 export declare function checkHiddenRequirements(model: AvAdapterModel, layer: AvConfigLayerName, universe: Readonly<Record<string, ProjectedResource>>, parent: Readonly<Record<string, ProjectedResource>>, projection: Readonly<Record<string, ResourceWithOperations>>, diagnostics: AvContractCompilerDiagnostic[]): void;
+/**
+ * Refuses, for one layer, every relation that writes rows of a Resource the
+ * layer keeps read-only: a nested `$create`, `$connectOrCreate` or `$upsert`
+ * into a Resource with no create or upsert variant and no field writable on
+ * create, a nested `$update` or `$upsert` into one with no update or upsert
+ * variant and no field writable on update, or a nested `$delete` into one with
+ * no delete variant. Reported once, by the layer that makes it so: an overlay
+ * is not refused for a relation its parent was already refused for. `parent` is
+ * what the layer starts from; the root's is none, so an Adapter that offers such
+ * a write is refused at the root. An Omit layer has none left to refuse:
+ * {@link withholdReadOnlyNestedWrites} dropped them first.
+ */
+export declare function checkReadOnlyNestedWrites(layer: AvConfigLayerName, parent: Readonly<Record<string, ResourceWithOperations>> | undefined, projection: Readonly<Record<string, ResourceWithOperations>>, diagnostics: AvContractCompilerDiagnostic[]): void;
+/** Why the narrowing dropped a directive: its target deletes, updates or creates nothing in the layer. */
+export type WithheldReason = "delete" | "update" | "create";
+/**
+ * The directives an Omit layer's narrowing dropped, by relation, stage and
+ * directive (`"posts.comments.update.$delete"`), each with why.
+ */
+export type WithheldWrites = ReadonlyMap<string, WithheldReason>;
+/** The key of one dropped directive in {@link WithheldWrites}. */
+export declare function withheldKey(relation: string, stage: string, directive: string): string;
+/**
+ * Narrows an Omit layer's view so no relation writes rows of a Resource the
+ * view cannot write: `$create`, `$connectOrCreate` and `$upsert` into one that
+ * creates nothing (no create or upsert variant, no field writable on create),
+ * `$update` and `$upsert` into one that updates nothing (no update or upsert
+ * variant, no field writable on update), `$delete` into one that deletes
+ * nothing (no delete variant). A member emptied goes with its last directive.
+ * Dropping a directive can leave another Resource writing nothing (its only
+ * write capability was it), so the pass repeats to a fixed point. Returns
+ * every directive it dropped, with why. A Pick layer's view is not narrowed:
+ * {@link checkReadOnlyNestedWrites} refuses what it grants.
+ */
+export declare function withholdReadOnlyNestedWrites(resources: Readonly<Record<string, ResourceWithOperations>>): WithheldWrites;
 /**
  * Every name in the Adapter's create requirements that is not what its member
  * says: a `required` name that is no field of the Resource, a group whose first

package/dist/compiler/create-requirements.projector.js

@@ -1,6 +1,7 @@
 import { advertisedDirectives, advertisedDirectivesAt, } from "../contracts/field.js";
 import { isOperationVariantAvailable, writeScopeOf, } from "../contracts/resource-operations.js";
 import { isRecord } from "../runtime/record.guard.js";
+import { keptDirectives } from "./managed-elsewhere.projector.js";
 function own(record, key) {
     return Object.hasOwn(record, key) ? record[key] : undefined;
 }
@@ -32,6 +33,23 @@ function computedOnCreate(resource, name) {
         Array.isArray(field.lifecycle) &&
         field.lifecycle.includes("COMPUTED_ON_CREATE"));
 }
+function virtualRequirements(resource) {
+    return Object.entries(resource.fields)
+        .filter(([, field]) => field.kind === "scalar" &&
+        field.nullable === false &&
+        Array.isArray(field.lifecycle) &&
+        field.lifecycle.includes("VIRTUAL"))
+        .map(([name]) => name);
+}
+export function withVirtualRequirements(stated, resource) {
+    const [first, ...rest] = [
+        ...(stated?.required ?? []),
+        ...virtualRequirements(resource),
+    ];
+    return first === undefined
+        ? stated
+        : { ...stated, required: [first, ...rest] };
+}
 function projectOne(stated, resource, resources) {
     const required = [];
     const requireOnce = (name) => {
@@ -99,7 +117,7 @@ function projectOne(stated, resource, resources) {
 export function projectCreateRequirements(model, resources) {
     for (const [name, resource] of Object.entries(resources)) {
         delete resource.createRequirements;
-        const stated = own(model.resources, name)?.createRequirements;
+        const stated = withVirtualRequirements(own(model.resources, name)?.createRequirements, resource);
         if (stated === undefined) {
             continue;
         }
@@ -118,6 +136,7 @@ const UPDATING_DIRECTIVES = [
     "$update",
     "$upsert",
 ];
+const DELETING_DIRECTIVES = ["$delete"];
 function variantsOf(resource, families) {
     const variants = [];
     for (const family of families) {
@@ -159,6 +178,36 @@ function createVariantsOf(resource) {
     return variants;
 }
 function createPaths(resources) {
+    const { created, updated } = writtenResources(resources);
+    const paths = new Map();
+    const add = (name, path) => {
+        const list = paths.get(name) ?? [];
+        list.push(path);
+        paths.set(name, list);
+    };
+    for (const [name, resource] of Object.entries(resources)) {
+        const variants = createVariantsOf(resource);
+        if (variants.length > 0) {
+            add(name, { kind: "operation", variants });
+        }
+    }
+    for (const [parent, resource] of Object.entries(resources)) {
+        for (const [relation, field] of Object.entries(resource.fields)) {
+            const target = field.target;
+            if (field.kind !== "relation" || typeof target !== "string") {
+                continue;
+            }
+            if ((created.has(parent) &&
+                advertises(field, "create", CREATING_DIRECTIVES)) ||
+                (updated.has(parent) &&
+                    advertises(field, "update", CREATING_DIRECTIVES))) {
+                add(target, { kind: "nested", parent, relation });
+            }
+        }
+    }
+    return paths;
+}
+function writtenResources(resources) {
     const created = new Set();
     const updated = new Set();
     for (const [name, resource] of Object.entries(resources)) {
@@ -197,33 +246,7 @@ function createPaths(resources) {
             }
         }
     }
-    const paths = new Map();
-    const add = (name, path) => {
-        const list = paths.get(name) ?? [];
-        list.push(path);
-        paths.set(name, list);
-    };
-    for (const [name, resource] of Object.entries(resources)) {
-        const variants = createVariantsOf(resource);
-        if (variants.length > 0) {
-            add(name, { kind: "operation", variants });
-        }
-    }
-    for (const [parent, resource] of Object.entries(resources)) {
-        for (const [relation, field] of Object.entries(resource.fields)) {
-            const target = field.target;
-            if (field.kind !== "relation" || typeof target !== "string") {
-                continue;
-            }
-            if ((created.has(parent) &&
-                advertises(field, "create", CREATING_DIRECTIVES)) ||
-                (updated.has(parent) &&
-                    advertises(field, "update", CREATING_DIRECTIVES))) {
-                add(target, { kind: "nested", parent, relation });
-            }
-        }
-    }
-    return paths;
+    return { created, updated };
 }
 function pathLabel(path) {
     return path.kind === "operation"
@@ -320,6 +343,7 @@ export function checkHiddenRequirements(model, layer, universe, parent, projecti
         const parentResource = own(parent, name);
         if (stated === undefined ||
             routes.length === 0 ||
+            createsNothing(resource) ||
             universeResource === undefined ||
             parentResource === undefined) {
             continue;
@@ -367,6 +391,193 @@ export function checkHiddenRequirements(model, layer, universe, parent, projecti
         }
     }
 }
+function createsNothing(resource) {
+    return (variantsOf(resource, ["create", "upsert"]).length === 0 &&
+        !Object.keys(resource.fields).some((name) => creatable(resource, name)));
+}
+function updatesNothing(resource) {
+    return (variantsOf(resource, ["update", "upsert"]).length === 0 &&
+        !Object.values(resource.fields).some((field) => {
+            const capabilities = isRecord(field.capabilities)
+                ? field.capabilities
+                : undefined;
+            return field.kind === "scalar"
+                ? capabilities?.update !== undefined
+                : advertisedDirectives(capabilities?.update) !== undefined;
+        }));
+}
+function deletesNothing(resource) {
+    return variantsOf(resource, ["delete"]).length === 0;
+}
+function advertisedOf(field, stage, directives) {
+    const capabilities = isRecord(field.capabilities)
+        ? field.capabilities
+        : undefined;
+    const advertised = advertisedDirectives(capabilities?.[stage]) ?? [];
+    return directives.filter((name) => advertised.includes(name));
+}
+function readOnlyNestedWrites(resources) {
+    const { created, updated } = writtenResources(resources);
+    const writes = [];
+    for (const [parent, resource] of Object.entries(resources)) {
+        for (const [relation, field] of Object.entries(resource.fields)) {
+            const target = field.target;
+            const targetResource = field.kind === "relation" && typeof target === "string"
+                ? own(resources, target)
+                : undefined;
+            if (typeof target !== "string" || targetResource === undefined) {
+                continue;
+            }
+            const reached = (directives) => [
+                ...new Set([
+                    ...(created.has(parent)
+                        ? advertisedOf(field, "create", directives)
+                        : []),
+                    ...(updated.has(parent)
+                        ? advertisedOf(field, "update", directives)
+                        : []),
+                ]),
+            ];
+            const creating = createsNothing(targetResource)
+                ? reached(CREATING_DIRECTIVES)
+                : [];
+            const updating = updatesNothing(targetResource)
+                ? reached(UPDATING_DIRECTIVES)
+                : [];
+            const deleting = deletesNothing(targetResource)
+                ? reached(DELETING_DIRECTIVES)
+                : [];
+            if (creating.length > 0 || updating.length > 0 || deleting.length > 0) {
+                writes.push({
+                    parent,
+                    relation,
+                    target,
+                    creating,
+                    updating,
+                    deleting,
+                });
+            }
+        }
+    }
+    return writes;
+}
+export function checkReadOnlyNestedWrites(layer, parent, projection, diagnostics) {
+    const inherited = new Map((parent === undefined ? [] : readOnlyNestedWrites(parent)).map((write) => [
+        `${write.parent}.${write.relation}`,
+        write,
+    ]));
+    for (const found of readOnlyNestedWrites(projection)) {
+        const at = `${found.parent}.${found.relation}`;
+        const above = inherited.get(at);
+        const write = {
+            ...found,
+            creating: (above?.creating.length ?? 0) > 0 ? [] : found.creating,
+            updating: (above?.updating.length ?? 0) > 0 ? [] : found.updating,
+            deleting: (above?.deleting.length ?? 0) > 0 ? [] : found.deleting,
+        };
+        if (write.creating.length === 0 &&
+            write.updating.length === 0 &&
+            write.deleting.length === 0) {
+            continue;
+        }
+        const directives = [
+            ...new Set([...write.creating, ...write.updating, ...write.deleting]),
+        ];
+        const lacks = [
+            ...(write.creating.length === 0
+                ? []
+                : ["no create operation and no field writable on create"]),
+            ...(write.updating.length === 0
+                ? []
+                : ["no update operation and no field writable on update"]),
+            ...(write.deleting.length === 0 ? [] : ["no delete operation"]),
+        ];
+        const gives = [
+            ...(write.creating.length === 0
+                ? []
+                : ["a create operation or a field writable on create"]),
+            ...(write.updating.length === 0
+                ? []
+                : ["an update operation or a field writable on update"]),
+            ...(write.deleting.length === 0 ? [] : ["a delete operation"]),
+        ];
+        const keep = `take ${listed(directives)} off "${at}" (keep only the directives it may use, such as $connect)`;
+        diagnostics.push({
+            code: "COMPILER_READ_ONLY_NESTED_WRITE",
+            path: `${layer}.exemptions.resources.${write.parent}.fields.${write.relation}`,
+            message: write.creating.length === 0 && write.updating.length === 0
+                ? `the ${layer} layer lets relation "${at}" delete rows of resource "${write.target}" ($delete), but "${write.target}" has no delete operation in that layer; ${keep}, or give "${write.target}" a delete operation`
+                : `the ${layer} layer lets relation "${at}" write rows of resource "${write.target}" (${listed(directives)}), but "${write.target}" is read-only in that layer: it has ${lacks.join(", and ")}; ${keep}, or give "${write.target}" ${gives.join(", and ")}`,
+        });
+    }
+}
+function dropDirectives(field, stage, dropped) {
+    if (!isRecord(field.capabilities)) {
+        return [];
+    }
+    const capabilities = field.capabilities;
+    const advertised = advertisedDirectives(capabilities[stage]) ?? [];
+    const removed = advertised.filter((name) => dropped.includes(name));
+    if (removed.length === 0) {
+        return [];
+    }
+    const narrowed = keptDirectives(capabilities[stage], advertised.filter((name) => !dropped.includes(name)));
+    if (narrowed === undefined) {
+        delete capabilities[stage];
+    }
+    else {
+        capabilities[stage] = narrowed;
+    }
+    return removed;
+}
+function* relationsOf(resources) {
+    for (const [parent, resource] of Object.entries(resources)) {
+        for (const [relation, field] of Object.entries(resource.fields)) {
+            const target = field.target;
+            const targetResource = field.kind === "relation" && typeof target === "string"
+                ? own(resources, target)
+                : undefined;
+            if (typeof target === "string" && targetResource !== undefined) {
+                yield [parent, relation, field, target, targetResource];
+            }
+        }
+    }
+}
+export function withheldKey(relation, stage, directive) {
+    return `${relation}.${stage}.${directive}`;
+}
+export function withholdReadOnlyNestedWrites(resources) {
+    const withheld = new Map();
+    const drop = (at, field, stage, directives, reason) => {
+        const removed = dropDirectives(field, stage, directives);
+        for (const directive of removed) {
+            withheld.set(withheldKey(at, stage, directive), reason);
+        }
+        return removed.length > 0;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const [parent, relation, field, , target] of relationsOf(resources)) {
+            const at = `${parent}.${relation}`;
+            for (const stage of ["create", "update"]) {
+                if (deletesNothing(target)) {
+                    changed =
+                        drop(at, field, stage, DELETING_DIRECTIVES, "delete") || changed;
+                }
+                if (createsNothing(target)) {
+                    changed =
+                        drop(at, field, stage, CREATING_DIRECTIVES, "create") || changed;
+                }
+            }
+            if (updatesNothing(target)) {
+                changed =
+                    drop(at, field, "update", UPDATING_DIRECTIVES, "update") || changed;
+            }
+        }
+    }
+    return withheld;
+}
 function misnamed(path, message) {
     return { code: "COMPILER_UNKNOWN_FIELD", path, message };
 }

package/dist/compiler/managed-elsewhere.projector.d.ts

@@ -1,4 +1,5 @@
 import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvRelationMutationDirective } from "../contracts/capability.js";
 import type { AvContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
 type ProjectedField = Record<string, unknown> & {
     kind: "scalar" | "relation";
@@ -14,6 +15,8 @@ type ProjectedContract = {
 };
 /** The Resources the root's `resources` tree marks `managedElsewhere: true`. */
 export declare function managedElsewhereOf(rootTree: unknown): ReadonlySet<string>;
+/** A relation mutation capability with only `kept` of its directives (its scopes kept), or `undefined` when none is left. */
+export declare function keptDirectives(capability: unknown, kept: readonly AvRelationMutationDirective[]): unknown;
 /**
  * Takes every write of a managed Resource away from `baseline`: its write
  * families, its fields' `create`/`update`, and the directives of every relation

package/dist/compiler/managed-elsewhere.projector.js

@@ -22,7 +22,7 @@ export function managedElsewhereOf(rootTree) {
     }
     return managed;
 }
-function keptDirectives(capability, kept) {
+export function keptDirectives(capability, kept) {
     if (Array.isArray(capability)) {
         const left = capability.filter((directive) => kept.includes(directive));
         return left.length > 0 ? left : undefined;