@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/compiler/contract-compiler-diagnostic.guidance.js

@@ -0,0 +1,97 @@
+export const CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE = {
+    COMPILER_UNKNOWN_RESOURCE: {
+        message: "Unknown Resource.",
+        cause: "A Resource name the adapter's model does not have, in resources or in exemptions; or a client or agent entry for a Resource managed elsewhere, which those layers never have.",
+        fix: "Use the model's exact name. After a schema change run `npm run aventara:prepare`. Configure a Resource managed elsewhere at the root or in application only.",
+    },
+    COMPILER_UNKNOWN_FIELD: {
+        message: "Unknown field.",
+        cause: "A field that is neither in the schema nor defined at the root.",
+        fix: "Fix the name, run aventara:prepare after a schema change, or add the field with a root definition.",
+    },
+    COMPILER_RELATION_FIELD_CONFIG_UNSUPPORTED: {
+        message: "A relation field takes write guards only.",
+        cause: "Field pipes or compute on a relation field.",
+        fix: "Put the stage on the relation's reference field, or use an operation pipe.",
+    },
+    COMPILER_INCOMPLETE_FIELD: {
+        message: "An added field is incomplete.",
+        cause: "A definition that adds a field leaves out type, nullable or list.",
+        fix: 'Spell out type, nullable and list, with lifecycle: ["VIRTUAL"] for a field that has no column.',
+    },
+    COMPILER_STRUCTURAL_FIELD_OVERRIDE: {
+        message: "A discovered field's structure was redefined.",
+        cause: "A definition on a field the adapter discovered changes its type, format or capabilities.",
+        fix: "Restate only its type, nullable and list. Change capabilities through exemptions and the column through the schema.",
+    },
+    COMPILER_MISSING_SCALAR: {
+        message: "Unknown scalar type.",
+        cause: "A definition names a scalar type that does not exist.",
+        fix: "Use a built-in scalar: string, boolean, int, float, bigint, decimal, datetime, bytes or json.",
+    },
+    COMPILER_MISSING_ENUM: {
+        message: "Unknown enum.",
+        cause: "A definition names an enum the model does not have.",
+        fix: "Use an enum of the schema, and run aventara:prepare after adding one.",
+    },
+    COMPILER_DANGLING_RELATION: {
+        message: "A visible relation points at a hidden Resource.",
+        cause: "A layer hides a Resource but still exposes a relation field that targets it.",
+        fix: "Hide the relation field too (`exemptions.resources.<R>.fields.<relation>: true`), or expose the target.",
+    },
+    COMPILER_UNAVAILABLE_OPERATION: {
+        message: "Operation not available.",
+        cause: "An operation the adapter does not offer (such as delete.many), or an overlay granting one that its parent hid.",
+        fix: "Remove it. To reach an operation from one overlay only, expose it at the root and hide it in the other overlay.",
+    },
+    COMPILER_UNAVAILABLE_CAPABILITY: {
+        message: "Capability not available.",
+        cause: "A capability or token the field does not offer, or an overlay (or the agent layer) granting one its parent hid. Overlays only narrow.",
+        fix: "Remove it, or expose it in the parent layer and hide it in the layer it must not reach.",
+    },
+    COMPILER_INVALID_LIFECYCLE: {
+        message: "Invalid field lifecycle.",
+        cause: "An added field declares a lifecycle other than VIRTUAL, a VIRTUAL field claims a database-generated lifecycle or a provider-side capability, or a definition redefines a discovered field's lifecycle.",
+        fix: 'Give an added field lifecycle: ["VIRTUAL"] and only the capabilities it can serve; computed lifecycles come from compute stages.',
+    },
+    COMPILER_MISSING_READ_COMPUTE: {
+        message: "A selectable virtual field has no compute.read.",
+        cause: "A VIRTUAL field that can be selected has no pipelines.compute.read stage.",
+        fix: "Add a compute.read stage, or make the field write-only with capabilities.select: false.",
+    },
+    COMPILER_INVALID_COMPUTE_DEPENDENCY: {
+        message: "Invalid compute.read dependency.",
+        cause: "A dependsOn entry that is not a stored scalar field of the same Resource.",
+        fix: "List only stored scalar fields of the Resource in dependsOn.",
+    },
+    COMPILER_RESERVED_RESOURCE_NAME: {
+        message: "Reserved Resource name.",
+        cause: "A model name starts with $, which is reserved for the framework's own names (ctx.$sql, $ref), or, on a host that adds members beside the Resources, is one of those members' names (on Next.js: tx and transaction on avClient, appTx and transaction on avApp).",
+        fix: "Rename the model; the table it maps to can keep its name. A host member's name is also left free when the layer it belongs to hides the Resource.",
+    },
+    COMPILER_MISSING_IDENTIFIER: {
+        message: "A unique operation has no identifier.",
+        cause: "A layer exposes a unique variant (find.unique, update.unique, delete.unique, upsert.unique) and no complete identifier of the Resource: a Pick that did not pick one, or an Omit that hid every one.",
+        fix: "Expose an identifier field (id, or every field of one unique), or exempt the unique variants.",
+    },
+    COMPILER_HIDDEN_REQUIRED_FIELD: {
+        message: "A layer that creates a Resource hides a required field.",
+        cause: "A layer still creates the Resource (a create or upsert variant, or a nested create) while a required field, or a required relation's reference field, is hidden or has its create capability exempted, and no compute.create fills it.",
+        fix: "Expose the field, give it a compute.create stage, or exempt the layer's create operations.",
+    },
+    COMPILER_INVALID_VALIDATOR: {
+        message: "A field validator cannot apply.",
+        cause: "A validator that is not built with AvZ, does not fit the field's type (AvZ.maxLength on an int, AvZ.maxItems on a field that is not a list), or sits on a relation or Json field.",
+        fix: "Use an AvZ check that fits the field's type; a Json field's checks go in its json shape.",
+    },
+    COMPILER_INVALID_JSON_SHAPE: {
+        message: "A Json shape cannot apply.",
+        cause: "A json shape on a field that is not a discovered Json field, a shape not built with AvZ, or one that admits null or absence at its top level.",
+        fix: "Put the shape on a Json field, build it with AvZ, and keep its top level non-null (the column's nullability decides null).",
+    },
+    COMPILER_INVALID_CLIENT_CONTRACT: {
+        message: "The compiled client contract is invalid.",
+        cause: "The finished client contract failed its own structural check: a framework defect.",
+        fix: "Report it with the diagnostic's path and message.",
+    },
+};

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

@@ -1,12 +1,17 @@
-import type { AdapterModel } from "../adapters/adapter-model.js";
+import type { AvAdapterModel } 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;
+import type { AvContractAgent, AvContractApplication, AvContractClient, AvContractCore } from "../contracts/contract.js";
+import type { AvContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** The Core, Application, Client and Agent Contracts compiled from one configuration. */
+export type AvContracts = {
+    readonly core: AvContractCore;
+    readonly application: AvContractApplication;
+    readonly client: AvContractClient;
+    /**
+     * The agent layer's Contract, which MCP tools are built from. With no `agent`
+     * layer configured it is the Client Contract's view.
+     */
+    readonly agent: AvContractAgent;
 };
 /**
  * The result of {@link compileContracts}: the three Contracts, or the
@@ -14,19 +19,20 @@ export type FrameworkContracts = {
  */
 export type ContractCompilationResult = {
     readonly ok: true;
-    readonly contracts: FrameworkContracts;
+    readonly contracts: AvContracts;
 } | {
     readonly ok: false;
-    readonly diagnostics: readonly ContractCompilerDiagnostic[];
+    readonly diagnostics: readonly AvContractCompilerDiagnostic[];
 };
 /**
- * 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.
+ * Compiles the Core Contract from the adapter model and the root
+ * configuration, then the Application and Client Contracts from it, then the
+ * Agent Contract from the view of the layer it extends.
  */
-export declare function capabilityAddsBaseline(fieldKind: "scalar" | "relation", baseline: Readonly<Record<string, unknown>>, key: string, configured: unknown): boolean;
+export declare function compileContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
 /**
- * Compiles the Core Contract from the adapter model and the root
- * configuration, then the Application and Client Contracts from it.
+ * Binds Contracts loaded from a prebuilt file to the runtime pieces
+ * {@link compileContracts} binds to the ones it compiles, from the live
+ * `config` and `model` they were compiled from.
  */
-export declare function compileContracts<M extends AdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;
+export declare function bindPrebuiltContracts<M extends AvAdapterModel>(model: M, config: ResolvedFrameworkConfig<M>, contracts: AvContracts): void;