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

package/dist/adapters/adapter.interface.d.ts

@@ -5,47 +5,46 @@ import type { AdapterOperationExecutor } from "./adapter-operation-executor.inte
 /** Provider-specific implementation of Aventara discovery and execution. */
 export interface Adapter<M extends AdapterModel = AdapterModel> extends AdapterOperationExecutor<M> {
     /**
-     * Canonical provider-discovery facts, held by the adapter and read
-     * synchronously at framework construction. Discovery is a property, not a
-     * call: the model is a settled fact of the constructed adapter, so it
-     * cannot fail, change, or be observed twice during construction.
+     * What the adapter discovered about the data source, in Aventara's vocabulary.
+     * Read once, synchronously, when the framework is constructed.
      */
     readonly model: M;
     /**
      * Optional referential actions: for each Resource that holds a reference,
-     * what deleting a referenced row does to its rows, in Aventara's words
-     * (`runtime/referential-action.ts`). Read once at framework construction,
-     * like `model`, and never part of a Contract or its hash.
+     * every relation holding one — the fields that hold it (`references`) and
+     * what deleting a referenced row does to its rows. Read once when the
+     * framework is constructed; never part of a Contract or its hash.
      *
-     * Direction, because getting it backwards is silent: an edge listed under
-     * Resource `R` says **deleting a `target` row does `onDelete` to rows of
-     * `R`**.
+     * An edge listed under Resource `R` says **deleting a `target` row does
+     * `onDelete` to rows of `R`**, and that `R`'s `references` fields hold the
+     * relation `field`'s reference.
      *
-     * Optional so an Adapter that cannot state them is believed: core then plans
-     * no cascade, and a transaction plan is never refused for one (`V1019`).
+     * When absent, no cascade is planned and no transaction plan is refused
+     * because of one (`V1019`); a write that sets a relation and a field holding
+     * its reference both is not refused before the store; and a required
+     * relation can be satisfied only by writing the relation.
      */
     readonly referentialActions?: ReferentialActionTable;
     /**
      * Optional create requirements: for each Resource, the values its store
-     * cannot create a row without, in Aventara's words
-     * (`runtime/create-requirement.ts`). Read once at framework construction,
-     * like `model`, and never part of a Contract or its hash.
+     * cannot create a row without. Read once when the framework is constructed;
+     * never part of a Contract or its hash.
      *
-     * Optional so an Adapter that cannot state them is believed: core then checks
-     * nothing, and a missing value reaches the store as before.
+     * When absent, creates are not checked for missing values before they reach
+     * the store.
      */
     readonly createRequirements?: CreateRequirementTable;
     /**
-     * Optional callback transaction capability, required exactly when the discovered
-     * model declares `transactions: "interactive"`. The callback receives only a
-     * transaction-scoped operation executor, never the provider client itself, and
-     * every operation of a plan executes through it.
+     * Optional callback transaction capability, required exactly when the
+     * discovered model declares `transactions: "interactive"`. The callback
+     * receives only a transaction-scoped operation executor, never the provider
+     * client itself, and every operation of a plan executes through it.
      *
-     * The implementation MUST reject with the exact value `work` threw — by identity,
-     * never a wrapper — and MUST NOT resolve after `work` rejected; rollback is
-     * implied by that rejection. Framework guards, pipes, hooks and interceptors of
-     * every plan operation run inside `work` while the provider transaction is open,
-     * so they must not perform network I/O or unrelated slow work.
+     * The implementation must reject with the exact value `work` threw — by identity,
+     * never a wrapper — and must not resolve after `work` rejected; rollback is
+     * implied by that rejection. Guards, pipes, hooks and interceptors of every plan
+     * operation run inside `work` while the provider transaction is open, so they must
+     * not perform network I/O or unrelated slow work.
      */
     transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
 }

package/dist/compiler/contract-compiler-diagnostic.d.ts

@@ -1,4 +1,11 @@
+/** Codes of {@link ContractCompilerDiagnostic}. */
 export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMPILER_UNKNOWN_FIELD" | "COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED" | "COMPILER_INCOMPLETE_FIELD" | "COMPILER_STRUCTURAL_FIELD_OVERRIDE" | "COMPILER_MISSING_SCALAR" | "COMPILER_MISSING_ENUM" | "COMPILER_DANGLING_RELATION" | "COMPILER_UNAVAILABLE_OPERATION" | "COMPILER_UNAVAILABLE_CAPABILITY" | "COMPILER_INVALID_LIFECYCLE" | "COMPILER_MISSING_READ_BEHAVIOR" | "COMPILER_INVALID_BEHAVIOR_DEPENDENCY"
+/**
+ * A field's `json` shape cannot apply: the field is not a Json field the
+ * adapter discovered, the value is not a shape built with `AvZ`, or the shape
+ * admits `null` or absence at its top level.
+ */
+ | "COMPILER_INVALID_JSON_SHAPE"
 /**
  * The finished, hashed client projection is not a structurally valid
  * `ClientContract`. A framework-bug guard: the server never serves what its own
@@ -6,6 +13,7 @@ export type ContractCompilerDiagnosticCode = "COMPILER_UNKNOWN_RESOURCE" | "COMP
  * (`$.enums.status.values[1]`).
  */
  | "COMPILER_INVALID_CLIENT_CONTRACT";
+/** One reason a configuration could not be compiled into Contracts. */
 export type ContractCompilerDiagnostic = {
     readonly code: ContractCompilerDiagnosticCode;
     readonly path: string;

package/dist/compiler/contract.compiler.d.ts

@@ -2,11 +2,16 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { ResolvedFrameworkConfig } from "../config/config.resolver.js";
 import type { ApplicationContract, ClientContract, CoreContract } from "../contracts/contract.js";
 import type { ContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** The Core, Application and Client Contracts compiled from one configuration. */
 export type FrameworkContracts = {
     readonly core: CoreContract;
     readonly application: ApplicationContract;
     readonly client: ClientContract;
 };
+/**
+ * The result of {@link compileContracts}: the three Contracts, or the
+ * diagnostics that stopped compilation.
+ */
 export type ContractCompilationResult = {
     readonly ok: true;
     readonly contracts: FrameworkContracts;
@@ -16,28 +21,12 @@ export type ContractCompilationResult = {
 };
 /**
  * Whether writing `configured` VERBATIM as capability member `key` would advertise
- * something `baseline` does not — the question the `fields` walk asks before it
- * copies a value onto an adapter field.
- *
- * Answered on the member's AXIS, off the same `satisfies`-pinned table the
- * restriction walk and the output gate read, and the baseline is read through the
- * shape's own owners: {@link holdsAt} for a position list, the `…At` readers for a
- * scope-qualified token arm. Never off the runtime shape of the value: an
- * object-shaped arm used to match no branch and pass unexamined, and `true` was
- * compared to the baseline with `!== true`, which reads a qualified baseline as
- * *not advertised* even where it holds in every position.
- *
- * The unqualified forms keep their meaning: `true` and a bare token list claim
- * every position on the axis, so either one over a qualified baseline is an
- * addition — writing it verbatim would widen the member.
- *
- * A key no axis covers, and a value its axis does not admit, are not additions;
- * they are unrepresentable, and the output gate ({@link
- * validateCapabilityRepresentation}) is the one place that says so. So is a
- * position off the axis.
- *
- * Exported for its unit test only; it is not part of the package surface.
+ * something `baseline` does not — the question the `fields` walk asks before it copies
+ * a value onto an adapter field.
  */
 export declare function capabilityAddsBaseline(fieldKind: "scalar" | "relation", baseline: Readonly<Record<string, unknown>>, key: string, configured: unknown): boolean;
-/** Compile Core first, then derive Application and Client from the Core compilation lineage. */
+/**
+ * Compiles the Core Contract from the adapter model and the root
+ * configuration, then the Application and Client Contracts from it.
+ */
 export declare function compileContracts<M extends AdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;

package/dist/compiler/contract.compiler.js

@@ -6,6 +6,7 @@ import { DEFAULT_CONTRACT_LIMITS, } from "../contracts/contract-limits.js";
 import { AVENTARA_PROTOCOL_VERSION } from "../contracts/contract-protocol.js";
 import { advertisedDirectives, advertisedDirectivesAt, advertisedReducers, advertisedReducersAt, holdsAt, holdsInAnyScope, } from "../contracts/field.js";
 import { isOperationVariantAvailable, } from "../contracts/resource-operations.js";
+import { bindShapedField, jsonShapeOf } from "../json/json-shape.registry.js";
 const UNIQUE_VARIANTS = [
     ["find", "unique"],
     ["update", "unique"],
@@ -99,6 +100,9 @@ function createBaseline(model) {
         ])),
         limits: { ...DEFAULT_CONTRACT_LIMITS },
         transactions: model.transactions,
+        ...(model.referenceWrites === undefined
+            ? {}
+            : { referenceWrites: model.referenceWrites }),
     };
 }
 function scalarFieldPath(scope, resource, field) {
@@ -111,6 +115,10 @@ function structuralValueMatches(field, config, key) {
     return JSON.stringify(field[key]) === JSON.stringify(config[key]);
 }
 function addConfiguredScalarField(config, path, diagnostics) {
+    if (config.json !== undefined) {
+        refuseJsonShape(path, "is not a field of the adapter model", diagnostics);
+        return undefined;
+    }
     const missing = ["type", "nullable", "list"].filter((key) => config[key] === undefined);
     if (missing.length > 0) {
         diagnostics.push(diagnostic("COMPILER_INCOMPLETE_FIELD", path, `framework-added scalar field is missing required properties: ${missing.join(", ")}`));
@@ -157,6 +165,8 @@ export function capabilityAddsBaseline(fieldKind, baseline, key, configured) {
     }
     const baselineValue = baseline[key];
     switch (axis.kind) {
+        case "limit":
+            return baselineValue !== undefined && configured !== baselineValue;
         case "flag":
             return configured === true && baselineValue !== true;
         case "tokens": {
@@ -213,6 +223,31 @@ function advertisedTokensAt(tokenKey, baselineValue, position) {
         ? advertisedDirectivesAt(baselineValue, position)
         : advertisedReducersAt(baselineValue, position);
 }
+function fieldLabel(path) {
+    const [, resource, , field] = path.split(".").slice(1);
+    return `${resource}.${field}`;
+}
+function refuseJsonShape(path, reason, diagnostics) {
+    diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}" ${reason}; only a Json field the adapter discovered may declare a "json" shape`));
+}
+function applyJsonShape(field, baselineField, shape, path, diagnostics) {
+    const type = baselineField.type;
+    if (type.scalar !== "json") {
+        refuseJsonShape(path, `is ${type.scalar === undefined ? "an enum" : `${/^[aeiou]/.test(type.scalar) ? "an" : "a"} ${type.scalar}`} field`, diagnostics);
+        return;
+    }
+    const runtime = jsonShapeOf(shape);
+    if (runtime === undefined) {
+        diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}": "json" must be a shape built with AvZ from "@aventara/core/json"; a Zod schema or any other value is not accepted`));
+        return;
+    }
+    if (runtime.validate(null).length === 0 ||
+        runtime.validate(undefined).length === 0) {
+        diagnostics.push(diagnostic("COMPILER_INVALID_JSON_SHAPE", `${path}.json`, `field "${fieldLabel(path)}": a field's shape cannot admit null or absence at its top level; whether the field may be null comes from the adapter model`));
+        return;
+    }
+    field.json = cloneValue(runtime.schema);
+}
 function applyExistingScalarConfig(field, baselineField, config, path, diagnostics) {
     for (const key of ["type", "nullable", "list"]) {
         if (!structuralValueMatches(field, config, key)) {
@@ -222,6 +257,9 @@ function applyExistingScalarConfig(field, baselineField, config, path, diagnosti
     if (config.format !== undefined) {
         field.format = config.format;
     }
+    if (config.json !== undefined) {
+        applyJsonShape(field, baselineField, config.json, path, diagnostics);
+    }
     if (config.lifecycle !== undefined) {
         diagnostics.push(diagnostic("COMPILER_INVALID_LIFECYCLE", `${path}.lifecycle`, "existing adapter field lifecycle cannot be redefined by framework field configuration"));
     }
@@ -243,6 +281,9 @@ function applyFrameworkOwnedScalarConfig(field, config, path, diagnostics) {
             field[key] = cloneValue(config[key]);
         }
     }
+    if (config.json !== undefined) {
+        refuseJsonShape(path, "is not a field of the adapter model", diagnostics);
+    }
     if (config.format !== undefined) {
         field.format = config.format;
     }
@@ -391,6 +432,7 @@ const RELATION_CAPABILITY_AXES = {
     },
     create: { kind: "scopedTokens", tokenKey: "directives", axis: WRITE_SCOPES },
     update: { kind: "scopedTokens", tokenKey: "directives", axis: WRITE_SCOPES },
+    nestedWriteFilter: { kind: "limit", values: ["scalar"] },
 };
 function capabilityAxisFor(kind, key) {
     const axes = kind === "scalar" ? SCALAR_CAPABILITY_AXES : RELATION_CAPABILITY_AXES;
@@ -478,6 +520,10 @@ function applyScopedTokenRestriction(tokenKey, axis, baselineValue, current, key
     return true;
 }
 function applyCapabilityRestriction(fieldKind, inherited, restoration, current, key, value, path, diagnostics) {
+    if (capabilityAxisFor(fieldKind, key)?.kind === "limit") {
+        unavailableCapability(path, `capability "${key}" is an adapter limit and takes no restriction`, diagnostics);
+        return;
+    }
     if (value === false) {
         delete current[key];
         return;
@@ -728,6 +774,10 @@ function positionListFault(axis, positions) {
 }
 function representationFault(axis, value) {
     switch (axis.kind) {
+        case "limit":
+            return typeof value === "string" && axis.values.includes(value)
+                ? undefined
+                : `one of ${axis.values.join(", ")} is expected`;
         case "flag":
             return typeof value === "boolean" ? undefined : "a boolean is expected";
         case "tokens":
@@ -827,6 +877,20 @@ function projectDerivedScope(model, scopeName, core, scope, diagnostics) {
     validateProjection(projection, baseline, scopeName, scope.restrictions, diagnostics);
     return projection;
 }
+function bindShapedFields(contract, fields) {
+    for (const [resourceName, resource] of Object.entries(contract.resources)) {
+        for (const [fieldName, field] of Object.entries(resource.fields)) {
+            if (field.kind !== "scalar" || field.json === undefined) {
+                continue;
+            }
+            const shape = jsonShapeOf(fields?.[resourceName]?.[fieldName]?.json);
+            if (shape === undefined) {
+                throw new Error(`the Contract compiler found no shape for shaped field "${resourceName}.${fieldName}"`);
+            }
+            bindShapedField(field, shape);
+        }
+    }
+}
 export async function compileContracts(model, config) {
     const compilerConfig = config;
     const diagnostics = [];
@@ -856,6 +920,9 @@ export async function compileContracts(model, config) {
             ],
         };
     }
+    bindShapedFields(core, compilerConfig.root.fields);
+    bindShapedFields(application, compilerConfig.application.fields);
+    bindShapedFields(client, compilerConfig.client.fields);
     return {
         ok: true,
         contracts: { core, application, client },

package/dist/config/any-framework-config.d.ts

@@ -1,11 +1,4 @@
-/**
- * A `fields` block whose resource and field names are both unconstrained.
- *
- * The `undefined` in the value position is required, not incidental: under
- * `exactOptionalPropertyTypes` a real `fields` block is a `Partial` record,
- * so its values include `undefined` and it would not otherwise be assignable
- * to the widest block.
- */
+/** A `fields` block whose resource and field names are both unconstrained. */
 export type AnyFieldsBlock = Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
 /** The widest scope overlay: a `fields` block, and anything else. */
 export type AnyScopeConfig = {
@@ -13,24 +6,10 @@ export type AnyScopeConfig = {
     readonly fields?: AnyFieldsBlock;
 };
 /**
- * The widest authoring configuration: every resource admits every field name.
- *
- * This is the default argument of the `Cfg` parameter threaded through
- * `FrameworkScopeConfig`, `FrameworkConfig`, `Framework` and
- * `createFramework`. Because it constrains nothing, a `FrameworkConfig<M>`
- * written without a `Cfg` argument behaves exactly as it did before `Cfg`
- * existed: narrowing below the resource key is opt-in, never imposed.
- *
- * `Cfg` is the authored configuration literal itself, not a shape the
- * framework validates. Its only job is to carry the field names the
- * configuration adds — at the root layer and at each scope overlay — so that
- * a resource's effective field-key set is computable from the adapter model
- * plus the configuration alone, and never from a compiled Contract.
- *
- * The index signature is what makes "widest" true. Without it this is a weak
- * type, and a configuration that happens to declare no `fields`,
- * `application` or `client` would have no property in common with it and be
- * rejected — the opposite of the intended default.
+ * The widest configuration type: every resource admits every field name. It
+ * is the default `Cfg` of `FrameworkConfig`, `Framework` and
+ * `createFramework`; pass your own configuration's type instead to get field
+ * names checked.
  */
 export type AnyFrameworkConfig = {
     readonly [key: string]: unknown;

package/dist/config/config-diagnostic.d.ts

@@ -1,4 +1,6 @@
+/** Codes of {@link ConfigDiagnostic}. */
 export type ConfigDiagnosticCode = "CONFIG_REQUIRED" | "CONFIG_UNKNOWN_PROPERTY" | "CONFIG_INVALID_TYPE" | "CONFIG_INVALID_VALUE";
+/** One problem found in a configuration, at its path. */
 export type ConfigDiagnostic = {
     readonly code: ConfigDiagnosticCode;
     readonly path: string;

package/dist/config/config-layer.d.ts

@@ -1,25 +1,12 @@
 /**
- * One layer of the configuration tree the framework is built on: `root` is the
- * configuration's own top level and compiles to the Core Contract; `application`
- * and `client` are the overlays resolved on top of it and compile to the
- * Application and Client Contracts.
- *
- * The one source of truth for the layer set. {@link RequestOrigin} is derived
- * from it rather than declared beside it, so the two cannot drift.
- *
- * Deliberately not named `…Scope`: that word already carries several unrelated
- * meanings in this package (the framework scope configuration, the pipeline
- * `scope`, and the capability positions `ProjectionScope`/`WriteScope`), and a
- * layer of the configuration tree is none of them.
+ * One layer of the configuration: `root` is the configuration's own top level
+ * and compiles to the Core Contract; `application` and `client` are overlays
+ * on top of it and compile to the Application and Client Contracts.
  */
 export type ConfigLayer = "root" | "application" | "client";
 /**
- * The layers a request can originate at: every {@link ConfigLayer} except
- * `root`. `root` is a real layer for the compiler — the Core Contract every
- * other layer derives from — but no request is ever made against it, so it is
- * not an origin.
- *
- * It is also the set of overlays a configuration may declare, because each
- * origin sees exactly the root layer plus its own overlay.
+ * The layers a request can come from: `application` (in-process calls) or
+ * `client` (remote calls). Each sees the root configuration plus its own
+ * overlay.
  */
 export type RequestOrigin = Exclude<ConfigLayer, "root">;

package/dist/config/config.resolver.d.ts

@@ -2,39 +2,34 @@ import type { Adapter } from "../adapters/adapter.interface.js";
 import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { TransactionCapability } from "../contracts/transaction-capability.js";
 import type { FrameworkDiagnosticsSink } from "../runtime/diagnostics-reporter.js";
+import type { FrameworkMisuseSink } from "../runtime/misuse-reporter.js";
 import type { FrameworkBehaviorsConfig } from "./framework-behaviors-config.js";
 import type { FrameworkConfig, FrameworkLimitsConfig } from "./framework-config.js";
 import type { FrameworkFieldsConfig } from "./framework-fields-config.js";
 import type { FrameworkRestrictionsConfig } from "./framework-restrictions-config.js";
 import type { ResolvedPipelineConfig } from "./pipeline-config.js";
+/** One resolved layer of the configuration: root, application or client. */
 export type ResolvedFrameworkScopeConfig<M extends AdapterModel = AdapterModel> = {
     readonly fields: FrameworkFieldsConfig<M> | undefined;
-    /**
-     * The **erased** behaviors view, deliberately not `FrameworkBehaviorsConfig<M>`.
-     *
-     * A compute context carries `resource: R`, so a behavior bound to one
-     * Resource is a callback that accepts only that Resource's name. That makes
-     * `FrameworkBehaviorsConfig<M>` contravariant in the Resource key and *not*
-     * a subtype of the widest instantiation — correctly so. The runtime dispatches
-     * by string key and can never recover which literal it holds, so it consumes
-     * behaviors erased, exactly as it consumes the compiled Contract: narrowing is
-     * an authoring-time affordance, and resolution is the boundary where it ends.
-     */
+    /** The behaviors configuration, with Resource and field keys as plain strings. */
     readonly behaviors: FrameworkBehaviorsConfig | undefined;
     readonly restrictions: FrameworkRestrictionsConfig<M> | undefined;
     readonly limits: FrameworkLimitsConfig | undefined;
     readonly pipelines: ResolvedPipelineConfig;
     readonly transactions: TransactionCapability | undefined;
 };
+/** A configuration after defaults and overlays are resolved, before compilation. */
 export type ResolvedFrameworkConfig<M extends AdapterModel = AdapterModel> = {
     /**
-     * The mount path in its canonical form: `""` at the root, otherwise `/seg(/seg)*`.
-     * Normalized once, here; every reader sees this.
+     * The mount path in its canonical form: `""` at the root, otherwise
+     * `/seg(/seg)*`.
      */
     readonly entrypoint: string;
     readonly adapter: Adapter<M>;
-    /** Root-only, never scoped: the framework owns this channel. */
+    /** The diagnostics sink, from the root configuration only. */
     readonly diagnostics: FrameworkDiagnosticsSink | undefined;
+    /** The misuse sink, from the root configuration only. */
+    readonly misuse: FrameworkMisuseSink | undefined;
     readonly root: ResolvedFrameworkScopeConfig<M>;
     readonly application: ResolvedFrameworkScopeConfig<M>;
     readonly client: ResolvedFrameworkScopeConfig<M>;

package/dist/config/config.resolver.js

@@ -103,6 +103,7 @@ export function resolveFrameworkConfig(config) {
         entrypoint: resolveEntrypoint(config.entrypoint),
         adapter: config.adapter,
         diagnostics: config.diagnostics,
+        misuse: config.misuse,
         root: resolveScope(root),
         application: resolveScope(root, config.application),
         client: resolveScope(root, config.client),

package/dist/config/config.validator.d.ts

@@ -1,9 +1,12 @@
 import type { ConfigDiagnostic } from "./config-diagnostic.js";
 /**
  * The refusal of an entrypoint whose mount path is not canonical, from the
- * normalizer's message: it names the defect and the rule — never the value, which
- * may carry credentials.
+ * normalizer's message: it names the defect and the rule — never the value, which may
+ * carry credentials.
  */
 export declare function entrypointRefusalDiagnostic(message: string): ConfigDiagnostic;
-/** Validate framework-owned authoring structure; later semantic leaves remain opaque. */
+/**
+ * Checks the structure of a configuration object and reports each problem as
+ * a {@link ConfigDiagnostic}.
+ */
 export declare function validateFrameworkConfig(value: unknown): readonly ConfigDiagnostic[];

package/dist/config/config.validator.js

@@ -10,6 +10,7 @@ const ROOT_PROPERTIES = new Set([
     "pipelines",
     "transactions",
     "diagnostics",
+    "misuse",
     "application",
     "client",
 ]);
@@ -206,6 +207,11 @@ export function validateFrameworkConfig(value) {
         typeof value.diagnostics !== "function") {
         diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "diagnostics", "diagnostics must be a function when provided"));
     }
+    if (Object.hasOwn(value, "misuse") &&
+        value.misuse !== undefined &&
+        typeof value.misuse !== "function") {
+        diagnostics.push(diagnostic("CONFIG_INVALID_TYPE", "misuse", "misuse must be a function when provided"));
+    }
     if (Object.hasOwn(value, "application")) {
         validateScope(value.application, "application", diagnostics);
     }

package/dist/config/define-fields.d.ts

@@ -2,55 +2,33 @@ import type { AdapterModel } from "../adapters/adapter-model.js";
 import type { AdapterFieldKey } from "../adapters/adapter-resource.js";
 import type { FrameworkResourceKey, FrameworkScalarFieldConfig, FrameworkScalarTypeRef } from "./framework-fields-config.js";
 /**
- * What an author may still say about a field the adapter already discovered.
- *
- * Everything in {@link FrameworkScalarFieldConfig} except `type`: the adapter
- * owns a discovered field's scalar/enum identity, so restating it here would
- * create a second source of truth for a fact discovery already settled.
- * `type?: never` rather than an omission so the rejection is a pointed
- * assignability error at the offending property, not a whole-object one.
+ * What a configuration may say about a field the adapter already discovered:
+ * everything in {@link FrameworkScalarFieldConfig} except `type`.
  */
 export type KnownScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type"> & {
     readonly type?: never;
 };
 /**
- * A scalar field the configuration adds, which the adapter never discovered.
- *
- * Nothing upstream can supply the structural leaves for a name that exists
- * nowhere in the provider, so `type`, `nullable` and `list` are required
- * here while they stay optional on the augmentation shape.
+ * A scalar field the configuration adds, which the adapter did not discover.
+ * `type`, `nullable` and `list` are required; it takes no `json` shape.
  */
-export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list"> & {
+export type AddedScalarFieldConfig<M extends AdapterModel = AdapterModel> = Omit<FrameworkScalarFieldConfig<M>, "type" | "nullable" | "list" | "json"> & {
     readonly type: FrameworkScalarTypeRef<M>;
     readonly nullable: boolean;
     readonly list: boolean;
+    readonly json?: never;
 };
-/**
- * The shape one authored field name admits, by what the adapter knows of it.
- *
- * Where there is no discovered key set to discriminate on, the answer is today's
- * undivided {@link FrameworkScalarFieldConfig}.
- */
+/** The shape one authored field name admits, by what the adapter knows of it. */
 type ScalarFieldConfigFor<M extends AdapterModel, R extends FrameworkResourceKey<M>, F> = string extends AdapterFieldKey<M, R> ? FrameworkScalarFieldConfig<M> : F extends AdapterFieldKey<M, R> ? M["resources"][R]["fields"][F] extends {
     readonly kind: "relation";
-} ? never : KnownScalarFieldConfig<M> : AddedScalarFieldConfig<M>;
-/**
- * The constraint an authored `fields` block is checked against, keyed on the
- * block's **own** names.
- *
- * `Self` is the literal being checked, which is why {@link defineFields} is
- * F-bounded: a `satisfies FrameworkFieldsConfig<M>` annotation maps the
- * value shape over an open key set, which collapses to a single index
- * signature, and an index signature cannot tell a discovered name from an
- * added one. The three buckets are only reachable from a mapped type keyed
- * on `keyof Self`.
- *
- * The self-reference is legal here despite the workstream's stopping rule 3
- * because the `fields` block carries no callbacks: nothing inside it needs
- * contextual typing, so there is no inference to collapse. A callback
- * appearing in this block is the signal that this encoding has stopped
- * being safe.
- */
+} ? never : M["resources"][R]["fields"][F] extends {
+    readonly type: {
+        readonly scalar: "json";
+    };
+} ? KnownScalarFieldConfig<M> : Omit<KnownScalarFieldConfig<M>, "json"> & {
+    readonly json?: never;
+} : AddedScalarFieldConfig<M>;
+/** The shape an authored `fields` block is checked against, keyed on its own names. */
 export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
     readonly [R in keyof Self]: R extends FrameworkResourceKey<M> ? {
         readonly [F in keyof Self[R]]: ScalarFieldConfigFor<M, R, F>;
@@ -59,17 +37,6 @@ export type FrameworkFieldsShape<M extends AdapterModel, Self> = {
 /**
  * Authors stage 1 of a configuration: the `fields` block, checked against
  * what the adapter discovered and returned unwidened.
- *
- * The returned literal is stage 2's `Cfg` fields block, so the names it adds
- * are nameable from `restrictions`, `behaviors` and `dependsOn`.
- *
- * `M` is bound by the **model value**, not a type argument: TypeScript has
- * no partial type-argument inference, so `defineFields<M>({ … })` would
- * force `Self` to be written out by hand. The model is already a value at
- * the authoring site, so binding it there costs nothing.
- *
- * The model argument is type-level only — the returned block is the authored
- * one, unchanged.
  */
 export declare function defineFields<M extends AdapterModel, const Self extends FrameworkFieldsShape<M, Self>>(_model: M, fields: Self): Self;
 export {};

package/dist/config/effective-fields.d.ts

@@ -13,41 +13,18 @@ import type { FrameworkResourceKey } from "./framework-fields-config.js";
 type FieldsBlockOf<Layer> = Layer extends {
     readonly fields?: infer Block;
 } ? Block extends AnyFieldsBlock ? Block : never : never;
-/**
- * The field names a single `fields` block declares for `R`.
- *
- * The `[Block] extends [never]` guard is load-bearing, not defensive: `keyof
- * never` is `string | number | symbol`, so a layer with no `fields` block
- * would otherwise widen the whole effective key set back to `string` and
- * silently erase every narrowing downstream of it.
- */
+/** The field names a single `fields` block declares for `R`. */
 type FieldsBlockKey<Block, R extends string> = [Block] extends [never] ? never : R extends keyof Block ? Extract<keyof NonNullable<Block[R]>, string> : never;
-/**
- * The field names `Cfg`'s own root `fields` block adds for `R`.
- *
- * Under the default `Cfg` this degenerates to `string`: `AnyFieldsBlock` maps
- * every resource name to an open record, so the effective key set widens back to
- * an index-signature-compatible `string` and today's wide acceptance is preserved.
- */
+/** The field names the configuration's root `fields` block adds to Resource `R`. */
 export type ConfigFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = FieldsBlockKey<FieldsBlockOf<Cfg>, R>;
-/**
- * The single answer to "what are `R`'s field names under this configuration".
- *
- * Nothing else in the framework may compute a field-key set; `restrictions`,
- * `behaviors` and `dependsOn` all key on this type.
- *
- * There is deliberately no subtraction here. A `HiddenFieldKey` subtraction would
- * contradict the Accepted ADR and must not be reintroduced.
- */
+/** The single answer to "what are `R`'s field names under this configuration". */
 export type EffectiveFieldKey<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>> = AdapterFieldKey<M, R> | ConfigFieldKey<M, Cfg, R>;
 /** The overlay `Cfg` carries for `Origin`, or `never` when it declares none. */
 type OriginOverlayOf<Cfg, Origin extends RequestOrigin> = Origin extends keyof Cfg ? NonNullable<Cfg[Origin]> : never;
 /**
- * `R`'s effective field names as seen from one request origin: the root layer
- * plus whatever the `application` or `client` overlay adds on top of it.
- *
- * Origins are siblings, never parents: an overlay contributes to its own origin
- * only, so a name added under `client` is not visible under `application`.
+ * `R`'s field names as seen from one request origin: the root layer plus
+ * whatever the `application` or `client` overlay adds. A name added under
+ * `client` is not visible under `application`, and the other way round.
  */
 export type EffectiveFieldKeyAt<M extends AdapterModel, Cfg, R extends FrameworkResourceKey<M>, Origin extends RequestOrigin> = EffectiveFieldKey<M, Cfg, R> | FieldsBlockKey<FieldsBlockOf<OriginOverlayOf<Cfg, Origin>>, R>;
 export {};