@aventara/core 0.0.0-stage → 0.1.0-pilot.0

package/LICENSE

@@ -0,0 +1,91 @@
+Required Notice: Copyright 2026 Mohamed Ragheb
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/LICENSE-ADDITIONAL-PERMISSION.md

@@ -0,0 +1,9 @@
+# Additional Permission — Aventara
+
+Copyright 2026 Mohamed Ragheb
+
+In addition to the permissions of the PolyForm Shield License 1.0.0 in `LICENSE`, the licensor grants the following additional permission:
+
+The Noncompete section applies only to providing a product that competes with the software itself — the Aventara framework, its packages and its tooling. Providing a product that competes with any other product the licensor or its affiliates provide using the software is a permitted purpose.
+
+This additional permission only adds to your permissions; it does not restrict or replace any term of `LICENSE`.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# `@aventara/core`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Aventara framework itself: the framework factory (`createFramework`), configuration and its resolution, the
+adapter interfaces an ORM adapter implements, Contract compilation and identity, validation, operation semantics, the
+pipeline runtime, transactions and execution. Its HTTP protocol — passive data and pure functions; it mounts nothing —
+is the separate entry point `@aventara/core/protocol`, which hosts such as `@aventara/nest` serve.
+
+Core is ORM- and transport-agnostic: it imports neither Prisma nor NestJS. An application uses it through an adapter
+(`@aventara/prisma7-adapter`) and a host (`@aventara/nest`), and the usual way to set that up is the CLI.
+
+## Install
+
+```bash
+npx @aventara/cli new my-api     # a new NestJS project with Prisma and Aventara
+npx @aventara/cli init           # or: add Aventara to an existing NestJS 12 project
+npm install @aventara/core       # the package on its own
+```
+
+Node `^22.18.0 || >=24.2.0`. ES modules, with a CommonJS `default` condition.
+
+## Documentation
+
+Start from the `@aventara/cli` README (what `new` and `init` write), then `@aventara/nest` (mounting a `Framework`)
+and `@aventara/prisma7-adapter` (the Prisma 7 adapter and its generate step); each package's README ships in its
+tarball and shows on its npm page.
+
+## License
+
+PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
+use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/adapters/adapter-discovery-diagnostic.d.ts

@@ -0,0 +1,6 @@
+export type AdapterDiscoveryDiagnosticCode = "DISCOVERY_TRANSACTION_CAPABILITY_MISMATCH";
+export type AdapterDiscoveryDiagnostic = {
+    readonly code: AdapterDiscoveryDiagnosticCode;
+    readonly path: "adapter.transactions";
+    readonly message: string;
+};

package/dist/adapters/adapter-discovery-diagnostic.js

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

package/dist/adapters/adapter-field.d.ts

@@ -0,0 +1,52 @@
+import type { RelationFieldCapabilities, ScalarFieldCapabilities, ScalarFormat } from "../contracts/field.js";
+import type { LifecycleTrait } from "../contracts/lifecycle-trait.js";
+import type { AdapterModel } from "./adapter-model.js";
+/** Provider-observable lifecycle facts available during adapter discovery. */
+export type AdapterLifecycleTrait = Extract<LifecycleTrait, "DEFAULTED" | "GENERATED_ON_CREATE" | "GENERATED_ON_UPDATE">;
+/**
+ * Scalar-shaped provider field expressed only in Aventara vocabulary.
+ *
+ * Scalar capabilities carry no scope qualifier, measured and not assumed: all six
+ * members are uniform across every operation variant on both pilot engines, so a
+ * discoverer has nothing per-position to answer here.
+ */
+export type AdapterScalarField<M extends AdapterModel> = {
+    readonly kind: "scalar";
+    readonly type: {
+        readonly scalar: Extract<keyof M["scalars"], string>;
+    } | {
+        readonly enum: Extract<keyof M["enums"], string>;
+    };
+    readonly format?: ScalarFormat;
+    readonly nullable: boolean;
+    readonly list: boolean;
+    readonly lifecycle: readonly AdapterLifecycleTrait[];
+    readonly capabilities: ScalarFieldCapabilities;
+};
+/**
+ * Provider relation edge; the target AdapterResource owns object shape.
+ *
+ * The capabilities are the Contract's own {@link RelationFieldCapabilities}, scope
+ * qualifier included, and that sharing is the point: the ADAPTER is the only party
+ * that can measure which argument positions a relation is reachable in, because
+ * the answer depends on which provider call each operation variant is routed to.
+ * Core tabulating it would be a tabulated provider fact (D-802) and would be wrong
+ * for the next adapter.
+ *
+ * The qualifier is OPTIONAL at this boundary, as it is in the Contract: an adapter
+ * that has not measured the axis states the unqualified answer and is believed,
+ * which is what keeps a surface that predates the measurement meaningful rather
+ * than silently narrowed.
+ *
+ * **A scope qualifies the TOP LEVEL of an argument only** — the measurement and the
+ * reason are recorded on `ProjectionScope`, and a discoverer that narrows
+ * recursively would advertise less than the provider accepts.
+ */
+export type AdapterRelationField<M extends AdapterModel> = {
+    readonly kind: "relation";
+    readonly target: Extract<keyof M["resources"], string>;
+    readonly cardinality: "one" | "many";
+    readonly nullable: boolean;
+    readonly capabilities: RelationFieldCapabilities;
+};
+export type AdapterField<M extends AdapterModel> = AdapterScalarField<M> | AdapterRelationField<M>;

package/dist/adapters/adapter-field.js

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

package/dist/adapters/adapter-identifier.d.ts

@@ -0,0 +1,25 @@
+import type { AdapterField } from "./adapter-field.js";
+import type { AdapterModel } from "./adapter-model.js";
+/**
+ * Keys of `TFields` whose discovered field can be scalar-shaped.
+ *
+ * `TFields[K]` is an indexed access, not a naked type parameter, so a bare
+ * conditional would not distribute over a union-valued field. With the
+ * abstract `AdapterFieldMap` default every key maps to the whole
+ * `AdapterField` union, which is not a subtype of the scalar branch, so the
+ * bare form collapses to `never` and makes `AdapterIdentifier` uninhabitable.
+ * `Extract` selects the scalar branch out of the union instead, so a key is
+ * kept unless it is provably relation-only.
+ */
+export type AdapterScalarFieldKey<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = Extract<{
+    [K in keyof TFields]: [
+        Extract<TFields[K], {
+            readonly kind: "scalar";
+        }>
+    ] extends [never] ? never : K;
+}[keyof TFields], string>;
+/** Non-empty scalar-field tuple discovered as provider uniqueness. */
+export type AdapterIdentifier<TFields extends Readonly<Record<string, AdapterField<AdapterModel>>>> = readonly [
+    AdapterScalarFieldKey<TFields>,
+    ...AdapterScalarFieldKey<TFields>[]
+];

package/dist/adapters/adapter-identifier.js

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

package/dist/adapters/adapter-model.d.ts

@@ -0,0 +1,14 @@
+import type { EnumDefinition } from "../contracts/enum-definition.js";
+import type { ScalarRegistry } from "../contracts/scalar.js";
+import type { TransactionCapability } from "../contracts/transaction-capability.js";
+import type { AdapterResource } from "./adapter-resource.js";
+/**
+ * Canonical provider-discovery facts before framework configuration or
+ * Contract compilation is applied.
+ */
+export interface AdapterModel {
+    readonly scalars: ScalarRegistry;
+    readonly enums: Readonly<Record<string, EnumDefinition>>;
+    readonly resources: Readonly<Record<string, AdapterResource<this>>>;
+    readonly transactions: TransactionCapability;
+}

package/dist/adapters/adapter-model.js

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

package/dist/adapters/adapter-operation-executor.interface.d.ts

@@ -0,0 +1,6 @@
+import type { AdapterModel } from "./adapter-model.js";
+import type { AdapterOperation } from "./adapter-operation.js";
+/** Small execution seam usable both directly and inside provider transactions. */
+export interface AdapterOperationExecutor<M extends AdapterModel = AdapterModel> {
+    execute(operation: AdapterOperation<M>): Promise<unknown>;
+}

package/dist/adapters/adapter-operation-executor.interface.js

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

package/dist/adapters/adapter-operation.d.ts

@@ -0,0 +1,12 @@
+import type { OperationIdentity } from "../operations/operation-identity.js";
+import type { SemanticOperationArguments } from "../operations/operation-validator.js";
+import type { AdapterModel } from "./adapter-model.js";
+/**
+ * Provider execution request after framework semantic validation.
+ * Operation identity and arguments remain provider-neutral; adapters receive
+ * only validated semantic argument objects, never raw transport input.
+ */
+export type AdapterOperation<M extends AdapterModel = AdapterModel> = OperationIdentity & {
+    readonly resource: Extract<keyof M["resources"], string>;
+    readonly arguments: SemanticOperationArguments;
+};

package/dist/adapters/adapter-operation.js

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

package/dist/adapters/adapter-resource.d.ts

@@ -0,0 +1,43 @@
+import type { ResourceOperations } from "../contracts/resource-operations.js";
+import type { AdapterField } from "./adapter-field.js";
+import type { AdapterIdentifier } from "./adapter-identifier.js";
+import type { AdapterModel } from "./adapter-model.js";
+export type AdapterFieldMap<M extends AdapterModel> = Readonly<Record<string, AdapterField<M>>>;
+/**
+ * The field names the adapter discovered for `R`.
+ *
+ * This is the lower layer of `EffectiveFieldKey`, in
+ * `config/effective-fields.ts`: everything the provider already knows about,
+ * before any configuration is applied. Named in prose rather than with a
+ * `{@link}` because a resolvable link would need an import, and `adapters/`
+ * must not reach into `config/`.
+ *
+ * `R`'s constraint is written out rather than imported as
+ * `FrameworkResourceKey<M>` — the identical type — because `adapters/` owns
+ * the Base layer and must not depend on `config/`.
+ */
+export type AdapterFieldKey<M extends AdapterModel, R extends Extract<keyof M["resources"], string>> = Extract<keyof M["resources"][R]["fields"], string>;
+/**
+ * Provider-discovered facts for one Aventara Resource candidate.
+ *
+ * `TFields` is never supplied by a caller — every in-repo site writes
+ * `AdapterResource<M>` — but it is **load-bearing and must not be inlined**.
+ * It is the indirection that keeps `M` out of this type's body.
+ *
+ * `AdapterField<M>` is invariant in `M` (it reads `keyof M["scalars"]` and
+ * `keyof M["resources"]`). If `M` reached the body, `AdapterResource` would
+ * acquire an invariant variance marker, and every concrete model would stop
+ * satisfying the self-typed `AdapterModel.resources: Readonly<Record<string,
+ * AdapterResource<this>>>` constraint. Measured: 43 type errors across the
+ * adapter and index type tests, and identically 43 whether the parameter is
+ * deleted or merely bypassed — so it is the body occurrence that matters,
+ * not the arity.
+ *
+ * This is why F-601 ("the second type parameter is dead") was closed as
+ * mistaken rather than actioned. Deleting it is not a cleanup.
+ */
+export type AdapterResource<M extends AdapterModel, TFields extends AdapterFieldMap<M> = AdapterFieldMap<M>> = {
+    readonly fields: TFields;
+    readonly identifiers: readonly AdapterIdentifier<TFields>[];
+    readonly operations: ResourceOperations;
+};

package/dist/adapters/adapter-resource.js

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

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

@@ -0,0 +1,41 @@
+import type { ReferentialActionTable } from "../runtime/referential-action.js";
+import type { AdapterModel } from "./adapter-model.js";
+import type { AdapterOperationExecutor } from "./adapter-operation-executor.interface.js";
+/** 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.
+     */
+    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.
+     *
+     * Direction, because getting it backwards is silent: an edge listed under
+     * Resource `R` says **deleting a `target` row does `onDelete` to rows of
+     * `R`**.
+     *
+     * 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`).
+     */
+    readonly referentialActions?: ReferentialActionTable;
+    /**
+     * 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 (spec §14.5).
+     */
+    transaction?<T>(work: (executor: AdapterOperationExecutor<M>) => Promise<T>): Promise<T>;
+}

package/dist/adapters/adapter.interface.js

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

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

@@ -0,0 +1,14 @@
+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"
+/**
+ * The finished, hashed client projection is not a structurally valid
+ * `ClientContract` (`validateClientContractStructure`; Phase 10 R3, the
+ * architect's code, 2026-10-05). A framework-bug guard: the server never
+ * serves what its own generator would refuse. `path` is the JSONPath
+ * inside the ClientContract (`$.enums.status.values[1]`).
+ */
+ | "COMPILER_INVALID_CLIENT_CONTRACT";
+export type ContractCompilerDiagnostic = {
+    readonly code: ContractCompilerDiagnosticCode;
+    readonly path: string;
+    readonly message: string;
+};

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

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

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

@@ -0,0 +1,42 @@
+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";
+export type FrameworkContracts = {
+    readonly core: CoreContract;
+    readonly application: ApplicationContract;
+    readonly client: ClientContract;
+};
+export type ContractCompilationResult = {
+    readonly ok: true;
+    readonly contracts: FrameworkContracts;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly ContractCompilerDiagnostic[];
+};
+/**
+ * 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 (F-817).
+ *
+ * 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 (C-855).
+ *
+ * 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.
+ */
+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. */
+export declare function compileContracts<M extends AdapterModel>(model: M, config: ResolvedFrameworkConfig<M>): Promise<ContractCompilationResult>;