@aventara/core 0.1.0-pilot.1 → 0.1.0-pilot.2

package/dist/transactions/transaction-reference-validator.js

@@ -10,11 +10,6 @@ function failure(rejection, operation) {
         response: transactionOperationFailure(mapValidationOutcome([rejection]), operation),
     };
 }
-/**
- * Inspects one control record. A non-record value, arrays included, is
- * classified by the caller's `nonRecordIssue`; reflection failures are
- * contained as `V1001` at the record path.
- */
 function inspectControlObject(value, allowed, path, nonRecordIssue) {
     if (typeof value !== "object" || value === null) {
         return { ok: false, issue: nonRecordIssue };
@@ -168,7 +163,6 @@ function sameType(source, destination) {
 }
 const CANDIDATE_KEYS = new Set(["$ref"]);
 const REFERENCE_KEYS = new Set(["operation", "fingerprint", "path"]);
-/** Validates every passive reference candidate before operation fingerprinting. */
 export function validateTransactionReferences(operation, earlier) {
     const references = [];
     for (const slot of operation.candidates) {
@@ -236,8 +230,6 @@ export function validateTransactionReferences(operation, earlier) {
         if (projection === undefined || !projection.requested.includes(segment)) {
             return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);
         }
-        // The source's own Contract: in a plan that mixes origins, a source field the
-        // referencing step's layer hides is still the source's to read.
         const sourceField = lookupField(lookupResource(source.contract, projection.resource), segment);
         if (sourceField === undefined) {
             return failure(validationIssue("V1010", pathPath, "Transaction reference path is not present in the source projection."), operation.index);

package/dist/transactions/transaction-reference.d.ts

@@ -29,79 +29,55 @@ export type TransactionReferenceCandidateRoute = {
 };
 /**
  * Total descriptor-only routing for a scalar value at a transaction-reference
- * position. Reflection failures stay candidates so Task 7 can report their
- * full wire path instead of losing them to ordinary scalar validation.
+ * position.
  */
 export declare function routeTransactionReferenceCandidate(value: unknown): TransactionReferenceCandidateRoute;
-/** Broad routing guard only; validation of `$ref` members belongs to Task 7. */
 export declare function isTransactionReferenceCandidate(value: unknown): value is TransactionReferenceCandidate;
 /**
- * Narrows a structurally complete `$ref` object. DA-15 semantic validation
- * (index ordering, source fingerprint, path existence, and type) stays in
- * the transaction reference validator.
+ * Narrows a structurally complete `$ref` object.
  */
 export declare function isTransactionReferenceObject(value: unknown): value is TransactionReference;
 /**
- * A scalar mutation value inside a plan: the value itself, or a reference to
- * an earlier operation's field of that same type (DA-3).
+ * A scalar mutation value inside a plan: the value itself, or a reference to an
+ * earlier operation's field of that same type.
  */
 export type TransactionScalarValue<Value> = Value | TransactionReference<Value>;
 /**
- * One DA-3 position's value, read under two scalar-form maps: `Forms` for the
- * value the caller writes, `ReferenceForms` for the value a `$ref` carries. A
- * reference carries its source's final data, which every scope returns in the
+ * A reference carries its source's final data, which every scope returns in the
  * application forms; so a client-origin builder writes wire forms and still takes
- * a `$ref` typed by the application form of the same Contract field — strict
- * type compatibility (D-710) compares Contract field types, never their forms.
- * Unstated, both are the same map and this is {@link TransactionScalarValue}.
+ * a `$ref` typed by the application form of the same Contract field — strict type
+ * compatibility compares Contract field types, never their forms. Unstated, both
+ * are the same map and this is {@link TransactionScalarValue}.
  */
 type ReferenceableValue<Value, ReferenceValue> = Value | TransactionReference<ReferenceValue>;
-/**
- * `Data`'s member `Key`, or `never` when it has none: the reference half of a
- * DA-3 position reads the same key under the reference forms, where an
- * intersection index (`Data[Key & keyof Data]`) would make the generic
- * declaration below relate two deferred `keyof`s of the whole data type — the
- * same answer, measured at ≈47,000 instantiations of `packages/core`'s own check.
- */
 type MemberOf<Data, Key> = Key extends keyof Data ? Data[Key] : never;
 /**
- * `CreateDataInput` with DA-3 reference positions opened, under one value form
- * and one reference form. The exported {@link TransactionCreateDataInput} is it
- * with neither form stated; the typed builders state both.
+ * The exported {@link TransactionCreateDataInput} is it with neither form stated;
+ * the typed builders state both.
  */
 export type ReferenceableCreateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in keyof CreateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "create", Scope> ? CreateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<CreateDataInput<C, K, Scope, Forms>[F], MemberOf<CreateDataInput<C, K, Scope, ReferenceForms>, F>>;
 }>;
-/** `UpdateDataInput` with DA-3 reference positions opened; see {@link ReferenceableCreateData}. */
 export type ReferenceableUpdateData<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = Readonly<{
     [F in keyof UpdateDataInput<C, K, Scope, Forms>]: F extends WritableRelationKey<C, K, "update", Scope> ? UpdateDataInput<C, K, Scope, Forms>[F] : ReferenceableValue<UpdateDataInput<C, K, Scope, Forms>[F], MemberOf<UpdateDataInput<C, K, Scope, ReferenceForms>, F>>;
 }>;
 /**
- * `CreateDataInput` with DA-3 reference positions opened, **at one write
- * position**. Only top-level scalar fields accept a `$ref`; a relation field
- * keeps its relation mutation action, where a `$ref` is an ordinary invalid
- * value.
+ * Only top-level scalar fields accept a `$ref`; a relation field keeps its
+ * relation mutation action, where a `$ref` is an ordinary invalid value.
  *
- * The position is the standalone surface's, read the same way: both surfaces
- * read one capability value and differ only in where they bind it, so a plan's
- * flat bulk write refuses a nested-only relation exactly as `create.many` does
- * outside a plan (F-811). The default is the unrestricted position, as on
- * `CreateDataInput`.
+ * The position is the standalone surface's, read the same way: both surfaces read
+ * one capability value and differ only in where they bind it, so a plan's flat
+ * bulk write refuses a nested-only relation exactly as `create.many` does outside
+ * a plan. The default is the unrestricted position, as on `CreateDataInput`.
  */
 export type TransactionCreateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableCreateData<C, K, Scope, ScalarForms, ScalarForms>;
 /**
- * `UpdateDataInput` with the same DA-3 scalar-only reference positions, at one
- * write position. See {@link TransactionCreateDataInput}.
+ * See {@link TransactionCreateDataInput}.
  */
 export type TransactionUpdateDataInput<C extends Contract, K extends ResourceKey<C>, Scope extends WriteScope = "nested"> = ReferenceableUpdateData<C, K, Scope, ScalarForms, ScalarForms>;
 /**
- * Operation arguments inside a transaction plan under one value form and one
- * reference form: identical to `OperationArgumentsFor` except at the DA-3
- * mutation-data positions, and bound at the same write position per variant as
- * `OperationArgumentMap` — the four flat bulk writes (`create.many`,
- * `create.count`, `update.many`, `update.count`) in `"bulkWrite"`, every other
- * data argument in `"nested"`. The typed builders read it with both forms stated;
- * the exported {@link TransactionOperationArgumentsFor} is it with neither.
+ * The typed builders read it with both forms stated; the exported {@link
+ * TransactionOperationArgumentsFor} is it with neither.
  */
 export type ReferenceableArgumentsFor<C extends Contract, K extends ResourceKey<C>, I extends OperationIdentity, Forms extends ScalarForms, ReferenceForms extends ScalarForms> = I extends {
     family: "create";

package/dist/transactions/transaction-reference.js

@@ -1,10 +1,5 @@
 import { isOperationFingerprint } from "./operation-fingerprint.js";
 const ORDINARY_ROUTE = { kind: "ordinary" };
-/**
- * Total descriptor-only routing for a scalar value at a transaction-reference
- * position. Reflection failures stay candidates so Task 7 can report their
- * full wire path instead of losing them to ordinary scalar validation.
- */
 export function routeTransactionReferenceCandidate(value) {
     if (value === null || typeof value !== "object") {
         return ORDINARY_ROUTE;
@@ -30,15 +25,9 @@ export function routeTransactionReferenceCandidate(value) {
         return { kind: "reflection-failure", candidate: value };
     }
 }
-/** Broad routing guard only; validation of `$ref` members belongs to Task 7. */
 export function isTransactionReferenceCandidate(value) {
     return routeTransactionReferenceCandidate(value).kind === "candidate";
 }
-/**
- * Narrows a structurally complete `$ref` object. DA-15 semantic validation
- * (index ordering, source fingerprint, path existence, and type) stays in
- * the transaction reference validator.
- */
 export function isTransactionReferenceObject(value) {
     const route = routeTransactionReferenceCandidate(value);
     if (route.kind !== "candidate" ||

package/dist/transactions/transaction-request.d.ts

@@ -16,11 +16,10 @@ export type ClientTransactionRequest = TransactionRequestBase & {
 };
 export type FrameworkTransactionRequest = ApplicationTransactionRequest | ClientTransactionRequest;
 /**
- * The origin one plan operation runs under (architect, 2026-10-04: mixed
- * application and client handles in one transaction): its own layer's Contract,
- * its own pipelines, and — for a client step — the protocol identity it is
- * accepted with. The untyped seam derives every operation's origin from the
- * request; the typed runner states one per handle.
+ * The origin one plan operation runs under: its own layer's Contract, its own
+ * pipelines, and — for a client step — the protocol identity it is accepted with.
+ * The untyped seam derives every operation's origin from the request; the typed
+ * runner states one per handle.
  *
  * Internal to the transaction runtime, and deliberately not a member of the
  * request: the public seam's request cannot smuggle a per-operation origin.

package/dist/transactions/transaction-response.d.ts

@@ -1,6 +1,6 @@
 import type { OperationFailureResponse } from "../runtime/operation-response.js";
 /**
- * A committed plan (DA-1): each operation's final `data`, in plan order.
+ * A committed plan: each operation's final `data`, in plan order.
  *
  * `T` mirrors `OperationResponse<T>`: the untyped seam (`executeTransaction`)
  * answers the default `readonly unknown[]`, and the typed runner

package/dist/transactions/transaction-runtime.d.ts

@@ -14,8 +14,7 @@ import type { TransactionResponse } from "./transaction-response.js";
 export type FrameworkTransactionExecutor = (request: FrameworkTransactionRequest, diagnostics: TransactionDiagnosticsChannel, origins?: readonly TransactionOperationOrigin[]) => Promise<TransactionResponse>;
 /**
  * Validates a whole plan through the Framework Validation Layer, then runs it
- * inside exactly one Adapter transaction. Guards, pipes, hooks and
- * interceptors of every plan operation run while the provider transaction is
- * open (DA-6, §14.5).
+ * inside exactly one Adapter transaction. Guards, pipes, hooks and interceptors of
+ * every plan operation run while the provider transaction is open.
  */
 export declare function createTransactionRuntime<M extends AdapterModel>(dependencies: OperationRuntimeDependencies<M>): FrameworkTransactionExecutor;

package/dist/transactions/transaction-runtime.js

@@ -7,26 +7,13 @@ import { TransactionIntegrityError } from "./transaction-integrity-error.js";
 import { validateTransactionPlan } from "./transaction-plan-validator.js";
 import { resolveTransactionReferences } from "./transaction-reference-resolver.js";
 import { transactionCommitted, transactionInfrastructureFailure, transactionOperationFailure, } from "./transaction-response.js";
-/**
- * The framework-owned rollback request (D-707). It is thrown out of the
- * Adapter transaction callback only after an operation failure is recorded,
- * and a rejection is recognized as it solely by identity — never by message,
- * shape or class (C-750). It is a control signal, not a failure, so it never
- * reaches diagnostics.
- */
 const TRANSACTION_ABORT = Object.freeze({ reason: "aventara-transaction-abort" });
-/**
- * Validates a whole plan through the Framework Validation Layer, then runs it
- * inside exactly one Adapter transaction. Guards, pipes, hooks and
- * interceptors of every plan operation run while the provider transaction is
- * open (DA-6, §14.5).
- */
 export function createTransactionRuntime(dependencies) {
-    // The root Adapter is kept apart from what plan operations receive, so no
-    // operation inside a plan can reach it (C-724): only its `transaction`
-    // function is used here.
-    const { adapter, ...pipelineDependencies } = dependencies;
-    // A settled fact of the constructed Adapter, like its model: read once.
+    const { adapter, ...runtimeDependencies } = dependencies;
+    const pipelineDependencies = {
+        ...runtimeDependencies,
+        createRequirements: adapter.createRequirements ?? {},
+    };
     const planDependencies = {
         ...pipelineDependencies,
         cascades: resolveCascadeClosure(adapter.referentialActions),
@@ -39,18 +26,6 @@ export function createTransactionRuntime(dependencies) {
         return executeTransactionPlan(adapter, pipelineDependencies, validation.plan, diagnostics);
     };
 }
-/**
- * Runs an accepted plan strictly sequentially inside one Adapter transaction
- * callback and maps how that transaction settled:
- *
- * - resolved with every operation completed → `A1009` with the ledger;
- * - rejected with the abort sentinel after a recorded failure → that
- *   operation's own outcome with `cause.operation`, including an unexpected
- *   throw from the framework's own per-operation work (`A3000`, DA-23);
- * - any other rejection → `A3002` and a diagnostic;
- * - a transaction that breaks the Adapter contract (DA-24) → `A3002` and a
- *   {@link TransactionIntegrityError} diagnostic, never the sentinel.
- */
 async function executeTransactionPlan(adapter, dependencies, plan, diagnostics) {
     const ledger = { results: [], failure: undefined };
     const infrastructureFailure = (error) => {
@@ -58,23 +33,9 @@ async function executeTransactionPlan(adapter, dependencies, plan, diagnostics)
         diagnostics.transaction(operation)(error, "A3002");
         return transactionInfrastructureFailure(operation);
     };
-    // Unreachable by construction (D-712): a declared "interactive" capability
-    // without a transaction function fails createFramework. Kept because the
-    // Adapter object stays reachable and mutable after construction.
     if (typeof adapter.transaction !== "function") {
         return infrastructureFailure(new TransactionIntegrityError("transaction-unavailable"));
     }
-    /**
-     * Everything the framework does for one plan operation inside the
-     * callback: reference resolution, which reads the source's final data and
-     * writes the substituted slots, then the operation's own pipeline. The
-     * pipeline's result is the operation's outcome; anything the framework's
-     * own work throws is that operation's `A3000` failure, reported with its
-     * identity and index (DA-23). The boundary is structural — it encloses
-     * only this work, never the Adapter transaction call — and the rollback
-     * request is thrown by the caller after it returns, so the sentinel never
-     * crosses it.
-     */
     const runPlanOperation = async (operation, executor) => {
         const report = diagnostics.operation(operation.request, operation.index);
         try {

package/dist/transactions/transaction-slot-path-error.d.ts

@@ -1,10 +1,9 @@
 /**
- * The ways a transaction slot path can fail to name a member of the argument
- * view it is written into. Every slot path was collected from an argument
- * view by the plan validator, so any of these is a framework defect rather
- * than a caller error; the violation is the only thing that tells them apart,
- * so it is structured data rather than message text (ADR 0006: never infer an
- * outcome from error text).
+ * The ways a transaction slot path can fail to name a member of the argument view
+ * it is written into. Every slot path was collected from an argument view by the
+ * plan validator, so any of these is a framework defect rather than a caller
+ * error; the violation is the only thing that tells them apart, so it is
+ * structured data rather than message text.
  *
  * - `slot-prefix`: the path does not begin `["operations", <this operation>,
  *   "args", <member>]`, or the view itself is not an object.
@@ -13,11 +12,11 @@
  */
 export type TransactionSlotPathViolation = "slot-prefix" | "absent-member" | "non-object-ancestor";
 /**
- * The framework-owned failure thrown when a slot path does not name a member
- * of the argument view. It never reaches the wire: inside a plan's
- * transaction callback it becomes that operation's `A3000` (DA-23), during
- * validation the totality guard's `A3000`. It reaches a diagnostics sink as
- * the raw `error`, where the violation discriminates the three defects.
+ * The framework-owned failure thrown when a slot path does not name a member of
+ * the argument view. It never reaches the wire: inside a plan's transaction
+ * callback it becomes that operation's `A3000`, during validation the totality
+ * guard's `A3000`. It reaches a diagnostics sink as the raw `error`, where the
+ * violation discriminates the three defects.
  */
 export declare class TransactionSlotPathError extends Error {
     readonly violation: TransactionSlotPathViolation;

package/dist/transactions/transaction-slot-path-error.js

@@ -3,13 +3,6 @@ const TRANSACTION_SLOT_PATH_MESSAGES = {
     "absent-member": "Transaction slot path names an absent member of the operation arguments.",
     "non-object-ancestor": "Transaction slot path descends through a non-object value.",
 };
-/**
- * The framework-owned failure thrown when a slot path does not name a member
- * of the argument view. It never reaches the wire: inside a plan's
- * transaction callback it becomes that operation's `A3000` (DA-23), during
- * validation the totality guard's `A3000`. It reaches a diagnostics sink as
- * the raw `error`, where the violation discriminates the three defects.
- */
 export class TransactionSlotPathError extends Error {
     violation;
     constructor(violation) {

package/dist/transactions/transaction-slot-writer.d.ts

@@ -1,18 +1,18 @@
 /**
- * The one owner of writing a value at a transaction slot path. Validation
- * installs framework-owned `$ref` control snapshots through it (DA-20) and
- * execution installs resolved final data through it (DA-8), so both argument
- * views are produced by the same ancestor-cloning walker.
+ * The one owner of writing a value at a transaction slot path. Validation installs
+ * framework-owned `$ref` control snapshots through it and execution installs
+ * resolved final data through it, so both argument views are produced by the same
+ * ancestor-cloning walker.
  *
  * Slot paths are collected once, from the validated semantic argument view.
- * Validation then writes them into two views: that semantic view, where the
- * path is known to name a member, and the raw wire view
- * (`operation.request.arguments`), where the same path is asserted rather
- * than established. It holds there because a slot names a scalar leaf key
- * inside top-level mutation data (DA-3) and Framework Validation Layer
- * normalization preserves that `data`-leaf key structure. A path that does
- * not name a member of the view being written is therefore a framework
- * defect either way, and fails loudly rather than being skipped.
+ * Validation then writes them into two views: that semantic view, where the path
+ * is known to name a member, and the raw wire view
+ * (`operation.request.arguments`), where the same path is asserted rather than
+ * established. It holds there because a slot names a scalar leaf key inside
+ * top-level mutation data and Framework Validation Layer normalization preserves
+ * that `data`-leaf key structure. A path that does not name a member of the view
+ * being written is therefore a framework defect either way, and fails loudly
+ * rather than being skipped.
  */
 type Path = readonly (string | number)[];
 /** One value to install at a full transaction slot path. */

package/dist/transactions/transaction-slot-writer.js

@@ -1,34 +1,7 @@
-/**
- * The one owner of writing a value at a transaction slot path. Validation
- * installs framework-owned `$ref` control snapshots through it (DA-20) and
- * execution installs resolved final data through it (DA-8), so both argument
- * views are produced by the same ancestor-cloning walker.
- *
- * Slot paths are collected once, from the validated semantic argument view.
- * Validation then writes them into two views: that semantic view, where the
- * path is known to name a member, and the raw wire view
- * (`operation.request.arguments`), where the same path is asserted rather
- * than established. It holds there because a slot names a scalar leaf key
- * inside top-level mutation data (DA-3) and Framework Validation Layer
- * normalization preserves that `data`-leaf key structure. A path that does
- * not name a member of the view being written is therefore a framework
- * defect either way, and fails loudly rather than being skipped.
- */
 import { TransactionSlotPathError } from "./transaction-slot-path-error.js";
-/**
- * A path that does not name a member of the view being written is a framework
- * defect, for either view (see the module note).
- * Skipping it would leave the original value in place — at execution a `$ref`
- * placeholder handed to guards, pipes and the Adapter — so it fails loudly
- * instead: inside a plan's transaction callback that is the operation's own
- * `A3000` failure (DA-23), during validation the totality guard's `A3000`.
- * The violation discriminates the defect for whoever catches it, so no caller
- * has to read message text.
- */
 function slotPathMismatch(violation) {
     throw new TransactionSlotPathError(violation);
 }
-/** Clones one container, copying sibling descriptors verbatim and replacing one property. */
 function cloneContainerWithReplacement(container, property, replacement) {
     const array = Array.isArray(container);
     const prototype = Object.getPrototypeOf(container);
@@ -63,7 +36,6 @@ function cloneContainerWithReplacement(container, property, replacement) {
     }
     return clone;
 }
-/** Replaces the value below one container member, cloning only that container. */
 function replaceValueInContainer(container, property, tail, replacement) {
     const descriptor = Object.getOwnPropertyDescriptor(container, property);
     if (descriptor === undefined) {
@@ -82,12 +54,6 @@ function replaceValueAtPath(value, path, replacement) {
     }
     return replaceValueInContainer(value, String(head), tail, replacement);
 }
-/**
- * Installs values at transaction slot paths into one argument view: validated
- * control snapshots at validation, resolved final data at execution. A slot
- * path always names a member below `args`, so the view keeps its own
- * container kind and prototype; only the ancestors of each slot are cloned.
- */
 export function replaceTransactionSlotValues(value, operation, slots) {
     let materialized = value;
     for (const slot of slots) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/core",
-  "version": "0.1.0-pilot.1",
+  "version": "0.1.0-pilot.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Core runtime, contract compiler, and extension APIs for Aventara.",
   "type": "module",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --removeComments --declaration false && tsc -p tsconfig.json --emitDeclarationOnly && node ../../scripts/build/declaration-comments.sanitizer.ts dist",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run --typecheck --config ../../vitest.config.mts --root .",
     "lint": "biome lint src"