@zerotal/ai 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -8,6 +8,50 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Fixed
+
+- **An empty string is an answer.** `required` treats `""` as absent, which is right
+  for an HTML form — an empty text input submits `""` — and wrong for structured
+  model output, where `""` is the conventional way to say _"this field does not
+  apply"_ and is what a prompt naturally asks for. So `rule.string()` rejected the
+  answer a prompt had requested, and the whole feature returned nothing: an app's
+  questions mostly named no month, the model replied `""` in 3.3 seconds every time,
+  and the page said "either no model is configured, or it was not about your money"
+  while a model was configured and had answered.
+
+  `""` now counts as present on a **string** field in the AI path only. Absence is
+  still a failure, every other constraint still applies (a `min(3)` still rejects
+  `""`), and a non-string field is untouched — `""` for a number is a malformed
+  answer, not a convention.
+
+- **`AiFake` validates what it is scripted with.** `respondWithObject()` handed the
+  canned value back unexamined, so a fake answer the real driver would reject passed
+  every test. An app scripted `{ month: "" }`, eleven tests passed on it, and the live
+  path rejected the identical value every time — the feature shipped green and
+  answered nothing. The permissive fake is what made the bug above invisible; they are
+  the same defect from both ends.
+
+  `AiFake.object()` now takes the schema `AiManager.object()` takes, and checks the
+  scripted object through the same `recheckAgainstSchema` a driver uses. Omit the
+  schema and nothing is checked, because there is nothing to check against.
+
+### Added
+
+- **`AiError.transient`** — `true` for _this call failed_, `false` for _this machine
+  cannot do this_. A service calling a model per row has to latch itself off after a
+  permanent failure, or a machine with no API key pays the driver's timeout per row,
+  per merchant, per page load — 8s × 12 merchants is ninety seconds of blank page.
+
+  Writing that latch meant classifying eleven error classes by hand, and the mistake
+  is unrecoverable in one direction: call something permanent that is not, and the
+  feature disables itself for the life of the process, silently, because every call
+  site already treats "no answer" as normal. An app classified `AiSchemaError` as
+  permanent and would have turned two features off on their first badly-shaped reply.
+  **It is transient** — sampling is not deterministic. Only this package knows what a
+  new error class means, so the judgement now lives here.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/api-surface.md

@@ -10,6 +10,7 @@ class AiAgentLimitError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiCancelledError = {
@@ -17,6 +18,7 @@ class AiCancelledError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiConfigError = {
@@ -24,6 +26,7 @@ class AiConfigError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiDriverUnavailableError = {
@@ -31,13 +34,15 @@ class AiDriverUnavailableError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiError = {
-  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): AiError
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>, transient?: boolean): AiError
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiFake = {
@@ -55,7 +60,7 @@ class AiFake = {
   embed: (input: string | string[], _options?: Omit<AiEmbedRequest, 'input'>) => Promise<AiEmbedResponse>
   generate: (request: AiRequest | string) => Promise<AiResponse>
   handlerFor: (name: string) => AiQueueHandler | undefined
-  object: <T = Record<string, unknown>>(request: AiRequest | string) => Promise<T>
+  object: <T = Record<string, unknown>>(request: AiRequest | string, schema?: SchemaInput | ((rule: RuleBuilder) => SchemaInput)) => Promise<T>
   onGenerated: (name: string, handler: AiQueueHandler) => AiFake
   prompts: string[]
   queue: (request: AiRequest, options: AiQueueOptions) => Promise<void>
@@ -131,6 +136,7 @@ class AiRateLimitError = {
   readonly context?: Record<string, unknown> | undefined
   readonly retryAfterSeconds?: number | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiRefused = {
@@ -149,6 +155,7 @@ class AiRefusedError = {
   readonly explanation: string | null
   readonly partialText: string
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiRequestError = {
@@ -157,6 +164,7 @@ class AiRequestError = {
   readonly context?: Record<string, unknown> | undefined
   readonly providerStatus: number
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiSchemaError = {
@@ -164,6 +172,7 @@ class AiSchemaError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiSpendLimitError = {
@@ -171,6 +180,7 @@ class AiSpendLimitError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 class AiToolCalled = {
@@ -235,6 +245,7 @@ class UnknownAiDriverError = {
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
+  readonly transient: boolean
 }
 
 const Ai = AiManager

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/ai",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "license": "MIT",
   "maturity": "experimental",
   "maturityReview": "1.11.0",
@@ -31,9 +31,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.10.0",
-    "@zerotal/validator": "1.10.0",
-    "@zerotal/queue": "1.10.0"
+    "@zerotal/core": "1.11.1",
+    "@zerotal/validator": "1.11.1",
+    "@zerotal/queue": "1.11.1"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.70.0"

package/src/AiFake.ts

@@ -1,5 +1,7 @@
 import { Application, currentApp } from "@zerotal/core";
-import { AiRefusedError } from "./errors.ts";
+import { AiRefusedError, AiSchemaError } from "./errors.ts";
+import { recheckAgainstSchema, _resolveSchema, type SchemaInput } from "./schema.ts";
+import type { RuleBuilder } from "@zerotal/validator";
 import { normalizeMessages, promptText, type DriverStatus } from "./drivers/AiDriver.ts";
 import type { AiAgentRequest, AiQueueHandler, AiQueueOptions } from "./AiManager.ts";
 import type {
@@ -158,7 +160,28 @@ export class AiFake {
     };
   }
 
-  async object<T = Record<string, unknown>>(request: AiRequest | string): Promise<T> {
+  /**
+   * Return the next scripted object — after checking it against the same schema the
+   * real driver would.
+   *
+   * This used to hand the canned value back unexamined, and that is a fake that
+   * makes tests *less* informative than no test. An app scripted `{ month: "" }`,
+   * eleven tests passed on it, and the live path rejected the identical answer every
+   * time — so the suite was green about a feature that returned nothing in
+   * production. The permissive fake is what made the schema bug invisible; they are
+   * the same defect seen from both ends.
+   *
+   * The check runs only when the caller passed a schema, because that is the only
+   * case where there is anything to check. A mismatch throws here, in the test, with
+   * the field named — which is the whole point.
+   *
+   * @param request - The request, or just a prompt.
+   * @param schema - The schema the production call declares.
+   */
+  async object<T = Record<string, unknown>>(
+    request: AiRequest | string,
+    schema?: SchemaInput | ((rule: RuleBuilder) => SchemaInput),
+  ): Promise<T> {
     const normalized = capture(request);
     this._record("object", normalized);
     this._maybeRefuse();
@@ -169,7 +192,26 @@ export class AiFake {
           "ai.respondWithObject({ … }) before the code under test runs.",
       );
     }
-    return (this._objects.length > 1 ? this._objects.shift() : this._objects[0]) as T;
+
+    const scripted = (
+      this._objects.length > 1 ? this._objects.shift() : this._objects[0]
+    ) as unknown;
+
+    if (schema === undefined) return scripted as T;
+
+    const resolved = await _resolveSchema(schema);
+    try {
+      return recheckAgainstSchema<T>(resolved, scripted);
+    } catch (error) {
+      throw new AiSchemaError(
+        `[Zerotal/ai] The object scripted with respondWithObject() does not satisfy the ` +
+          `schema this call declares, so the real driver would reject it too — and a test ` +
+          `passing on it would be green about a call that fails in production.
+  ` +
+          `${(error as Error).message}`,
+        { scripted },
+      );
+    }
   }
 
   async agent(request: AiAgentRequest): Promise<AiAgentResult> {

package/src/AiManager.ts

@@ -12,7 +12,7 @@ import { AiCancelledError, AiConfigError, AiRefusedError, UnknownAiDriverError }
 import { AiGenerated, AiRefused } from "./events.ts";
 import { estimateCost } from "./pricing.ts";
 import { redactPrompt } from "./redact.ts";
-import type { SchemaInput } from "./schema.ts";
+import { _resolveSchema, type SchemaInput } from "./schema.ts";
 import { assertWithinLimits, recordSpend } from "./spend.ts";
 import type {
   AiAgentResult,
@@ -266,7 +266,7 @@ export class AiManager {
   ): Promise<T> {
     const normalized = normalize(request);
     const driver = this.driver(normalized.driver);
-    const resolved = await resolveSchema(schema);
+    const resolved = await _resolveSchema(schema);
     const startedAt = performance.now();
 
     try {
@@ -553,14 +553,6 @@ function normalize(request: AiRequest | string): AiRequest {
 }
 
 /** Accept either a schema map or a `(rule) => schema` factory. */
-async function resolveSchema(
-  schema: SchemaInput | ((rule: import("@zerotal/validator").RuleBuilder) => SchemaInput),
-): Promise<SchemaInput> {
-  if (typeof schema !== "function") return schema;
-  const { RuleBuilder } = await import("@zerotal/validator");
-  return schema(new RuleBuilder());
-}
-
 /** The `lock` binding, or `undefined` when the app has no LockProvider. */
 async function lockManager(): Promise<import("@zerotal/core/lock").LockManager | undefined> {
   try {

package/src/errors.ts

@@ -1,9 +1,52 @@
 import { ZerotalError } from "@zerotal/core";
 
-/** Base class for all `@zerotal/ai` errors. */
+/**
+ * Base class for all `@zerotal/ai` errors.
+ *
+ * Every one of them carries {@link transient}, because the caller cannot work it out
+ * and the package can.
+ */
 export class AiError extends ZerotalError {
-  constructor(message: string, code = "E_AI", status = 500, context?: Record<string, unknown>) {
+  /**
+   * Whether retrying could plausibly succeed — `true` for *this call failed*, `false`
+   * for *this machine cannot do this*.
+   *
+   * The distinction exists because a service that calls a model per row has to latch
+   * itself off after a permanent failure. Without that, a laptop with no API key pays
+   * the driver's timeout per row, per merchant, per page load — measured at 8s × 12
+   * merchants, which is ninety seconds of blank page.
+   *
+   * Writing that latch meant classifying eleven error classes by hand, and the
+   * permissive mistake is unrecoverable: get it wrong toward "permanent" and a
+   * feature disables itself for the lifetime of the process, silently, because every
+   * call site already treats "no answer" as normal. An app classified
+   * {@link AiSchemaError} as permanent and would have turned two features off on
+   * their first badly-shaped answer.
+   *
+   * So the judgement lives here, where the knowledge is. Only this package knows
+   * whether a new error class means "this call" or "this machine".
+   *
+   * @example
+   * ```ts
+   * try {
+   *   return await Ai.object(prompt, schema);
+   * } catch (error) {
+   *   if (error instanceof AiError && !error.transient) this.disabled = true;
+   *   return null;
+   * }
+   * ```
+   */
+  readonly transient: boolean;
+
+  constructor(
+    message: string,
+    code = "E_AI",
+    status = 500,
+    context?: Record<string, unknown>,
+    transient = false,
+  ) {
     super(message, code, status, context);
+    this.transient = transient;
   }
 }
 
@@ -18,6 +61,8 @@ export class UnknownAiDriverError extends AiError {
       "E_AI_UNKNOWN_DRIVER",
       500,
       { driver, known },
+      // A name that does not exist will not start existing. Permanent.
+      false,
     );
   }
 }
@@ -25,7 +70,8 @@ export class UnknownAiDriverError extends AiError {
 /** Thrown at boot, or on first use, for a config combination that cannot work. */
 export class AiConfigError extends AiError {
   constructor(message: string, context?: Record<string, unknown>) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_CONFIG", 500, context);
+    // Configuration does not fix itself between two calls. Permanent.
+    super(`[Zerotal/ai] ${message}`, "E_AI_CONFIG", 500, context, false);
   }
 }
 
@@ -43,6 +89,9 @@ export class AiDriverUnavailableError extends AiError {
       "E_AI_DRIVER_UNAVAILABLE",
       500,
       { driver, packageName },
+      // A missing package is missing for the life of the process. Permanent, and the
+      // one this distinction exists for — it is what a laptop with no key hits.
+      false,
     );
   }
 }
@@ -72,6 +121,10 @@ export class AiRefusedError extends AiError {
       // policy decision about the content, which is what 422 says.
       422,
       { category, explanation },
+      // Transient: a refusal is about *this content*, not about the machine. The
+      // next prompt may be fine, and latching a feature off because one request was
+      // declined would disable it for everybody over one user's question.
+      true,
     );
   }
 }
@@ -82,7 +135,8 @@ export class AiRateLimitError extends AiError {
     message: string,
     readonly retryAfterSeconds?: number,
   ) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_RATE_LIMIT", 429, { retryAfterSeconds });
+    // The provider is telling you when to come back. Transient by definition.
+    super(`[Zerotal/ai] ${message}`, "E_AI_RATE_LIMIT", 429, { retryAfterSeconds }, true);
   }
 }
 
@@ -93,37 +147,52 @@ export class AiRequestError extends AiError {
     readonly providerStatus: number,
     context?: Record<string, unknown>,
   ) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_REQUEST", providerStatus >= 500 ? 502 : 400, {
-      providerStatus,
-      ...context,
-    });
+    super(
+      `[Zerotal/ai] ${message}`,
+      "E_AI_REQUEST",
+      providerStatus >= 500 ? 502 : 400,
+      { providerStatus, ...context },
+      // The only classification here that reads a value, and the split is the
+      // provider's own: 5xx is the provider having a bad moment and 408/429 say so
+      // outright, while a 4xx is this request being wrong in a way that repeating it
+      // will not fix — a bad key, a model name that does not exist, a payload the
+      // API rejects.
+      providerStatus >= 500 || providerStatus === 408 || providerStatus === 429,
+    );
   }
 }
 
 /** Thrown when a request would breach a configured spend ceiling. */
 export class AiSpendLimitError extends AiError {
   constructor(message: string, context?: Record<string, unknown>) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_SPEND_LIMIT", 429, context);
+    // A budget resets on its window. Transient, though a caller may reasonably
+    // back off much harder than it would for a rate limit.
+    super(`[Zerotal/ai] ${message}`, "E_AI_SPEND_LIMIT", 429, context, true);
   }
 }
 
 /** Thrown when a validator schema uses a constraint structured output cannot express. */
 export class AiSchemaError extends AiError {
   constructor(message: string, context?: Record<string, unknown>) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_SCHEMA", 500, context);
+    // Transient, and deliberately so. A model that shaped one answer badly may
+    // shape the next one correctly — sampling is not deterministic. An app called
+    // this permanent and would have disabled two features on a single bad reply.
+    super(`[Zerotal/ai] ${message}`, "E_AI_SCHEMA", 500, context, true);
   }
 }
 
 /** Thrown when the agent loop hits its step or resume ceiling. */
 export class AiAgentLimitError extends AiError {
   constructor(message: string, context?: Record<string, unknown>) {
-    super(`[Zerotal/ai] ${message}`, "E_AI_AGENT_LIMIT", 500, context);
+    // The loop hit its own ceiling on this run. Another run may not. Transient.
+    super(`[Zerotal/ai] ${message}`, "E_AI_AGENT_LIMIT", 500, context, true);
   }
 }
 
 /** Thrown when the caller's `AbortSignal` fired before the call finished. */
 export class AiCancelledError extends AiError {
   constructor(message = "The generation was cancelled.") {
-    super(`[Zerotal/ai] ${message}`, "E_AI_CANCELLED", 499);
+    // Somebody asked for this to stop. Nothing is wrong with the machine.
+    super(`[Zerotal/ai] ${message}`, "E_AI_CANCELLED", 499, undefined, true);
   }
 }

package/src/schema.ts

@@ -258,7 +258,7 @@ export function recheckAgainstSchema<T>(input: SchemaInput, value: unknown): T {
   }
 
   const cleaned = dropAbsentNulls(schema, value as Record<string, unknown>);
-  const result = runValidation(schema, cleaned);
+  const result = runValidation(emptyStringIsPresent(schema, cleaned), cleaned);
 
   if (!result.success) {
     const detail = Object.entries(result.errors)
@@ -290,3 +290,70 @@ function dropAbsentNulls(schema: Schema, value: Record<string, unknown>): Record
 
   return out;
 }
+
+/**
+ * Let `""` count as an answer on a required string field.
+ *
+ * `required` treats the empty string as absent, and for an HTML form that is exactly
+ * right: an empty text input submits `""`, and a user who typed nothing has supplied
+ * nothing. Structured model output is not a form. There, `""` is the conventional way
+ * to say *"this field does not apply"* — it is what a prompt naturally asks for, and
+ * a model that returns it has answered rather than declined:
+ *
+ * > A month must be YYYY-MM. Use an empty string when the question names no month.
+ *
+ * With the form rule applied, that correct answer was rejected as malformed and the
+ * whole feature returned nothing. An app shipped exactly that: most questions named
+ * no month, the model returned `""` in 3.3 seconds every time, and the page said
+ * "either no model is configured, or it was not about your money" — while a model
+ * was configured and had answered.
+ *
+ * Only `required` is relaxed, and only for a field the schema declares as a string
+ * whose value is exactly `""`. Every other constraint still applies: a
+ * `rule.string().min(3)` still rejects `""`, because that length is the app's own
+ * requirement rather than a form convention leaking in.
+ *
+ * @param schema - The declared schema.
+ * @param value - The model's parsed answer.
+ * @returns A schema to validate with — the same one when nothing needed relaxing.
+ */
+function emptyStringIsPresent(schema: Schema, value: Record<string, unknown>): Schema {
+  let relaxed: Schema | undefined;
+
+  for (const [name, def] of Object.entries(schema)) {
+    // Only a field that is *present* and holds `""`. An absent field leaves
+    // `value[name]` as `undefined`, so `required` still fires on it — which is the
+    // difference between "the model said this does not apply" and "the model did
+    // not answer", and only the first is an answer.
+    if (value[name] !== "") continue;
+
+    const shape = def as { type?: string; required?: boolean };
+    if (shape.type !== "string" || shape.required !== true) continue;
+
+    relaxed ??= { ...schema };
+    // A shallow clone: the caller's schema object is theirs, and mutating it would
+    // change every later validation that reuses the same instance.
+    relaxed[name] = { ...(def as object), required: false } as Schema[string];
+  }
+
+  return relaxed ?? schema;
+}
+
+/**
+ * Resolve a schema that may be declared as a builder callback.
+ *
+ * `Ai.object(request, (rule) => ({ … }))` is the ergonomic form — it saves the caller
+ * an import — and every consumer of a schema has to accept it. Shared so the fake
+ * resolves it exactly as the manager does, rather than declining to check a schema it
+ * did not recognise.
+ *
+ * @param schema - A schema, or a callback given a {@link RuleBuilder}.
+ * @internal
+ */
+export async function _resolveSchema(
+  schema: SchemaInput | ((rule: import("@zerotal/validator").RuleBuilder) => SchemaInput),
+): Promise<SchemaInput> {
+  if (typeof schema !== "function") return schema;
+  const { RuleBuilder } = await import("@zerotal/validator");
+  return schema(new RuleBuilder());
+}