akanjs 3.1.1-rc.2 → 3.1.1-rc.4

package/client/router.ts

@@ -180,7 +180,7 @@ export const getPathInfo = (requestUrl: string, lang: string, prefix: string) =>
   return { path, pathname, hash, search, href };
 };
 class Router {
-  isInitialized = false;
+  isInitialized: boolean = false;
   #prefix = "";
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
@@ -193,6 +193,8 @@ class Router {
   #backsAwaitingPopstate = 0;
   #redirects = 0;
   #navigations = 0;
+  
+  #beforeInit: (() => void)[] = [];
   #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -227,6 +229,7 @@ class Router {
     else if (options.side === "client") this.#initSsrClientRouter(options);
     this.isInitialized = true;
     Logger.verbose("Router initialized");
+    for (const call of this.#beforeInit.splice(0)) call();
   }
   #initSsrClientRouter(options: SsrClientRouterOption) {
     this.#historyWrittenByNavigation = true;
@@ -282,6 +285,27 @@ class Router {
   #checkInitialized() {
     if (!this.isInitialized) throw new Error("Router is not initialized");
   }
+  #deferredUntilInit(call: () => void) {
+    if (this.isInitialized || getEnv().side === "server") return false;
+    this.#track(
+      new Promise<void>((resolve, reject) => {
+        this.#beforeInit.push(() => {
+          const pending = this.#navigation;
+          try {
+            call();
+          } catch (error) {
+            Logger.error(`A navigation made before the router was initialized failed: ${String(error)}`);
+            reject(error);
+            return;
+          }
+          
+          if (this.#navigation === pending) resolve();
+          else this.#navigation.then(resolve, reject);
+        });
+      }),
+    );
+    return true;
+  }
 
   #ensureHistoryState() {
     if (getEnv().side === "server") return;
@@ -389,7 +413,9 @@ class Router {
     const target = `${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
     return dedupedStack.map((candidate, index) => (index === dedupedStack.length - 1 ? target : candidate));
   }
+  /** Before init the link waits for it, and the answer is `true`: the manifest that could refuse it is not loaded yet. */
   enterDeepLink(href: string, options: DeepLinkOptions = {}) {
+    if (this.#deferredUntilInit(() => this.enterDeepLink(href, options))) return true;
     this.#checkInitialized();
     if (!options.resetStack) {
       this.push(normalizeDeepLinkHref(href), options);
@@ -405,6 +431,7 @@ class Router {
     return true;
   }
   push(href: string, routeOptions?: RouteOptions) {
+    if (this.#deferredUntilInit(() => this.push(href, routeOptions))) return undefined as never;
     this.#checkInitialized();
     if (this.#refusesOffsite("push", href, routeOptions)) return undefined as never;
     this.#navigations += 1;
@@ -414,6 +441,7 @@ class Router {
     return undefined as never;
   }
   replace(href: string, routeOptions?: RouteOptions) {
+    if (this.#deferredUntilInit(() => this.replace(href, routeOptions))) return undefined as never;
     this.#checkInitialized();
     if (this.#refusesOffsite("replace", href, routeOptions)) return undefined as never;
     this.#navigations += 1;

package/document/database.ts

@@ -3,7 +3,7 @@ import type { Logger } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions, CacheValue } from "akanjs/service";
 import type { DataLoader } from "./dataLoader";
-import type { DocumentUpdateInput } from "./documentQuery";
+import type { DocumentTouchOptions, DocumentUpdateInput } from "./documentQuery";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta";
 import type { Mdl, SaveEventListener, SaveEventType, UpdateResult } from "./into";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types";
@@ -61,7 +61,7 @@ export class CacheDatabase<_T = unknown> {
 }
 /** What `update<Filter>` returns: the patch cannot trail a filter's optional args, so it lands on `.set()`. */
 export interface UpdateChain<Doc = any> {
-  set(update: DocumentUpdateInput<Doc>): Promise<UpdateResult>;
+  set(update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions): Promise<UpdateResult>;
 }
 
 type QueryMethodOfKey<
@@ -157,8 +157,16 @@ export type DatabaseInstanceWithQuerySort<
   __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __purgeMany: (query: _QueryOfDoc) => Promise<number>;
-  __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
-  __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+  __updateMany: (
+    query: _QueryOfDoc,
+    update: DocumentUpdateInput<Doc>,
+    options?: DocumentTouchOptions,
+  ) => Promise<UpdateResult>;
+  __updateOne: (
+    query: _QueryOfDoc,
+    update: DocumentUpdateInput<Doc>,
+    options?: DocumentTouchOptions,
+  ) => Promise<UpdateResult>;
   __list(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/document/documentQuery.ts

@@ -106,7 +106,12 @@ export interface DocumentScopeOptions {
   withRemoved?: boolean;
 }
 
-export interface DocumentUpdateOptions extends DocumentScopeOptions {
+export interface DocumentTouchOptions {
+  /** `false` leaves `updatedAt` as stored, for bookkeeping that is no edit: a lease heartbeat, a mirrored snapshot. */
+  touch?: boolean;
+}
+
+export interface DocumentUpdateOptions extends DocumentScopeOptions, DocumentTouchOptions {
   upsert?: boolean;
 }
 

package/document/into.ts

@@ -4,7 +4,13 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterCls, FilterQueryOf, FilterSortOf, SchemaOf } from ".";
 import type { CacheDatabase, QueryMethodPart } from "./database";
 import type { DataLoader } from "./dataLoader";
-import type { DocumentQuery, DocumentScopeOptions, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery";
+import type {
+  DocumentQuery,
+  DocumentScopeOptions,
+  DocumentTouchOptions,
+  DocumentUpdateInput,
+  DocumentUpdateOptions,
+} from "./documentQuery";
 import { type LoaderBuilder, type ModelCls, makeLoaderBuilder } from "./loaderInfo";
 import type { DocumentProjection } from "./types";
 
@@ -79,7 +85,7 @@ export type Mdl<
   updateMany(
     query: _RawQuery,
     update: DocumentUpdateInput<_RawDoc>,
-    options?: DocumentScopeOptions,
+    options?: DocumentScopeOptions & DocumentTouchOptions,
   ): Promise<UpdateResult>;
   removeOne(query: _RawQuery): Promise<UpdateResult>;
   removeMany(query: _RawQuery): Promise<UpdateResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.1-rc.2",
+  "version": "3.1.1-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -1,4 +1,4 @@
-import { type BackendEnv, DatabaseModes, getEnv } from "akanjs/base";
+import { type BackendEnv, DatabaseModes, getEnv, INTERNAL_META } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { ConstantRegistry } from "akanjs/constant";
 import {
@@ -195,6 +195,7 @@ export class DiLifecycle {
       this.logger.info("agent relay is provided by a lib module — the framework's is skipped");
     if (!this.#scalar.has("agentTurn"))
       this.#scalar.set("agentTurn", { constant: agentTurnConstant, database: agentTurnDocument });
+    this.#assertUniqueInternalJobs();
     const adaptorClaims = new Map<string, AdaptorCls>();
     const adaptorRegistrations: Registration[] = [];
     const claimAdaptor = (adaptorCls: AdaptorCls, owner: string) => {
@@ -460,6 +461,15 @@ export class DiLifecycle {
     this.logger.verbose(`${doneLabel} in ${Date.now() - now}ms`);
   }
 
+  #assertUniqueInternalJobs() {
+    const jobs = this.#allModules().flatMap(({ signal: { internal } }) =>
+      Object.entries(internal[INTERNAL_META])
+        .filter(([, { type }]) => type !== "resolveField")
+        .map(([key, { type }]) => ({ key, owner: `the ${type} of "${internal.refName}"` })),
+    );
+    assertUniqueRegistrations("internal", jobs);
+  }
+
   registerSchedule(serverMode: "federation" | "batch" | "all") {
     const internals = this.#allModules().map((mod) => mod.signal.internal);
     const failures: { label: string; reason: unknown }[] = [];

package/server/resolver/database.resolver.ts

@@ -11,6 +11,7 @@ import {
   DataLoader,
   DocumentSchema,
   type DocumentScopeOptions,
+  type DocumentTouchOptions,
   type DocumentUpdateInput,
   type DocumentUpdateOptions,
   documentQueryHelper,
@@ -45,6 +46,9 @@ const timedQuery = async <T>(fn: () => Promise<T>): Promise<T> => {
     trace.countDbQuery(performance.now() - start);
   }
 };
+const touchOf = (options?: DocumentTouchOptions) => (options?.touch === false ? { touch: false } : {});
+const touchArgs = (options?: DocumentTouchOptions): [] | [DocumentTouchOptions] =>
+  options?.touch === false ? [{ touch: false }] : [];
 
 export class DatabaseResolver {
   
@@ -205,6 +209,12 @@ export class DatabaseResolver {
         const scopeOf = (options?: DocumentScopeOptions) => (options?.withRemoved ? { withRemoved: true } : {});
         const scopeArgs = (options?: DocumentScopeOptions): [] | [DocumentScopeOptions] =>
           options?.withRemoved ? [{ withRemoved: true }] : [];
+        const updateManyArgs = (
+          options?: DocumentScopeOptions & DocumentTouchOptions,
+        ): [] | [DocumentScopeOptions & DocumentTouchOptions] => {
+          const narrowed = { ...scopeOf(options), ...touchOf(options) };
+          return Object.keys(narrowed).length ? [narrowed] : [];
+        };
         const createFindManyChain = (
           query: QueryOf<any>,
           options: { sort?: any; skip?: number; limit?: number; select?: any; withRemoved?: boolean } = {},
@@ -287,8 +297,11 @@ export class DatabaseResolver {
             timedQuery(() => store.count(query, ...scopeArgs(options))),
           updateOne: (query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentUpdateOptions) =>
             timedQuery(() => store.updateOneByQuery(query, update, options)),
-          updateMany: (query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentScopeOptions) =>
-            timedQuery(() => store.updateManyByQuery(query, update, ...scopeArgs(options))),
+          updateMany: (
+            query: QueryOf<any>,
+            update: DocumentUpdateInput,
+            options?: DocumentScopeOptions & DocumentTouchOptions,
+          ) => timedQuery(() => store.updateManyByQuery(query, update, ...updateManyArgs(options))),
           removeOne: (query: QueryOf<any>) => timedQuery(() => store.removeOneByQuery(query)),
           removeMany: (query: QueryOf<any>) => timedQuery(() => store.removeManyByQuery(query)),
           purgeMany: (query: QueryOf<any>) => timedQuery(() => store.purgeManyByQuery(query)),
@@ -401,11 +414,11 @@ export class DatabaseResolver {
       async __purgeMany(query: QueryOf<any>) {
         return await timedQuery(() => this.__store.purgeManyByQuery(query));
       }
-      async __updateMany(query: QueryOf<any>, update: DocumentUpdateInput) {
-        return await timedQuery(() => this.__store.updateManyByQuery(query, update));
+      async __updateMany(query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentTouchOptions) {
+        return await timedQuery(() => this.__store.updateManyByQuery(query, update, ...touchArgs(options)));
       }
-      async __updateOne(query: QueryOf<any>, update: DocumentUpdateInput) {
-        return await timedQuery(() => this.__store.updateOneByQuery(query, update));
+      async __updateOne(query: QueryOf<any>, update: DocumentUpdateInput, options?: DocumentTouchOptions) {
+        return await timedQuery(() => this.__store.updateOneByQuery(query, update, ...touchArgs(options)));
       }
       async [`remove${className}`](id: string) {
         return this.__remove(id);

package/server/resolver/service.resolver.ts

@@ -1,6 +1,6 @@
 import { capitalize } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
-import type { DatabaseModel, DataInputOf, Doc, DocumentUpdateInput } from "akanjs/document";
+import type { DatabaseModel, DataInputOf, Doc, DocumentTouchOptions, DocumentUpdateInput } from "akanjs/document";
 import { type DatabaseService, type ServiceCls, ServiceModel } from "akanjs/service";
 import type { CascadeRunner } from "./CascadeRunner";
 import { DatabaseResolver } from "./database.resolver";
@@ -38,11 +38,19 @@ export class ServiceResolver {
       async __purgeMany(this: DatabaseService, query: QueryOf<any>) {
         return await this.__databaseModel.__purgeMany(query);
       },
-      async __updateMany(this: DatabaseService, query: QueryOf<any>, update: DocumentUpdateInput) {
-        return await this.__databaseModel.__updateMany(query, update);
-      },
-      async __updateOne(this: DatabaseService, query: QueryOf<any>, update: DocumentUpdateInput) {
-        return await this.__databaseModel.__updateOne(query, update);
+      async __updateMany(
+        this: DatabaseService,
+        query: QueryOf<any>,
+        ...set: [DocumentUpdateInput, DocumentTouchOptions?]
+      ) {
+        return await this.__databaseModel.__updateMany(query, ...set);
+      },
+      async __updateOne(
+        this: DatabaseService,
+        query: QueryOf<any>,
+        ...set: [DocumentUpdateInput, DocumentTouchOptions?]
+      ) {
+        return await this.__databaseModel.__updateOne(query, ...set);
       },
     };
   }

package/service/agent.service.ts

@@ -35,13 +35,16 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
   /**
    * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
-   * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
+   * no-re-read sentences were measured to cut turns against a provider; do not shorten them. The navigation sentence
+   * carves the batching rule: a call batched behind `navigate` was written against the screen being left.
    */
   static readonly preamble = [
     "You are an in-page assistant. Use the published tools to read and drive the screen the user is looking at.",
     "Issue every tool call that does not need another call's result in the same turn, rather than one call per turn.",
     "Prefer the tool that does the whole job in one call, such as a form's fill tool over one call per field.",
     "A tool result already reports what it changed, so never call a read afterwards to confirm work you have just done — answer the user from the results you already have.",
+    "Tools belong to the screen on display: navigate and goBack replace the screen's own tools, and the new screen's are listed only on your next turn, so end the turn at a navigation and call them once they are listed.",
+    "Call a tool only by a name listed to you — never compose or guess one.",
   ].join(" ");
 
   static instructed(request: LlmTurnRequest): LlmTurnRequest {

package/service/predefinedAdaptor/openaiLlm.ts

@@ -1,5 +1,13 @@
 import { adapt } from "../adapt";
-import type { LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import {
+  type LlmAccepts,
+  type LlmAdaptor,
+  type LlmLimits,
+  type LlmOption,
+  type LlmTurnAnswer,
+  type LlmTurnRequest,
+  llmProviderOf,
+} from "./llm.adaptor";
 import { LlmOverflow } from "./llmOverflow";
 import { type OpenaiAnswer, OpenaiDialect } from "./openaiDialect";
 
@@ -24,10 +32,18 @@ export class OpenaiLlm
     return this.llmOption.contextWindow ? { window: this.llmOption.contextWindow } : {};
   }
 
-  /** A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn. */
   get accepts(): LlmAccepts | undefined {
-    if (this.llmOption.accepts) return this.llmOption.accepts;
-    return this.llmOption.host ? undefined : { image: true };
+    return OpenaiLlm.acceptsOf(this.llmOption);
+  }
+
+  /**
+   * A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn.
+   * OpenAI's own endpoint named outright is still OpenAI rather than a gateway. Static, so an app's own
+   * chat-completions adaptor claims what this one does instead of forking the rule.
+   */
+  static acceptsOf({ accepts, host }: LlmOption): LlmAccepts | undefined {
+    if (accepts) return accepts;
+    return !host || llmProviderOf(host) === llmProviderOf(OpenaiLlm.defaultHost) ? { image: true } : undefined;
   }
 
   async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {

package/service/predefinedAdaptor/sql/SqlDocumentStore.ts

@@ -9,6 +9,7 @@ import {
   type DocumentQuery,
   type DocumentSchema,
   type DocumentScopeOptions,
+  type DocumentTouchOptions,
   type DocumentUpdate,
   type DocumentUpdateInput,
   type DocumentUpdateNode,
@@ -471,7 +472,7 @@ export class SqlDocumentStore {
     operation: string,
   ) {
     const resolved = resolveDocumentUpdate(update);
-    const { assignments, params } = this.compiledUpdate(resolved);
+    const { assignments, params } = this.compiledUpdate(resolved, options);
     const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const subquery = `SELECT ${quoteIdent("id")} FROM ${quoteIdent(this.table)} WHERE ${where} ORDER BY ${this.compiler.orderBy()} LIMIT 1`;
 
@@ -490,17 +491,21 @@ export class SqlDocumentStore {
     return { acknowledged: true, matchedCount: 0, modifiedCount: 1, upsertedId: inserted.id };
   }
 
-  async updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options: DocumentScopeOptions = {}) {
+  async updateManyByQuery(
+    query: DocumentQuery,
+    update: DocumentUpdateInput,
+    options: DocumentScopeOptions & DocumentTouchOptions = {},
+  ) {
     return await this.#updateMany(query, update, options, "updateManyByQuery");
   }
 
   async #updateMany(
     query: DocumentQuery,
     update: DocumentUpdateInput,
-    options: DocumentScopeOptions,
+    options: DocumentScopeOptions & DocumentTouchOptions,
     operation: string,
   ) {
-    const { assignments, params } = this.compiledUpdate(resolveDocumentUpdate(update));
+    const { assignments, params } = this.compiledUpdate(resolveDocumentUpdate(update), options);
     const { where, params: whereParams } = this.writeQuery(query, operation, options);
     const sql = `UPDATE ${quoteIdent(this.table)} SET ${assignments.join(", ")} WHERE ${where}`;
     const changes = this.dialect.affectedRows(
@@ -559,14 +564,14 @@ export class SqlDocumentStore {
     return false;
   }
 
-  private compiledUpdate(update: DocumentUpdate) {
+  private compiledUpdate(update: DocumentUpdate, { touch = true }: DocumentTouchOptions = {}) {
     for (const raw of Object.values(update))
       assertStorableJson(jsonStr(isDocumentUpdateNode(raw) ? raw.value : raw), this.table);
-    const compiled = this.updateCompiler.compile(update);
-    return {
-      assignments: [`${quoteIdent("updatedAt")} = ?`, ...compiled.assignments],
-      params: [Date.now(), ...compiled.params],
-    };
+    const { assignments, params } = this.updateCompiler.compile(update);
+    const updatedAt = quoteIdent("updatedAt");
+    if (touch) return { assignments: [`${updatedAt} = ?`, ...assignments], params: [Date.now(), ...params] };
+    
+    return { assignments: assignments.length ? assignments : [`${updatedAt} = ${updatedAt}`], params };
   }
 
   async bulkWrite(

package/service/predefinedAdaptor/sql/types.ts

@@ -6,6 +6,7 @@ import type {
   DocumentQueryNode,
   DocumentSchema,
   DocumentScopeOptions,
+  DocumentTouchOptions,
   DocumentUpdateInput,
   DocumentUpdateOperator,
   DocumentUpdateOptions,
@@ -66,7 +67,7 @@ export interface DocumentStore {
   updateManyByQuery(
     query: DocumentQuery,
     update: DocumentUpdateInput,
-    options?: DocumentScopeOptions,
+    options?: DocumentScopeOptions & DocumentTouchOptions,
   ): Promise<{ acknowledged: boolean; matchedCount: number; modifiedCount: number }>;
   removeManyByQuery(
     query: DocumentQuery,

package/service/serviceModule.ts

@@ -207,11 +207,11 @@ export class ServiceModel<
       },
       [`update${key}`]: function (this: DatabaseService, ...args: any): UpdateChain {
         const query = queryOf(args);
-        return { set: (update) => this.__updateMany(query, update) };
+        return { set: (...set) => this.__updateMany(query, ...set) };
       },
       [`updateOne${key}`]: function (this: DatabaseService, ...args: any): UpdateChain {
         const query = queryOf(args);
-        return { set: (update) => this.__updateOne(query, update) };
+        return { set: (...set) => this.__updateOne(query, ...set) };
       },
     };
   }

package/service/types.ts

@@ -4,6 +4,7 @@ import type { QueryOf } from "akanjs/constant";
 import type {
   DatabaseModel,
   DataInputOf,
+  DocumentTouchOptions,
   DocumentUpdateInput,
   FilterInstance,
   FindQueryOption,
@@ -106,8 +107,16 @@ export type DatabaseService<
   __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
   __purgeMany: (query: _QueryOfDoc) => Promise<number>;
-  __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
-  __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+  __updateMany: (
+    query: _QueryOfDoc,
+    update: DocumentUpdateInput<Doc>,
+    options?: DocumentTouchOptions,
+  ) => Promise<UpdateResult>;
+  __updateOne: (
+    query: _QueryOfDoc,
+    update: DocumentUpdateInput<Doc>,
+    options?: DocumentTouchOptions,
+  ) => Promise<UpdateResult>;
   __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
   __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
   __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/store/agent/AgentVisual.ts

@@ -1,4 +1,3 @@
-import { router } from "akanjs/client";
 import type { ToolActivity } from "../../vendor/use-agentic";
 import { AgentCursor } from "./AgentCursor";
 import { ScreenFlash } from "./ScreenFlash";
@@ -108,28 +107,17 @@ export class AgentVisual {
   }
 
   static #linkTo(path: unknown): HTMLElement[] {
-    const wanted = AgentVisual.#routeOf(typeof path === "string" ? path : "");
+    const wanted = ScreenTarget.routeOf(typeof path === "string" ? path : "");
     if (!wanted || !document.body) return [];
     const links = [...document.body.querySelectorAll<HTMLAnchorElement>("a[href]")].filter(
       (link) =>
-        AgentVisual.#routeOf(link.getAttribute("href") ?? "") === wanted &&
+        ScreenTarget.routeOf(link.getAttribute("href") ?? "") === wanted &&
         ScreenTarget.visible(link) &&
         ScreenFlash.inView(link),
     );
     return AgentVisual.#only(links);
   }
 
-  static #routeOf(href: string) {
-    if (!href || href.startsWith("#")) return "";
-    try {
-      const url = new URL(href, window.location.href);
-      if (url.origin !== window.location.origin) return "";
-      return router.routeOf(url.pathname);
-    } catch {
-      return "";
-    }
-  }
-
   static #navigating(name: string) {
     return name.slice(name.lastIndexOf(".") + 1) === "navigate";
   }

package/store/agent/ScreenTarget.ts

@@ -1,3 +1,4 @@
+import { router } from "akanjs/client";
 import { ScreenReader } from "./ScreenReader";
 
 const containerAttrs = ["data-agent-zone", "data-agent-scope", "data-agent-skip"] as const;
@@ -75,6 +76,30 @@ export class ScreenTarget {
     );
   }
 
+  static linkedRoutes(root?: HTMLElement | null): string[] {
+    const scope = root ?? ScreenTarget.#body();
+    if (!scope) return [];
+    const routes = new Set<string>();
+    for (const link of scope.querySelectorAll<HTMLAnchorElement>("a[href]")) {
+      const route = ScreenTarget.visible(link) ? ScreenTarget.routeOf(link.getAttribute("href") ?? "") : "";
+      if (route) routes.add(route);
+      if (routes.size >= nameCap) break;
+    }
+    return [...routes];
+  }
+
+  /** Through `router.routeOf`: an href carries locale and base-path segments a tool argument lacks. */
+  static routeOf(href: string) {
+    if (!href || href.startsWith("#")) return "";
+    try {
+      const url = new URL(href, window.location.href);
+      if (url.origin !== window.location.origin) return "";
+      return router.routeOf(url.pathname);
+    } catch {
+      return "";
+    }
+  }
+
   static #names(attrs: readonly string[], root?: HTMLElement | null): string[] {
     const scope = root ?? ScreenTarget.#body();
     if (!scope) return [];

package/store/agent/StoreSurfaceSource.ts

@@ -1,4 +1,4 @@
-import { router } from "akanjs/client";
+import { csrLocation, router } from "akanjs/client";
 import { AgenticSurface, type SurfaceSource, type ToolEntry, ToolReturn } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
 import { ScreenFlash } from "./ScreenFlash";
@@ -58,17 +58,38 @@ export class StoreSurfaceSource implements SurfaceSource {
           router.push(path);
           await router.navigation();
         } catch {
-          throw new Error(
-            `There is no route at ${path}, so the page did not move. Call readScreen — it prints each link on this screen with its own path — and navigate to one of those.`,
-          );
+          throw new Error(`There is no route at ${path}, so the page did not move. ${StoreSurfaceSource.#linked()}`);
         }
         
         await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
-        return `Now on ${path}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
+        const landed = StoreSurfaceSource.#redirected(path);
+        return `${landed ? `Asked for ${path}, but the app sent the page to ${landed} instead.` : `Now on ${path}.`} ${StoreSurfaceSource.#arrived}`;
       },
     };
   }
 
+  static readonly #arrived =
+    "This screen's own tools and state replace the previous screen's and are listed on your next turn — call them then, by the names listed. Call readScreen to see the page.";
+
+  static #linked() {
+    const routes = ScreenTarget.linkedRoutes();
+    return routes.length
+      ? `Paths this screen links to: ${routes.join(", ")}. Navigate to one of those rather than composing a path.`
+      : "Call readScreen — it prints each link on this screen with its own path — and navigate to one of those.";
+  }
+
+  /** A redirect or the app's not-found page moves the page somewhere other than the path it was sent to. */
+  static #redirected(path: string): string | null {
+    const trimmed = (route: string) => (route.length > 1 ? route.replace(/\/+$/, "") : route);
+    try {
+      const landed = router.routeOf(csrLocation.pathname);
+      const wanted = router.routeOf(new URL(path, "http://route.invalid").pathname);
+      return trimmed(landed) === trimmed(wanted) ? null : landed;
+    } catch {
+      return null;
+    }
+  }
+
   static #goBack(): ToolEntry {
     return {
       name: "goBack",
@@ -79,7 +100,7 @@ export class StoreSurfaceSource implements SurfaceSource {
       run: async () => {
         router.back();
         await ScreenSettle.wait({ appearMs: 800, timeoutMs: 5000 });
-        return `Back on ${router.getPath()}. Call readScreen to see it; this screen's own tools and state are listed from the next turn.`;
+        return `Back on ${router.getPath()}. ${StoreSurfaceSource.#arrived}`;
       },
     };
   }

package/types/client/router.d.ts

@@ -87,6 +87,7 @@ declare class Router {
         page: number;
     }): void;
     resolveDeepLinkStack(href: string): string[];
+    /** Before init the link waits for it, and the answer is `true`: the manifest that could refuse it is not loaded yet. */
     enterDeepLink(href: string, options?: DeepLinkOptions): boolean;
     push(href: string, routeOptions?: RouteOptions): never;
     replace(href: string, routeOptions?: RouteOptions): never;

package/types/document/database.d.ts

@@ -3,7 +3,7 @@ import type { Logger } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { CacheAdaptor, CacheSetOptions, CacheValue } from "akanjs/service";
 import type { DataLoader } from "./dataLoader.d.ts";
-import type { DocumentUpdateInput } from "./documentQuery.d.ts";
+import type { DocumentTouchOptions, DocumentUpdateInput } from "./documentQuery.d.ts";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta.d.ts";
 import type { Mdl, SaveEventListener, SaveEventType, UpdateResult } from "./into.d.ts";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types.d.ts";
@@ -29,7 +29,7 @@ export declare class CacheDatabase<_T = unknown> {
 }
 /** What `update<Filter>` returns: the patch cannot trail a filter's optional args, so it lands on `.set()`. */
 export interface UpdateChain<Doc = any> {
-    set(update: DocumentUpdateInput<Doc>): Promise<UpdateResult>;
+    set(update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions): Promise<UpdateResult>;
 }
 type QueryMethodOfKey<CapitalizedK extends string, Doc, Insight, _Args extends any[], _ListArgs extends any[], _FindArgs extends any[], _QueryOfDoc = QueryOf<Doc>> = {
     [K in `list${CapitalizedK}`]: (...args: _ListArgs) => Promise<Doc[]>;
@@ -86,8 +86,8 @@ export type DatabaseInstanceWithQuerySort<T extends string = string, Input = any
     __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __purgeMany: (query: _QueryOfDoc) => Promise<number>;
-    __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
-    __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+    __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions) => Promise<UpdateResult>;
+    __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions) => Promise<UpdateResult>;
     __list(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
     __listIds(query: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
     __find(query: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/document/documentQuery.d.ts

@@ -55,7 +55,11 @@ export type DocumentUpdate<T = any> = {
 export interface DocumentScopeOptions {
     withRemoved?: boolean;
 }
-export interface DocumentUpdateOptions extends DocumentScopeOptions {
+export interface DocumentTouchOptions {
+    /** `false` leaves `updatedAt` as stored, for bookkeeping that is no edit: a lease heartbeat, a mirrored snapshot. */
+    touch?: boolean;
+}
+export interface DocumentUpdateOptions extends DocumentScopeOptions, DocumentTouchOptions {
     upsert?: boolean;
 }
 export declare const createDocumentUpdateHelper: () => {

package/types/document/into.d.ts

@@ -3,7 +3,7 @@ import type { DocumentModel, QueryOf } from "akanjs/constant";
 import type { FilterCls, FilterQueryOf, FilterSortOf } from ".";
 import type { CacheDatabase, QueryMethodPart } from "./database.d.ts";
 import type { DataLoader } from "./dataLoader.d.ts";
-import type { DocumentQuery, DocumentScopeOptions, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery.d.ts";
+import type { DocumentQuery, DocumentScopeOptions, DocumentTouchOptions, DocumentUpdateInput, DocumentUpdateOptions } from "./documentQuery.d.ts";
 import { type LoaderBuilder, type ModelCls } from "./loaderInfo.d.ts";
 import type { DocumentProjection } from "./types.d.ts";
 export type CRUDEventType = "create" | "update" | "remove";
@@ -52,7 +52,7 @@ export type Mdl<Doc, Raw, _RawDoc = DocumentModel<Raw>, _RawQuery extends Docume
     count(query: _RawQuery, options?: DocumentScopeOptions): Promise<number>;
     exists(query: _RawQuery, options?: DocumentScopeOptions): Promise<string | null>;
     updateOne(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>, options?: DocumentUpdateOptions): Promise<UpdateResult>;
-    updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>, options?: DocumentScopeOptions): Promise<UpdateResult>;
+    updateMany(query: _RawQuery, update: DocumentUpdateInput<_RawDoc>, options?: DocumentScopeOptions & DocumentTouchOptions): Promise<UpdateResult>;
     removeOne(query: _RawQuery): Promise<UpdateResult>;
     removeMany(query: _RawQuery): Promise<UpdateResult>;
     /** Deletes every row the query matches, removed ones too, and answers how many: no hook, cascade or undo. */

package/types/service/agent.service.d.ts

@@ -13,7 +13,8 @@ export declare class AgentService extends AgentService_base {
     }>;
     /**
      * Prepended to the app's instructions here, not per adaptor, where forgetting it would be silent. The batching and
-     * no-re-read sentences were measured to cut turns against a provider; do not shorten them.
+     * no-re-read sentences were measured to cut turns against a provider; do not shorten them. The navigation sentence
+     * carves the batching rule: a call batched behind `navigate` was written against the screen being left.
      */
     static readonly preamble: string;
     static instructed(request: LlmTurnRequest): LlmTurnRequest;

package/types/service/predefinedAdaptor/openaiLlm.d.ts

@@ -1,4 +1,4 @@
-import type { LlmAccepts, LlmAdaptor, LlmLimits, LlmOption, LlmTurnAnswer, LlmTurnRequest } from "./llm.adaptor";
+import { type LlmAccepts, type LlmAdaptor, type LlmLimits, type LlmOption, type LlmTurnAnswer, type LlmTurnRequest } from "./llm.adaptor";
 declare const OpenaiLlm_base: import("..").AdaptorCls<{}, {
     llmOption: import("..").InjectInfo<"use", LlmOption, never, never>;
 }>;
@@ -11,8 +11,13 @@ export declare class OpenaiLlm extends OpenaiLlm_base implements LlmAdaptor {
     static readonly defaultHost = "https://api.openai.com/v1";
     /** No answer ceiling: the dialect sends none, so the provider's own default is the one that applies. */
     get limits(): LlmLimits;
-    /** A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn. */
     get accepts(): LlmAccepts | undefined;
+    /**
+     * A named host is text-only until `setLlm({ accepts })` says otherwise: undecodable bytes fail the whole turn.
+     * OpenAI's own endpoint named outright is still OpenAI rather than a gateway. Static, so an app's own
+     * chat-completions adaptor claims what this one does instead of forking the rule.
+     */
+    static acceptsOf({ accepts, host }: LlmOption): LlmAccepts | undefined;
     chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
     static refusal(host: string, response: Response): Promise<Error>;
 }

package/types/service/predefinedAdaptor/sql/SqlDocumentStore.d.ts

@@ -1,5 +1,5 @@
 import { type ConstantModel } from "akanjs/constant";
-import { type DatabaseModel, type DocumentQuery, type DocumentSchema, type DocumentScopeOptions, type DocumentUpdateInput, type DocumentUpdateOptions } from "akanjs/document";
+import { type DatabaseModel, type DocumentQuery, type DocumentSchema, type DocumentScopeOptions, type DocumentTouchOptions, type DocumentUpdateInput, type DocumentUpdateOptions } from "akanjs/document";
 import { QueryCompiler } from "./QueryCompiler.d.ts";
 import { type DocumentDatabaseOwner, type DocumentRecord, type FindIdOptions, type FindManyOptions, type FindOneOptions, type SqlDialect, type TransferRow, type UpsertByIdOptions, type WriteHookOptions } from "./types.d.ts";
 import { UpdateCompiler } from "./UpdateCompiler.d.ts";
@@ -34,7 +34,7 @@ export declare class SqlDocumentStore {
         modifiedCount: number;
         upsertedId: any;
     }>;
-    updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options?: DocumentScopeOptions): Promise<{
+    updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options?: DocumentScopeOptions & DocumentTouchOptions): Promise<{
         acknowledged: boolean;
         matchedCount: number;
         modifiedCount: number;

package/types/service/predefinedAdaptor/sql/types.d.ts

@@ -1,6 +1,6 @@
 import type { PromiseOrObject } from "akanjs/base";
 import type { ConstantModel } from "akanjs/constant";
-import type { DatabaseModel, DocumentQuery, DocumentQueryNode, DocumentSchema, DocumentScopeOptions, DocumentUpdateInput, DocumentUpdateOperator, DocumentUpdateOptions } from "akanjs/document";
+import type { DatabaseModel, DocumentQuery, DocumentQueryNode, DocumentSchema, DocumentScopeOptions, DocumentTouchOptions, DocumentUpdateInput, DocumentUpdateOperator, DocumentUpdateOptions } from "akanjs/document";
 import type { SearchIndex } from "../searchIndex.d.ts";
 import type { SqlDocumentStore } from "./SqlDocumentStore.d.ts";
 export interface SqliteDatabaseConfig {
@@ -52,7 +52,7 @@ export interface DocumentStore {
         modifiedCount: number;
         upsertedId: string | null;
     }>;
-    updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options?: DocumentScopeOptions): Promise<{
+    updateManyByQuery(query: DocumentQuery, update: DocumentUpdateInput, options?: DocumentScopeOptions & DocumentTouchOptions): Promise<{
         acknowledged: boolean;
         matchedCount: number;
         modifiedCount: number;

package/types/service/types.d.ts

@@ -1,7 +1,7 @@
 import type { Cls, MergeAllTypes, PromiseOrObject } from "akanjs/base";
 import type { Logger } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
-import type { DatabaseModel, DataInputOf, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventListener, SaveEventType, UpdateResult } from "akanjs/document";
+import type { DatabaseModel, DataInputOf, DocumentTouchOptions, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventListener, SaveEventType, UpdateResult } from "akanjs/document";
 type ServiceMixinOmitKey = "onInit" | "onDestroy" | "_libsOnInit" | "_libsOnDestroy" | "_preCreate" | "_postCreate" | "_preUpdate" | "_postUpdate" | "_preRemove" | "_postRemove" | "_libsPreCreate" | "_libsPostCreate" | "_libsPreUpdate" | "_libsPostUpdate" | "_libsPreRemove" | "_libsPostRemove";
 type DatabaseQueryMethods<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery> = QueryMethodPart<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery>;
 type DocumentLike = {
@@ -34,8 +34,8 @@ export type DatabaseService<T extends string = string, Input = any, Doc = any, O
     __removeMany: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __removeOne: (query: _QueryOfDoc) => Promise<UpdateResult>;
     __purgeMany: (query: _QueryOfDoc) => Promise<number>;
-    __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
-    __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>) => Promise<UpdateResult>;
+    __updateMany: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions) => Promise<UpdateResult>;
+    __updateOne: (query: _QueryOfDoc, update: DocumentUpdateInput<Doc>, options?: DocumentTouchOptions) => Promise<UpdateResult>;
     __list(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<Doc[]>;
     __listIds(query?: _QueryOfDoc, queryOption?: _ListQueryOption): Promise<string[]>;
     __find(query?: _QueryOfDoc, queryOption?: _FindQueryOption): Promise<Doc | null>;

package/types/store/agent/ScreenTarget.d.ts

@@ -10,5 +10,8 @@ export declare class ScreenTarget {
     static containerNames(root?: HTMLElement | null): string[];
     static anchorNames(root?: HTMLElement | null): string[];
     static targetNames(root?: HTMLElement | null): string[];
+    static linkedRoutes(root?: HTMLElement | null): string[];
+    /** Through `router.routeOf`: an href carries locale and base-path segments a tool argument lacks. */
+    static routeOf(href: string): string;
     static visible(el: HTMLElement): boolean;
 }

package/vendor/use-agentic/AgentSession.ts

@@ -192,6 +192,8 @@ export class AgentSession {
   #limits: TurnLimits = {};
   /** What the tools, the screen context and the instructions cost the last request, for a host's gauge. */
   #overhead = 0;
+  /** The tool names the model was handed on the turn now running — what its calls were written against. */
+  #listed: readonly string[] = [];
 
   constructor(surface: SurfaceView, runner: AgentRunner, options: AgentSessionOptions = {}) {
     this.#surface = surface;
@@ -211,7 +213,7 @@ export class AgentSession {
       fallback: async (call, signal) =>
         call.name === AgentSession.askUserTool.name
           ? await this.#ask(call, signal)
-          : { id: call.id, name: call.name, error: `Unknown tool: ${call.name}` },
+          : { id: call.id, name: call.name, error: this.#unknown(call.name) },
     });
     this.#history = options.history;
     this.#onCompact = options.onCompact;
@@ -746,6 +748,7 @@ export class AgentSession {
   ): Promise<{ toolCalls: ToolCallRequest[]; stop: TurnStop; overflow?: { message: string; limit?: number } }> {
     const frame = this.#frame();
     this.#overhead = AgentSession.#tokensOfFrame(frame);
+    this.#listed = frame.tools.map((tool) => tool.name);
     const request: RunnerRequest = { messages: Transcript.wire(this.#messages), ...frame, signal };
     this.#append({ role: "assistant" });
     let text = "";
@@ -780,6 +783,20 @@ export class AgentSession {
     return Array.isArray(settled.result) ? settled.result.join(", ") : settled.result;
   }
 
+  /**
+   * Answered with the names that exist: a bare refusal sends a model guessing the next name. A screen that moved
+   * since the turn's list was written is said so, since that call was written against the screen it left.
+   */
+  #unknown(name: string): string {
+    const shown = this.#surface.snapshot().tools.map((tool) => tool.name);
+    const now = shown.includes(AgentSession.askUserTool.name) ? shown : [...shown, AgentSession.askUserTool.name];
+    const listed = new Set(this.#listed);
+    const moved = now.length !== listed.size || now.some((one) => !listed.has(one));
+    return moved
+      ? `Unknown tool: ${name}. The screen changed during this turn, so this call was written against tools that are no longer on it. The tools on screen now are listed with their arguments on your next turn — call one then by its exact name: ${now.join(", ")}.`
+      : `Unknown tool: ${name}. Call only a tool listed to you, by its exact name — never a guessed one. Listed now: ${now.join(", ")}.`;
+  }
+
   /** No surface call and so no diff to report: the only thing this changes is what the model knows. */
   async #ask(call: ToolCallRequest, signal: AbortSignal): Promise<ToolCallResult> {
     const base = { id: call.id, name: call.name };