@jskit-ai/agent-docs 0.1.257 → 0.1.258

package/guide/agent/app-extras/assistant-conversation.md

@@ -93,7 +93,7 @@ as not sent with `conversation_message_cancelled`. It also stops a submission
 that holds the message, and afterwards discards its unconfirmed request or
 pending native attempt. A message already accepted stays history. An
 application conversation provides this as `cancelDelivery({ messageId })`;
-without it the operation answers `conversation_unsupported`. Browser inputs cannot set the actor,
+without it the operation answers `conversation_message_cancel_unsupported`. Browser inputs cannot set the actor,
 native host or engine context.
 `readConversation(id, { beforeTurnId, limit, signal })` optionally requests an
 earlier or bounded page through the same authenticated GET. Its query contains
@@ -1120,8 +1120,8 @@ separate concerns.
 ## Optional shared capabilities
 
 All capabilities below are optional. Omit their adapter field to leave them off.
-They work in the aggregate element and as separately exported components; Vibe64
-uses the same components with its native transport and project policy.
+They work in the aggregate element and as separately exported components; a hosted
+editor can use the same components with its native transport and project policy.
 Configuration UI never grants backend permissions.
 
 ### Working status and suggestions
@@ -1312,7 +1312,7 @@ adapter.attachments = reactive(useAssistantAttachments({
 ```
 
 `sessionId` is an opaque application upload scope, such as a conversation or
-session identifier. It does not require Vibe64. The application owns routes,
+session identifier. It does not require a hosted editor. The application owns routes,
 authentication, storage, limits, inspection, retention and provider file access.
 An upload returns `{ attachmentId, fileName, size }` with optional `reference` and
 application fields. Progress reports use `{ loaded, total }`. The controller
@@ -1479,7 +1479,7 @@ history, sends, stops, deletion and attachment reads. The memory reference
 adapter requires a nonempty string; other adapters may use structured scopes.
 
 Each callback receives these asynchronous operations. The first six serve the
-transcript service. All nine are mandatory for `createConversationRuntime()`:
+transcript service. All the others are mandatory for `createConversationRuntime()`:
 
 | Transaction operation | Contract |
 | --- | --- |
@@ -1493,6 +1493,9 @@ transcript service. All nine are mandatory for `createConversationRuntime()`:
 | `readMetadata()` | Detached conversation metadata object; return `{}` for an empty scope. |
 | `writeMetadata(value)` | Replace conversation metadata within this transaction, committing atomically with its turn/message changes. |
 | `updateTurnMetadata(turnId, patch)` | Shallow-merge a detached patch into an existing turn's metadata; preserve unrelated keys and reject absent turns. |
+| `readTurnsAfter(turnId)` | Detached snapshots of the turns after that turn, oldest first, as `readTurn` returns them; `""` reads every turn. Reject an absent turn. |
+| `readSummary()` | The API compaction summary `{ text, throughTurnId }` (the last turn it covers), detached, or null. |
+| `writeSummary({ text, throughTurnId })` | Replace that summary within this transaction; reject empty text or an absent turn. Messages are never deleted. |
 
 `write` serializes mutations for the same scope, including duplicate checks and
 ID allocation. A successful return means the write is durable for that adapter.
@@ -1505,6 +1508,9 @@ Reads must not expose mutable backing objects.
 Use storage-level locks or transactions when several processes share storage;
 an in-process promise queue alone does not provide that guarantee.
 
+`readConversationLog(scope, { afterTurnId })` reads only the turns after that turn,
+through the transaction's `readTurnsAfter`.
+
 The service exposes `readConversationLog`, `readConversationLogPage`,
 `conversationMessageIdExists`, `writeConversationUserMessage`,
 `writeConversationAssistantMessage`, `writeConversationThinkingMessage`,
@@ -1536,7 +1542,8 @@ await verifyConversationStorageContract(storage, { runtime: true });
 Those checks cover scoped isolation, concurrent duplicate writes, stable
 ordering, pagination, final replacement, attachments and detached reads. An
 adapter selected with `runtime: true` also checks all metadata operations, scope
-isolation, patch preservation and combined transcript/metadata rollback. Use a
+isolation, patch preservation, combined transcript/metadata rollback, reading the
+turns after a turn and the saved, scoped and rolled-back compaction summary. Use a
 fresh isolated fixture for each invocation; omit the option only for transcript-only
 adapters. An app must additionally test its authentication, crash/reopen behavior,
 multi-process writes, failed commits and attachment cleanup.
@@ -2390,7 +2397,8 @@ the same transaction. The file adapter remains one-writer storage.
 
 `createConversationStorage({ readRecord, writeRecord, deleteRecord, recordVersion })` is exported
 for custom single-writer record stores. Each record contains `{ turns: Map,
-metadata: object }`; a missing record uses an empty map and metadata object. Its
+metadata: object }` and, once an API conversation is compacted, `summary: { text,
+throughTurnId }`; a missing record uses an empty map and metadata object. Its
 copy-on-write transaction methods match the supplied memory/file adapters. Saved
 records are shared and never changed in place; a transaction copies only the turn
 map and the turns it changes. The optional `recordVersion(id)` returns a cheap
@@ -2405,26 +2413,69 @@ serializes writes through one instance, not across processes. A database-backed
 application with concurrent writers must implement `read`/`write` using its own
 database transaction or hold that transaction across record loading and commit.
 
-The current API driver supports application action tools and authorized attachments.
-It reports steering and native goals as unsupported. Limits can bound input, output and history characters, output
-tokens and request duration. Oversized history fails explicitly; it is not silently
-truncated or presented as native compaction. These capabilities will be extended
-as their shared integrations are migrated.
-
-API replies use the shared streaming completion parser. Internal reasoning and
-provider tool markup stay out of visible replies, including tags split across
-chunks. Structured and text-encoded application calls use the same authorized
-execution and saved receipts. A completed response is required before executing
-a call; interrupted streams do not imply permission to execute or retry it.
-Output limits count raw provider text, including hidden blocks. Code indentation
-and blank lines remain intact in ordinary API answers.
+The API driver runs each reply on the agent engine, `@jskit-ai/agent`. It supports
+application action tools and authorized attachments, and reports steering and native
+goals as unsupported. Limits can bound input and output characters, output tokens,
+steps and request duration. `limits.maxOutputCharacters` bounds each step's text
+and the final reply; reasoning is bounded by output tokens instead.
+
+A long conversation is compacted rather than refused. `limits.contextTokens`
+(default 128,000) is the model's window, and the engine's sizes scale to it. Past
+the engine's compaction point, everything but the latest turns is folded into a
+summary written for the model, and storage keeps that summary with the last turn
+it covers (`writeSummary`). Later turns read only the turns after it
+(`readTurnsAfter`) and send the summary in the system prompt; messages are never
+deleted. Should compacting fail, the engine's last-resort cut drops the oldest
+messages and tells the model so. A bound conversation's host owns its transcript,
+so it is not compacted, and history an application supplies as `apiHistory` is
+used as given. History turns within the newest 20 messages send their files again;
+older turns name their files without their content.
+
+Each reply streams one message per step: `reply-1`, `reply-2` and so on. A step
+that also calls actions ends as commentary, complete before the first of its actions
+runs, and the reply's last step becomes the answer. The answer leaves out words already shown as commentary, unless they are
+all the reply says. Reasoning a model writes inline in `<think>` tags is kept as
+reasoning, including tags split across chunks. Provider tool markup and DeepSeek's
+own tokens never reach visible text, and a call written out as text never runs: the
+markup check below tells the model so. Every structured action call runs through
+the same authorized execution and saved receipts; a call to an action the model was
+not given is answered as a tool error, and nothing runs or is saved for it. A
+failed action reaches the model as its error; an unknown outcome or a broken
+receipt ends the reply at once with its error. A completed step is required before
+any of its calls runs.
+Results of earlier turns past 6,000 characters are cut, and the third, fifth and
+eighth identical call in a row tells the model it is not making progress.
+
+A finished reply gets the engine's checks. Each sends it back once to carry on from
+its own steps: raw markup (nothing in it ran), a reply that stops at announcing
+its next step, and, when neither ran, a claimed action that the reply's own
+actions do not support (one short model call compares them). The completion
+metadata names the check as `check`. A reply that ends with the engine's own
+account of where it got to is never sent back as stopping short.
+
+A reply runs at most `limits.maxSteps` steps (default 40, the engine's limit for
+work with app tools). Out of steps, or past the engine's 15-minute reply deadline,
+it ends with the model's own short account of what it did and what is left, and
+the completion metadata says why as `unfinished`. Failed model calls are tried
+again six times with growing waits (or the provider's retry-after), about two
+minutes in all. When nothing has been done yet, the call's error fails the turn as
+status information; after some steps, the engine's account ends the reply instead.
+
+Admission precedes every model call. The first resolves the authorized connection,
+checks access and admits the request; every later call (steps, checks, summaries,
+accounts) authorizes the same connection again and stops the reply when access is
+gone. A configured `effort` reaches every provider as the AI SDK's standard
+reasoning setting; without one, the engine's default applies (adaptive thinking at
+high effort for Anthropic-format models). The system prompt is the configured
+instructions, then the summary, then the engine's state note with the current UTC
+time.
 
 An application can set server-owned `limits.maxApiToolProgressCharacters` to a
 positive safe integer to bound the decoded text accompanying confirmed API tool
 calls. The API driver rejects oversized progress before executing any call from
 that response; it does not clip the text or ask the model to repeat the operation.
 Omit the limit to retain the original API policy. It does not change final-answer
-limits or the original sixteen tool rounds and three recovery passes. This option
+limits or the step limit. This option
 applies only to the direct API carrier; native tool progress needs association
 with its exact admitted native use at that engine's execution boundary.
 
@@ -2440,14 +2491,9 @@ OpenCode delivery recovery applies the bound to the joined decoded native reply
 while retaining the proven user admission and avoiding another inference. An advanced
 host supplying its own native runtime retains that runtime's writer policy.
 
-The API driver uses the existing assistant tool-loop policy: up to sixteen tool
-rounds, then three recovery passes with tools disabled. Progress-only narration
-is retained as commentary rather than accepted as the final answer. An available
-clock action marked `current-time` runs before inference for time questions only
-when it requires no parameters, after connection authorization and turn admission.
-Uncertain application effects stop the turn; recovery never silently retries them.
-The legacy database service delegates to the same loop through its transactional
-adapter over the existing conversation, message and request-claim rows.
+The state note carries the current time; no action runs before inference. Uncertain application effects stop the turn; nothing
+silently retries them. The legacy database service delegates to the same driver through its
+transactional adapter over the existing conversation, message and request-claim rows.
 
 ### Authorized attachments
 
@@ -2545,7 +2591,8 @@ or application turn owns separate call identities, even if the model reuses an
 ID. An interrupted reservation without a
 result or a server failure after execution stops the turn with an unknown-outcome
 error instead of executing again. Applications
-still own action-level idempotency and inspection of uncertain external effects.
+still make each action tolerate a repeated request in its own domain, and
+inspect uncertain external effects.
 The runtime cannot infer whether two different call IDs mean the same mutation.
 
 Events with `type: "tool"` carry the call's `id`, `name`, `arguments`, `status` and,
@@ -2769,8 +2816,8 @@ execution identity remains the filesystem boundary for those tools.
 
 Install Claude Code and log in with `claude auth login` under the application's
 server identity. The ordinary single-user host uses that account and owned POSIX
-process groups. It requires no Vibe64, Genesis or application-specific startup
-callbacks:
+process groups. It requires no hosted editor, project tooling or application-specific
+startup callbacks:
 
 ```js
 const runtime = createConversationRuntime({
@@ -3535,6 +3582,12 @@ facilities before inspecting its own native state. Its history-idle query reads
 that same state; the host separately checks durable process receipts and actual
 terminal activity. No second activity cache or restoration loop is required.
 
+The application that creates the owner may pass its own error builder as
+`createError(message, { code })`. Every refusal the owner raises passes its own
+code, such as `conversation_claude_session_closing` or
+`conversation_claude_message_required`, so the builder forwards that code
+instead of giving every refusal the same one.
+
 The owner serializes preparation with native controls and preserves the original
 control-interrupt followed by mandatory process drain. A failed drain stays an
 error. The host retains execution policy, durable cleanup and publication at
@@ -3721,7 +3774,7 @@ acknowledgement, stream blocks, nested-event exclusion, background-task
 completion and the interruption barrier for steering. Normalized owner events
 let the host persist admissions and publish application state; receiver
 completion alone does not prove process exit. `claudeNativeMessageId()`
-retains the same stable native message IDs used by the Vibe64 adapter.
+retains the same stable native message IDs that a host's own adapter uses.
 An exact native acknowledgement ends its ACK deadline before the admission
 writer runs; a slow write remains awaited, and a rejected write rejects admission.
 A missing acknowledgement remains uncertain. Native failure-result text stays
@@ -3933,8 +3986,8 @@ sandbox or resource limiter. It does not grant a permission bypass by default.
 The native executable and its account login must already exist. Call `stop()`
 and await its proof on shutdown; closing the protocol stream alone does not
 prove that native work stopped. Failed cleanup remains an error or an unconfirmed
-proof, and the owning application must retain its stop handle. Managed applications
-such as Vibe64 replace execution to enforce identity, resources and scope cleanup.
+proof, and the owning application must retain its stop handle. Managed hosts
+replace execution to enforce identity, resources and scope cleanup.
 
 For native history retirement, `nativeConversationStoragePolicy(engineId)` from
 `/server/conversation` describes the engine's writer requirements. Codex's native

package/guide/agent/app-extras/assistant.md

@@ -369,6 +369,12 @@ must have a documented exclusion or a description, output contract, result adapt
 and execution fixture. Application-defined automation actions require the same
 review; automation capability alone does not mean model exposure is safe.
 
+An application test that checks which actions a surface's assistant offers, or
+calls them as the assistant would, builds the catalogue the runtime builds:
+`createSurfaceAwareToolCatalog(actions, { appConfig })` from
+`@jskit-ai/assistant-runtime/server`, with the application's `runtime.actions`
+and its server configuration. Each call names its surface in `context.surface`.
+
 Generated list and view actions use JSON:API query shapes directly. `include`
 is a comma-separated string, and `fields` is keyed by resource type:
 
@@ -432,8 +438,7 @@ catalog by opting it in explicitly:
 ```js
 extensions: {
   assistant: {
-    alwaysAvailable: true,
-    preflight: ["current-time"]
+    alwaysAvailable: true
   }
 }
 ```
@@ -446,32 +451,27 @@ lookup before discovery-mode execution.
 ### Database surface conversation lifecycle
 
 The client receives answer text incrementally and shows working status before
-text arrives. Tool calls produce timeline events. Internal reasoning tags and raw
-tool arguments do not become visible answer text. A tool/recovery round replaces
-its provisional answer; completed answers occupy the existing chat rows.
-Common runtime commentary is retained separately from those chat rows. Progress-only
-responses such as “Let me query…” may appear provisionally while streaming but
-are retried internally and never stored or replayed as final chat history.
-
-The runtime permits up to 16 bounded tool rounds so catalog search, contract
-lookup, and execution can complete in one turn. If ordinary tool-failure
-recovery cannot finish, the runtime returns the latest successful tool result
-with a 4,000-character cap, or a concise failure when there was no successful
-result. Genuine round-budget exhaustion ends with exactly `Limit reached. Start
-a new conversation.`
-
-For current or relative date and time questions, the runtime instructs the
-model to use an available authoritative workspace clock action. When an
-authorized `preflight: ["current-time"]` action has no model-required input,
-the runtime executes it before the first model completion and places its result
-in model history. Mark it `alwaysAvailable` when the authorized catalog can
-enter discovery mode. Trusted workspace input can still be required by the
-application because JSKIT hides and injects it before execution.
-
-The clock action and its timezone policy remain application-owned; JSKIT does
-not invent a clock action or infer the current date from model knowledge. Make
-that action automation-capable and available on the assistant surface if the
-product needs now, today, tomorrow, or other relative-date answers.
+text arrives. Tool calls produce timeline events. Internal reasoning, provider tool
+markup and raw tool arguments do not become visible answer text. Each model step
+streams its own provisional answer; a step that also calls actions is kept as
+commentary, separately from the chat rows, and the last step becomes the completed
+answer in the existing chat rows.
+
+Replies run on the agent engine (`@jskit-ai/agent`), up to 40 steps by default, so
+catalog search, contract lookup and execution can complete in one turn. A failed
+action reaches the model as its error. A reply that runs out of steps ends with
+the model's own account of what it did and what is left. The engine's checks send
+a reply back once when it leaks markup, stops at announcing its next step (“Let me
+query…”), or claims an action no tool performed. Long conversations are summarised
+rather than refused; see the conversation runtime guide.
+
+Every request carries the current date and time in UTC in the engine's state
+note, so no turn needs an extra action to learn it, and no action runs before
+the model asks for one. The workspace's own time
+zone and clock remain application-owned: when answers need local now, today or
+tomorrow, make a clock action automation-capable, available on the assistant
+surface and `alwaysAvailable` when the catalog can enter discovery mode, and the
+model calls it like any other action.
 
 Conversation restoration loads every transcript page needed to retain the
 newest bounded transcript window, so a completed response on page two does not

package/guide/agent/app-setup/authentication.md

@@ -44,12 +44,15 @@ An application with accounts always includes the managed-preview login, whether
 or not anyone asked for it. Adding authentication adds both parts from the
 `auth/auth-surface` pattern:
 
-- the committed, executable `tools/preview-identity` from its example;
-- the `#### Preview identity` block in the web-presented Vibe64 `Outputs`
-  target (Command `tools/preview-identity`, Protocol
-  `vibe64.preview-identity.command.v1`, Identity types `email` `user-id`,
-  Enabled environment `AUTH_DEV_BYPASS_ENABLED`, Secret environment
-  `AUTH_DEV_BYPASS_SECRET`, Runtimes `nodejs`), copied exactly from the pattern.
+- the committed, executable `tools/preview-identity` from its example, which
+  passes `runManagedPreviewIdentityCommand` the preview host's protocol id, the
+  hostnames, besides loopback, that the host serves the app on, and the process
+  environment;
+- its declaration to the preview host in the form that host reads (for a host
+  that reads the web `Outputs` target, the pattern's `#### Preview identity`
+  block: Command `tools/preview-identity`, the same protocol id, Identity types
+  `email` `user-id`, Enabled environment `AUTH_DEV_BYPASS_ENABLED`, Secret
+  environment `AUTH_DEV_BYPASS_SECRET`, Runtimes `nodejs`).
 
 The preview host supplies both environment values per run, so a managed
 preview can sign its browser in as an existing account. Which accounts it may
@@ -76,32 +79,48 @@ capability using an ordinary application provider:
 
 ```js
 import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { createRecoverySender } from "./recoverySender.js";
 
 export const RecoveryEmailProvider = defineProvider({
   id: "app.recovery-email",
   requires: { mail: "app.mail" },
   provides: { recoverySender: "auth.local.recovery-sender" },
+  /** @param {{ mail: import("@local/mail/server/types").AppMail }} capabilities */
   setup({ mail }) {
-    return {
-      recoverySender: async ({ email, recoveryUrl }) => {
-        await mail.send({
-          to: email,
-          subject: "Reset your password",
-          text: `Open this link to reset your password:\n\n${recoveryUrl}\n`
-        });
-      }
-    };
+    return { recoverySender: createRecoverySender({ mail }) };
   }
 });
 ```
 
+```js
+// recoverySender.js
+/** @param {{ mail: import("@local/mail/server/types").AppMail }} dependencies */
+function createRecoverySender({ mail }) {
+  /** @type {import("@jskit-ai/auth-provider-local-core/server/types").AuthLocalRecoverySender} */
+  async function sendRecoveryEmail({ email, recoveryUrl }) {
+    await mail.send({
+      to: email,
+      subject: "Reset your password",
+      text: `Open this link to reset your password:\n\n${recoveryUrl}\n`
+    });
+  }
+
+  return sendRecoveryEmail;
+}
+
+export { createRecoverySender };
+```
+
 `app.mail` is an application-owned capability in this example, not a built-in
 JSKIT email API. Its `send()` implementation owns the selected integration,
 credential resolution and safe error mapping. A connected account or a domain
 listing adapter alone does not implement email sending. Install this provider
 alongside the application's mail provider and `AuthLocalProvider`.
+[Typed features](/guide/framework/typed-features) describes how application
+providers name and type the capabilities they receive.
 For direct library composition, pass the same function as `recoverySender` to
-`createLocalAuthService()`.
+`createLocalAuthService()`, with a configuration from
+`resolveLocalAuthConfig({ appRoot, env, fileBackend, emailRecovery: true })`.
 
 Set `APP_PUBLIC_URL` to the application's actual public URL. When a sender is
 configured, auth requires this value and does not return or log the recovery
@@ -213,7 +232,7 @@ in the server process and use `loginAsExistingUser()` from
 client environment.
 
 A managed host instead supplies authenticated state through
-`VIBE64_PLAYWRIGHT_STORAGE_STATE` and the app-owned Playwright config. Treat the
+`PLAYWRIGHT_STORAGE_STATE` and the app-owned Playwright config. Treat the
 file as a temporary secret, use relative URLs, and do not call the localhost
 login helper or start a duplicate server.
 

package/guide/agent/app-setup/database-layer.md

@@ -54,14 +54,20 @@ application file is small:
 import { createKnexMigrationConfigFromApp } from
   "@jskit-ai/database-runtime/server/knexMigrationConfig";
 
-export default await createKnexMigrationConfigFromApp({ client: "mysql2" });
+export default await createKnexMigrationConfigFromApp({ client: "mysql2", environment: process.env });
 ```
 
-Use `client: "pg"` for PostgreSQL. The complete examples are in:
+Use `client: "pg"` for PostgreSQL. The environment is always passed: JSKIT reads
+the connection values from what the application gives it, never from
+`process.env` on its own. The complete examples are in:
 
 - `database/mysql-application`
 - `database/postgres-application`
 
+Each example is complete for its own engine. Copy files only from the selected
+driver's pattern and never merge the two; for example, the CI workflow must
+contain only that engine's database service.
+
 The config discovers migrations directly from the current installed package
 graph. Application migrations live in the app's `migrations/` directory;
 package-owned migrations live in directories declared by the installed
@@ -111,6 +117,30 @@ package's metadata:
 }
 ```
 
+A `constraints/` subdirectory of a declared directory, such as
+`migrations/constraints/`, holds the package's constraints migrations; it runs
+later, as described below.
+
+A package whose table migrations use another package's tables names that
+package in `after`, and its migrations, and its constraints, then run after
+that package's:
+
+```json
+{
+  "jskit": {
+    "migrations": {
+      "directories": ["migrations"],
+      "after": ["@jskit-ai/users-core"]
+    }
+  }
+}
+```
+
+Each name in `after` must be another installed JSKIT package; a name that is
+not installed, the package's own name, or packages that each name the other
+stop discovery with an error. A named package without migrations orders
+nothing.
+
 Names must remain unique across the effective migration directories. Preserve
 the basename when relocating a migration: Knex records that name in its ledger.
 Do not rename it to force execution or edit an already-applied migration's body;
@@ -121,24 +151,60 @@ changed schema behavior requires a new migration.
 `createKnexMigrationConfigFromApp()` sets `sortDirsSeparately: true` and runs
 pending migrations in this order, using the default `migrationsDirectory`:
 
-1. Application `migrations/`.
-2. Discovered package migration directories, sorted by their absolute paths
-   using `localeCompare`.
-3. Application `migrations/constraints/`.
+1. Discovered package migration directories, sorted by their absolute paths
+   using `localeCompare`, except that a package's directories follow those of
+   every package its `after` names, which follow theirs in turn, each in the
+   order listed. Without `after` the path order is unchanged.
+2. Application `migrations/`.
+3. The `constraints/` subdirectory of each discovered package migration
+   directory that has one, in the same order.
+4. Application `migrations/constraints/`.
 
 Knex sorts filenames within each directory, not across the whole graph; see
 its [`sortDirsSeparately` option](https://knexjs.org/guide/migrations.html#migration-api).
-Package discovery does not topologically order tables or foreign keys. A newer
-timestamp in an earlier package still runs before every file in a later package.
+Package discovery does not read tables or foreign keys; only `after` changes
+the package order. A newer timestamp in an earlier package still runs before
+every file in a later package.
 Inspect the effective `knexfile.js` configuration if the app customizes it.
 
-Keep table and column creation with the owning package. Put cross-package
-foreign keys and other constraints that need the complete package schema in
-application `migrations/constraints/`. An ordinary root `migrations/` file runs
-too early for this purpose. For example, a `pet_notes.product_id` column can be
+Every package table exists before the application's own migrations run, so a
+root `migrations/` file can reference a package table directly, for example a
+`books.user_id` foreign key to `users.id`. A package's table migrations must
+never depend on an application table.
+
+Keep table and column creation with the owning package. Put foreign keys
+between two packages, and other constraints that need the complete schema, in a
+constraints phase: the referencing package's own `constraints/` subdirectory
+when it ships the key, or application `migrations/constraints/`. A package
+constraints migration runs after the application's `migrations/`, so it can also
+reference a table that may belong to the application, such as `users`; for
+example, `@jskit-ai/assistant-runtime` adds its `users` and `workspaces` keys
+from `migrations/constraints/`. Similarly, a `pet_notes.product_id` column can be
 added by the pet-notes package, but its foreign key to the products package's
-`products.id` belongs in the final constraints phase. Do not rely on today's
-package-directory order to make a cross-package reference work.
+`products.id` belongs in a constraints phase. Do not rely on the
+package-directory path order to make a cross-package reference work; when a
+package's table migrations need another package's table, declare `after`.
+
+Until `@jskit-ai/database-runtime` 0.1.252, root `migrations/` ran before the
+package directories, so a fresh database failed on any application migration
+that referenced a package table. Applied migrations stay in the Knex ledger;
+only pending ones follow the new order. An application migration that still
+creates a package-owned table belongs in that package.
+
+The assistant-runtime, console-core and rewarded-core table migrations used to
+add their keys to `users`, `workspaces` and later tables inline. A fresh MySQL
+or MariaDB database failed when the parent table did not exist yet (errno 150),
+and the assistant tables silently skipped their `workspaces` keys. They now add
+them from `migrations/constraints/`. A database migrated earlier keeps the keys
+it already has, and gains any that are missing.
+
+`@jskit-ai/database-runtime/server/foreignKeyMigrations` serves constraints
+migrations that must run on fresh and already-migrated databases alike.
+`addMissingForeignKey(knex, key)` adds a single-column key only when no key
+already links that column to the parent column. It fails, naming the table,
+column and count, when rows have no parent, and it deletes nothing; repair
+those rows and migrate again. `dropForeignKeyIfPresent(knex, key)` serves
+`down()`.
 
 Before adding the key, check that both tables and columns exist, the referenced
 key is indexed appropriately, column types match (including integer signedness),
@@ -206,7 +272,40 @@ Repositories own database access. Services and lifecycle hooks orchestrate
 repositories. External delivery belongs after commit; when it must be durable,
 write an outbox record inside the transaction and deliver it separately.
 A separate Feature is warranted when an operation belongs to another domain,
-not merely because a useful resource has behavior beyond list and save.
+not merely because a useful resource has behavior beyond list and save. Write
+it as a [typed feature](/guide/framework/typed-features).
+
+## Optimistic locking
+
+A CRUD resource whose records carry a version number names it with
+`lockVersionField`, an integer schema field over a non-null integer column
+with a starting value, such as `0`:
+
+```js
+defineCrudResource({
+  namespace: "contracts",
+  tableName: "contracts",
+  autofilter: "workspace",
+  lockVersionField: "lockVersion",
+  schema: {
+    // ...
+    lockVersion: { type: "integer", min: 0, readOnly: true, column: "lock_version" }
+  }
+});
+```
+
+The CRUD repository's
+`patchDocumentIfLockVersion(recordId, expectedLockVersion, patch, { trx, context })`
+then applies `patch` only while the record still holds `expectedLockVersion`, a
+non-negative integer, and adds one to the lock version in the same
+transaction: the caller's `trx`, or one it owns. It returns the patched document, which carries the new lock
+version, or `null` when the record does not exist or is outside the caller's
+scope. A record whose lock version has moved on rejects with a 409 coded
+`crud.document.lockVersionConflict` ("This record changed. Reload and try
+again."), and nothing is written. The patch leaves the lock field out; an app
+that wants its own wording for the conflict catches that code. A resource
+without `lockVersionField` cannot call it, and `defineCrudResource()` rejects
+a `lockVersionField` that names no integer schema field.
 
 ## Deadlock retries
 
@@ -218,8 +317,8 @@ request instead of a 500. This applies to `runInTransaction()` and
 `createWithTransaction()` from `@jskit-ai/database-runtime/shared`, to
 `transactionManager.inTransaction()`, to the seed transaction, to every JSON
 REST repository's `withTransaction()` (CRUD, users and workspaces), and to a
-CRUD `createDocument`, `patchDocumentById` or `deleteDocumentById` given no
-`trx`, which owns its own transaction. A lock wait timeout (errno 1205) is not
+CRUD `createDocument`, `patchDocumentById`, `patchDocumentIfLockVersion` or
+`deleteDocumentById` given no `trx`, which owns its own transaction. A lock wait timeout (errno 1205) is not
 retried.
 
 Only the outermost transaction retries. A call given an existing `trx`, or a