bazis 0.104.1 → 0.105.1

package/core/di/errors/NamedDependencyNotFoundError.ts

@@ -10,9 +10,18 @@ export function registerNamedDependencyHint(hint: NamedDependencyHint): void {
   hints.push(hint);
 }
 
+function hintFor(name: string): string {
+  const hint = hints.map((item) => item(name)).find((text) => text !== undefined);
+  return hint ? ` ${hint}` : "";
+}
+
+/** The graph-validation issue for a named dependency nobody registers, naming the service that needs it. */
+export function missingNamedDependencyIssue(name: string, requester: string): string {
+  return `Missing dependency "${name}" for "${requester}".${hintFor(name)}`;
+}
+
 export class NamedDependencyNotFoundError extends DiError {
   public constructor(name: string) {
-    const hint = hints.map((item) => item(name)).find((text) => text !== undefined);
-    super(`No provider token found for named dependency "${name}".${hint ? ` ${hint}` : ""}`);
+    super(`No provider token found for named dependency "${name}".${hintFor(name)}`);
   }
 }

package/core/di/internal/GraphValidator.ts

@@ -1,4 +1,5 @@
 import { ServiceValidationError } from "../errors";
+import { missingNamedDependencyIssue } from "../errors/NamedDependencyNotFoundError";
 import { isLazyDependency, isNamedDependency, isOptionalDependency } from "../provider";
 import type {
   KeyedDependency,
@@ -97,7 +98,8 @@ export class GraphValidator {
         const isOptional = isOptionalDependency(dependency);
         const inner = isLazy || isOptional ? dependency.inner : dependency;
         // An optional dependency on a name nothing registered is simply absent.
-        if (isOptional && isNamedDependency(inner) && !this.context.hasName(inner.name)) {
+        if (isNamedDependency(inner) && !this.context.hasName(inner.name)) {
+          if (!isOptional) issues.add(missingNamedDependencyIssue(inner.name, tokenToDebugName(registration.token)));
           continue;
         }
         const descriptor = this.context.describeDependency(inner);

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.104.1" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.105.1" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/kernel/config/defineConfig.ts

@@ -7,6 +7,16 @@ import { ENV_PREFIX } from "./sources";
 import { isSensitiveKey, redactSensitiveText } from "../../../library/redaction";
 import { ConfigValidationError, type ConfigIssue, type ConfigIssueKind } from "./ConfigValidationError";
 import { callerFile } from "./callerFile";
+import { registerNamedDependencyHint } from "../../di/errors/NamedDependencyNotFoundError";
+
+// `ConfigView<T>` is injected by the name of its config; a config that no
+// module declares has no provider, and the start says where to declare it.
+registerNamedDependencyHint((name) => {
+  const match = /^Config:(.+)$/.exec(name);
+  if (!match) return undefined;
+  const declaration = match[1] === "default" ? "defineConfig({ … })" : `defineConfig("${match[1]}", …)`;
+  return `The config ${declaration} is not declared in the application: add it to \`config\` of the module that uses it, or to runApp({ config }).`;
+});
 
 type Stand = "development" | "test" | "production";
 type Primitive = string | number | boolean;

package/library/orm/DbContext.ts

@@ -102,6 +102,6 @@ export abstract class DbContext {
 
   /** Executes a composable ORM transaction scope for this provider identity. */
   transactionScope<TResult>(work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions): Promise<TResult> {
-    return transactionScope(this, this.#options.provider, work, options);
+    return transactionScope(this, this.#options.provider, work, options, this.#options.executionStrategy);
   }
 }

package/library/orm/Saving/ExecutionStrategy.ts

@@ -56,7 +56,8 @@ export class ExecutionStrategy {
     return false;
   }
 
-  async execute<T>(operation: () => Promise<T>): Promise<T> {
+  /** Runs `operation`, again after a transient failure; `beforeRetry` runs before each new attempt. */
+  async execute<T>(operation: () => Promise<T>, beforeRetry?: (error: unknown) => void): Promise<T> {
     let attempt = 0;
     for (;;) {
       try {
@@ -67,6 +68,7 @@ export class ExecutionStrategy {
         }
         const delay = this.baseDelayMs * 2 ** attempt;
         await new Promise((resolve) => setTimeout(resolve, delay));
+        beforeRetry?.(error);
         attempt += 1;
       }
     }

package/library/orm/Tracking/ChangeTracker.ts

@@ -347,6 +347,11 @@ export function trackedEntriesOf(tracker: ChangeTracker): ReadonlyMap<object, Tr
   return trackerEntries.get(tracker) ?? new Map();
 }
 
+/** Non-barrel helper: how many entities the tracker holds. */
+export function trackedEntryCount(tracker: ChangeTracker): number {
+  return trackerEntries.get(tracker)?.size ?? 0;
+}
+
 /** Non-barrel helper used only by immediate DML admission. */
 export function hasTrackedEntriesForModel(tracker: ChangeTracker, model: EntityModel): boolean {
   return [...(trackerEntries.get(tracker)?.values() ?? [])].some((entry) => entry.model === model);

package/library/orm/Transactions/OrmTransaction.ts

@@ -1,4 +1,5 @@
 import type { DbContext } from "../DbContext";
+import type { ExecutionStrategyOptions } from "../Saving/ExecutionStrategy";
 
 /** A database wall-clock value obtained from the active database session. */
 export interface OrmDatabaseTimeV1 {
@@ -15,6 +16,16 @@ export interface OrmTransactionScopeOptions {
   readonly signal?: AbortSignal;
   /** Total work budget in milliseconds, including admission and COMMIT; positive integer. */
   readonly timeoutMs?: number;
+  /**
+   * Runs the whole scope again after a transient failure (deadlock,
+   * serialization failure, lost connection): `true` takes the context's
+   * `executionStrategy` (or 3 retries from 50 ms), an object sets its own.
+   * Every attempt starts from a clean context: what the failed attempt
+   * loaded or changed is detached, so the callback must read what it
+   * changes. Allowed only for the outermost scope of a context that tracks
+   * nothing yet; a COMMIT without acknowledgement is never retried.
+   */
+  readonly retry?: boolean | ExecutionStrategyOptions;
 }
 
 /** Opaque transaction capability. It deliberately exposes no executor or completion authority. */

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -7,6 +7,8 @@ import { OrmTransaction, type OrmDatabaseTimeV1, type OrmTransactionScopeOptions
 
 import { isUnknownTransactionOutcome, TransactionOutcomeUnknownError } from "../Providers/transactionOutcome";
 import { OperationDeadline, positiveTimeout } from "../Providers/operationDeadline";
+import { ExecutionStrategy, type ExecutionStrategyOptions } from "../Saving/ExecutionStrategy";
+import { trackedEntryCount } from "../Tracking/ChangeTracker";
 
 interface Frame {
   readonly allEnrolled: Set<object>;
@@ -20,6 +22,8 @@ interface Frame {
   activeChildFrame?: Frame;
   rollbackOnly?: unknown;
   cancellationRequested?: boolean;
+  /** Outermost frame of a retried scope: every context of the attempt, cleared before the next one. */
+  readonly retryContexts?: Set<DbContext>;
   readonly pending: Set<PendingTask>;
   readonly abortPromise: Promise<never>;
   abort(error: OrmTransactionScopeError): void;
@@ -173,7 +177,31 @@ function releaseTask(task: PendingTask): void {
   if (task.settled && task.dispatches.size === 0 && task.attached.size === 0) task.frame.pending.delete(task);
 }
 
-export async function transactionScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions): Promise<TResult> {
+export async function transactionScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options?: OrmTransactionScopeOptions, contextStrategy?: ExecutionStrategyOptions): Promise<TResult> {
+  const retry = options?.retry;
+  if (retry === undefined || retry === false) return runScope(context, provider, work, options);
+  if (views.getStore() !== undefined || provider.isTransactionActive?.() === true) {
+    throw new OrmTransactionScopeError("transactionScope({ retry }) must be the outermost scope: a nested scope is part of the outer transaction, so retry the outer one.");
+  }
+  assertRetryable(context);
+  const contexts = new Set<DbContext>([context]);
+  const strategy = new ExecutionStrategy(retry === true ? contextStrategy ?? {} : retry);
+  return strategy.execute(() => runScope(context, provider, work, options, contexts), () => {
+    // The rolled-back attempt left its loaded and changed entities behind;
+    // the next attempt reads them again instead of applying its changes twice.
+    for (const each of contexts) each.changeTracker.clear();
+    contexts.clear();
+    contexts.add(context);
+  });
+}
+
+function assertRetryable(context: DbContext): void {
+  const tracked = trackedEntryCount(context.changeTracker);
+  if (tracked === 0) return;
+  throw new OrmTransactionScopeError(`transactionScope({ retry }) needs ${contextName(context)} without tracked entities: every attempt starts from a clean context, and the ${tracked} entities tracked before the scope would lose their changes. Start the scope before loading anything, or create a new scope for it.`);
+}
+
+async function runScope<TResult>(context: DbContext, provider: DatabaseProvider, work: (transaction: OrmTransaction) => Promise<TResult>, options: OrmTransactionScopeOptions | undefined, retryContexts?: Set<DbContext>): Promise<TResult> {
   let signal = options?.signal;
   if (options?.timeoutMs !== undefined) positiveTimeout(options.timeoutMs, 30_000, "timeoutMs");
   if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError("ORM transaction signal must be an AbortSignal.");
@@ -230,7 +258,7 @@ export async function transactionScope<TResult>(context: DbContext, provider: Da
       void abortPromise.catch(() => {});
       let cancelDrain!: () => void;
       const cancellationPromise = new Promise<"cancelled">((resolve) => { cancelDrain = () => resolve("cancelled"); });
-      const frame: Frame = { allEnrolled: new Set([token]), id: Symbol("orm transaction"), authority, provider: base, parent, enrolled: parent ? current!.enrolled : new Set([token]), state: "active", pending: new Set(), abortPromise, abort, cancellationPromise, cancelDrain }; childFrame = frame;
+      const frame: Frame = { allEnrolled: new Set([token]), id: Symbol("orm transaction"), authority, provider: base, parent, enrolled: parent ? current!.enrolled : new Set([token]), state: "active", pending: new Set(), abortPromise, abort, cancellationPromise, cancelDrain, retryContexts: parent ? undefined : retryContexts }; childFrame = frame;
       if (parent) parent.activeChildFrame = frame;
       const view: View = { frame, enrolled: frame.enrolled };
       return withProviderDispatchObserver((dispatch) => registerDispatch(frame, dispatch), () => views.run(view, async () => {
@@ -374,6 +402,12 @@ class ScopedOrmTransaction extends OrmTransaction {
     const parent = views.getStore();
     if (!parent || parent.frame !== frame) throw foreignTransaction();
     if (uncertainContexts.has(token)) throw new TransactionOutcomeUnknownError();
+    let root = frame;
+    while (root.parent) root = root.parent;
+    if (root.retryContexts && !root.retryContexts.has(context)) {
+      assertRetryable(context);
+      root.retryContexts.add(context);
+    }
     for (let target: Frame | undefined = frame; target; target = target.parent) target.allEnrolled.add(token);
     const enrolled = new Set(parent.enrolled); enrolled.add(token);
     return views.run({ frame, enrolled }, () => trackTask(frame, () => work(context)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.104.1",
+  "version": "0.105.1",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",