# Upgrading qbit-assistant ## The assistant runs a process the signed-in person may run (Unreleased, UI API extension assistant 1.10.0) **After this upgrade, with nothing else changed, the assistant can run two kinds of process for a person who may run them themselves, once that person confirmed the run on a card: a table's own bulk edit and its bulk delete, on a table the assistant may already change for that person.** Every other process stays closed until the application's code names it on a reviewed list. No DDL changes. ### What a host should do before deploying 1. **Decide whether the two bulk actions should run.** They act on records of a table the person may change through the assistant already (one confirmed record at a time, until now). To keep them away: `AssistantQBitConfig.withDefaultProcessAccess(DataAccessMode.NONE)`, or `withProcessAccess("orders.bulkDelete", DataAccessMode.NONE)` for one, or `READ` on the table. 2. **To let the assistant run other processes, register a reviewed list.** Nothing else opens one: ```java new AssistantQBitConfig().withReviewedProcessesResource("assistant-runnable-processes.txt") // src/main/resources, one process name per line ``` Then add a test to the application that calls `RunnableProcessReview.assertReviewed(qInstance, person, Path.of("src/main/resources/assistant-runnable-processes.txt"))` (see the README, "Noticing drift"). Its first run fails and prints every process that could be run through the assistant. For each: accept it (its line goes in the file, which registers it) or say in code that the assistant stays away from it, so the test stops naming it: - a process of your own that a model should never drive (running SQL, restoring a backup, changing identity or permissions, acting on another person's work): `QPermissionRules.withDeniedClients(Set.of("assistant"))` on the process; - a process of a QBit you do not own: `ClientChannelsMetaData` (by name or pattern), or `AssistantQBitConfig.withProcessAccess(name, DataAccessMode.NONE)`. From then on the test fails whenever a process is added that nobody decided about, when a listed process is gone, and when the file is not the list the application registered. An unlisted process is not runnable in the meantime, with or without the test. 3. **Nothing to change for an administrator's rows.** A `PROCESS` row on Assistant > Data Access can only narrow: `NONE` (or `READ`) keeps the assistant from running that process. A `READ_WRITE` row opens nothing: not an unlisted process, and nothing the code or the person's permissions do not. ### What is never runnable through the assistant A process that is not on the application's reviewed list (except a table's own bulk edit and bulk delete); a process denied to the `assistant` channel; the assistant's own processes; a hidden process (except those two); a process no screen offers (in no app and on no table); a process on a table the assistant may not change; a process with a screen the assistant cannot present (a file upload, a required password, a download, a bulk-load form, a folder picker, a widget, custom content). The README has the list with its reasons. ### What a person sees The person asks; the assistant looks up the process and its inputs, asks for a required value it was not given (it never makes one up), and proposes the run. A card shows the process, every input, what the first screen says, the records (how many, of which table) and the steps that will stop for the person. Nothing runs until they confirm. A process that may run as a durable job is created as a job that waits for the person: they start it on its job record (core does not let the assistant start a job); where the application does not offer the operation that creates a job, such a process is not run through the assistant. Any other process runs until it ends or reaches a screen with something for the person that their card did not show (a review, a form, values to read, a text, a list of records): it stops, and going on takes a second card that shows what that screen shows. Four limits a person can meet: - **A field that cannot be set.** A screen's field whose name the process keeps for its own working (`ProcessControlNames`: the inputs of its backend steps, and the names QQQ's streamed and bulk steps use) is not an input through the assistant. The person is told; they set it in the application. A process of your own that declares a screen's field as an input of a backend step as well is affected: that field is set in the application. - **A filter over more than 500 records** is refused, for the person to narrow: the records of a run are fixed, by primary key, when it is proposed. - **An older card of the same run** is refused once the run moved on. - **A screen that lists records the assistant cannot show** (the application does not offer the operation that reads them, or they are of a table the assistant may not read) ends the run's way through the assistant there. **A released panel** draws the card as a record change (heading from the summary, one line per input, the button of an update), because it knows only the three record tools; the run works. The process card proper is the panel's package. ### Other changes in this release - **The write tools no longer say confirmation can be turned off.** The descriptions of `create_record`, `update_record` and `delete_record` ended "unless the administrator turned confirmation off". Tool descriptions are part of the cached request prefix: **the prefix changes once with this release** (one uncached request per conversation in flight), and again for a person who is offered the process tools. - **The routing classifier asks whether a spending limit is in force**, like every other model call. Without one it is not called and the heuristic chooses the route. Only a host whose limits are all scoped to single models or providers that do not include the classifier's notices a difference. - **Test connection stays available without a spending limit**, by decision, and is documented as the one exemption (README, "No answer without a spending limit"). - **Scheduled tasks**: `run_process` is offered to a scheduled task only with its write approval, like the record write tools. - UI API extension `assistant` 1.10.0: `AssistantActionV1` gains `processName` and `processLabel`, and `changes` carries the card's lines for a `process_run`. No operation changed. ### Java API - New: `tools.process.ProcessTools`, `ProcessToolFamily`, `ProcessRunnability`, `ProcessControlNames`, `RunnableProcessReview`; `ActionKinds.PROCESS_RUN`; `AssistantQBitConfig.withReviewedProcesses(Collection)`, `withReviewedProcessesResource(String)`, `getReviewedProcesses()` and `setReviewedProcesses(Set)`; `DataAccessService.forProcessInCode`, `forTableInCode` (what versioned code alone allows, with no administrator's row) and `reviewedProcesses()`. - `engine.ToolLabels.forModel(toolName, summary)` and `summaryIsData(toolName)`, `MessageParts.addToolText(toolName, text)` and `modelText()`: the summary of a process step, and the thread's message about a confirmed run, are told to a model inside the data envelope. A text part of a message may now carry `source` (the tool whose outcome it repeats); a panel shows it as any text. ## Writes follow the signed-in person; the assistant needs a spending limit (Unreleased) **After this upgrade the assistant proposes changes on every table the signed-in person may change themselves, with no settings row, and it refuses to answer anybody for whom no spending limit is in force.** Both are owner decisions of 2026-11-12. Every change still waits for the person's confirmation card, runs as that person through the UI API, and is refused there, with the screen's own message, when they may not make it. No DDL changes. ### What a host must apply 1. **Include the migration changeset** in the master changelog, once, after the assistant's tables: ```yaml - include: { file: db/liquibase/qbit-assistant/assistant-data-access-follow-user.changelog.sql } ``` It deletes the rows of `assistant_data_access` that the retired table action "Add rows for every table" wrote and nobody changed since: type `TABLE`, mode `READ`, the action's fixed note, and a modify date less than one second after the create date. It touches no other row: not a row an administrator wrote or changed, not a `NONE` or `READ_WRITE` row, not a `PROCESS` row. Its rollback is empty. A host that never ran that action has nothing to remove and may still include it. A host with its own migration tool runs the one `DELETE` of that file. Without the changeset nothing breaks: each of those rows now reads as a restriction, and the assistant stays read-only on that table until the row is deleted. **Before upgrading, look at the rows the changeset will remove. A table that an administrator deliberately left read-only for the assistant by running "Add rows for every table" and never editing its row becomes writable through the assistant after the upgrade** (for the people who may change it themselves, each change on a confirmation card): the changeset cannot tell such a row from one nobody meant. This query, which has the changeset's own predicate, shows them. Run it in every environment before the changeset runs: ```sql SELECT object_name, mode, notes, create_date, modify_date FROM assistant_data_access WHERE object_type = 'TABLE' AND mode = 'READ' AND notes = 'Added by ''Add rows for every table'': the assistant''s default for this table. The user''s own permissions still apply.' AND create_date IS NOT NULL AND modify_date IS NOT NULL AND modify_date < create_date + INTERVAL '1' SECOND ORDER BY object_name; ``` To keep a table read-only for the assistant, edit its row on Assistant > Data Access before upgrading: change its note to one of your own and save. An edited row is an administrator's row; the changeset leaves it, and after the upgrade it reads as the restriction you meant. A row the query does not show is not touched. 2. **Review the rows that remain** on Assistant > Data Access in every environment, before deploying. A row no longer opens anything. What each row means now: | Row | Before | After | |---|---|---| | none | the assistant may read the table | the assistant may read it and propose what the person may change | | `READ` | the same as no row | **a restriction**: the assistant never proposes a change to this table | | `NONE` | the assistant never sees the table | unchanged | | `READ_WRITE` | the assistant may propose changes to this table | no restriction, the same as no row: delete it or keep it | Which rows exist in a deployed database cannot be read from code; an administrator has to look. 3. **Make sure a spending limit is in force**, or the assistant refuses every question after the upgrade. One is, when a budget row on Assistant > Budgets is switched on, has a limit above zero and applies to the person (a whole-instance budget applies to everybody), or when the code configuration or the policy row declares a hard limit above zero (`AssistantBudgets` user daily or instance monthly). The starter defaults changelog seeds a monthly whole-instance budget on a host that had no budget; a host that deleted or switched off its budgets, or never included the starter defaults and declares no hard limit, must add one. The Setup card's Budgets line says so. ### What changes for administrators - **Data Access rows only restrict.** Add a row to make a table read-only for the assistant (`READ`) or to hide it (`NONE`). There is no longer a way to open a table from that screen, because nothing needs opening: the assistant follows each person's own permissions. The mode's help text and the Data access card on the Overview say what decided for each table ("default", "pinned in code", "administrator setting", "sensitive table"). - **The table action "Add rows for every table" is gone.** The Data access card shows the effective access of every table, and its source, without storing anything. - **People who may change a table are offered the write tools at once**, on every table they may change. A person who may only read is not offered them. Tell the people who use the assistant: the card is the moment to check. - **With no budget in force the assistant says so and stops**: "The assistant is not answering because no spending limit is in force. An administrator must set or switch on a budget (Assistant > Budgets) before it can be used." Switching a budget back on restores it with the next question. A budget that is switched off, or whose limit is zero, does not count. A temporary "unlimited until" override does not take a budget out of force: it is a dated exception to a budget that stays in place. - **Scheduled tasks** are refused the same way, and the run's error is that sentence. - **The retention process** now ends a confirmed change that was left running for more than an hour as failed, "Outcome unknown: ... Check the record before asking for it again.", with a tool-call row. Such an action could not be confirmed again before either; it is now also removed after `approvalRetentionDays` like any other. - The assistant's own tables can never be opened to the assistant, by a row or by code. ### Keeping the assistant read-only, or opening single tables In the application's configuration class, not in the database: ```java config.withDefaultTableAccess(DataAccessMode.READ) // the assistant proposes no change anywhere ... .withTableAccess("orders", DataAccessMode.READ_WRITE) // ... except where the code says so .withTableAccess("payroll", DataAccessMode.NONE) // never shown to the assistant, whoever asks .withDefaultProcessAccess(DataAccessMode.NONE); // no process, when the process tools arrive ``` A pin replaces the default for its object. An administrator's row can lower a pin or the default and can never raise either: with `withDefaultTableAccess(READ)` a `READ_WRITE` row does nothing. ### Java API, for a host or another QBit that called these directly - `SignedInPerson.ofSession(qInstance, session)` returns a person whose `session()` is the session the authentication module resolved, not the object passed in. Code that put permissions, security keys or values on its own session object and expected the assistant to see them must put them where the authentication module does (its customizer). The time zone value is carried over. - `UiApiToolbox.Context.forRead(sessionUUID, timezone, gateway, policy, credentials, turnId)` is gone. `runtime.getToolCalls().readContext(person, timeout)` makes the context of one of the assistant's own reads, for a signed-in person, and throws `QException` when the person has no assistant access or the kill switch is on. - `StarterPrompts.forUser(person, policy, configured, historyOffered)` is gone; `forUser(context, userId, configured, historyOffered)` takes a context from `readContext`. `new StarterPrompts(toolbox, clock)` no longer takes a gateway. - `AssistantStore.expirePendingAction(id)` is `expirePendingAction(userId, id, now)` and returns whether it expired the action; `decidePendingAction` is final. - `UiApiToolbox.definitions(policy, boolean)` is `definitions(policy, Set writableTables)`; `UiApiToolbox.anyWritableTable()` is gone (`DataAccessService.anyWritableTable()` still says whether any table's data access allows writes, for nobody in particular). `new BulkLoadToolFamily(bulkLoadTools)` takes one argument. - `AssistantRetentionStep.Result` has an eighth component, `pendingActionsFailed`; `purge(runtime, now)` is the whole run, `purge(config, store, now)` everything but ending the actions left running. - `processes.DataAccessDefaultsProcess` is gone. - The test-jar of `qbit-assistant` holds the `testing` package only. A project that used `RuntimeInternals`, `ToolCallServiceInternals` or `Toolboxes` from it (none of the provider modules did) keeps its own copy in its own test sources, inside the assistant's package it reaches into; they were never an API. - A host's own `ToolFamily` and its tools compile unchanged. A host's tool that proposes a change is offered as before; it decides its own offer in `definition(ToolOffer)`. ### An existing test's expectation that changed `ChatToolSetTest` compares the chat's tool list with a file written before the tool registry existed. No definition changed and no line of the file changed. What changed is who is offered the write tools: the four "everything" scenarios now ask as a person who may change tables (with no settings row; they used to ask as a person who may only read, with `READ_WRITE` rows), and the scenario of a person who may not save an analysis lost its `save_analysis` line. ## One decision per pending action, a closed tool surface, cards with before and after (Unreleased, UI API extension assistant 1.9.0) **Apply the "Pending actions" block at the end of `docs/schema-postgres.sql` before deploying.** It is guarded and safe to re-run. It adds: - `assistant_pending_action.action_kind VARCHAR(64)`, `before_json TEXT`, `record_version VARCHAR(64)` (all nullable); - two indexes on `assistant_pending_action`: `(user_id, status)` and `(create_date)`; - the table `assistant_pending_action_claim` (`id`, `pending_action_id` NOT NULL with a cascading foreign key to `assistant_pending_action`, `user_id`, `decision`, `create_date`), with **`UNIQUE (pending_action_id)`** and an index on `user_id`. The unique key is what makes a confirmation run once across servers. A host that maps table or column names with a table customizer maps the new table and columns the same way; a host with its own migration tool copies the block into it. Without the block, proposing and confirming fail (the columns and the table are written on every proposal and decision). What a host may notice: - A proposal made before the upgrade and confirmed after it: an update or a delete is refused as changed (it kept no version of the record) and the user asks again; a create runs. Proposals live 15 minutes by default. - `update_record` and `delete_record` now read the record (`GET /table/{tableName}/{primaryKey}`, as the user) when they propose and again when the user confirms. A record the user cannot read is refused at proposal time with that operation's answer. - Confirming an update or a delete of a record that changed in the meantime fails with "This record changed after the change was proposed. Nothing was changed." - `assistantRetention` now deletes decided and lapsed pending actions older than `approvalRetentionDays` (default 365). The setting was documented and never read; check its value before the first run after the upgrade. - New operation `GET /qqq/v1/assistant/actions`; `AssistantActionV1` has new optional fields (`actionKind`, `conversationId`, `createdAt`, `decidedAt`, `tableLabel`, `recordHref`, `changes`, `before`). A released panel keeps working: `toolName` and the existing fields are unchanged. - The input kept in `assistant_tool_call.input_json` is now also redacted with `customRedactionPatterns`. - A request that carries several credentials (a session cookie and an `Authorization` header, say) has only the one its session was resolved from forwarded to the UI API. Java API, for a host or another QBit that called these directly: - `SignedInPerson.ofSession(session)` is now `SignedInPerson.ofSession(qInstance, session)`. It asks the authentication module to resolve the session's own id and throws `IllegalArgumentException` when that is not the user the session names. - `new AssistantApi(runtime, session)` still exists and still serves the user's own conversations. It starts a turn, confirms or cancels an action, and explains access only after the same check, and answers 403 when the check fails. - Gone from the public surface: `AssistantRuntime.getToolRegistry()`, `getUiApiGateway()` and `ownToolFamilies()`; `ToolCallService.getRegistry()`; `ToolCallService.execute` and `log` (use `executeAndLog`); the public constructors of `ToolCallRequest`, `ConfirmedToolCall` and `UiApiToolbox.Context`, which are now final classes with the same accessors (a context for one of the assistant's own reads is `UiApiToolbox.Context.forRead(...)`). `new ToolCallService(runtime, registry, store)` takes the gateway as a fourth argument. - `AccessExplainer.explain(...)` has an overload without the gateway argument; `RagService` and `StarterPrompts` are handed the gateway by the runtime. - `UiApiToolbox.ProposedWrite` has three more components (`kind`, `before`, `recordVersion`); the seven-argument constructor still exists. `AssistantRetentionStep.Result` has a seventh component, `pendingActionsDeleted`. - A host's own `ToolFamily` and its tools compile unchanged (they read a request through its accessors and never constructed one). ## Every write waits for confirmation; the tool-call service owns the policy and the identity (Unreleased) No schema change and nothing to apply to the database. What a host may notice: - **Writes require confirmation** on the `assistant_policy` row no longer does anything: every create, update or delete the assistant proposes waits for the user's confirmation card. The column `writes_require_confirmation` stays in place and is not read. A host that had switched it off gets the card again. - `AssistantQBitConfig.withToolFamily` throws when it is called after the QBit was produced (it was ignored). Register tool families before producing it. - Java API, for a host that called these directly: `AssistantApi.withCredentials` is gone (`new AssistantApi(runtime, session)` is unchanged; a route uses `new AssistantApi(runtime, SignedInPerson.ofRequest(context))`); `AssistantRuntime.getToolbox()`, `getKnowledgeTool()` and `getBulkLoadTools()` are gone; `PolicyService.ToolPolicy` has three components (`allowedTools`, `maxRowsPerCall`, `redactPii`); `ToolCallScope.clientChannel()` is gone. A host's own `ToolFamily` and its tools compile unchanged. ## Conversation management (Unreleased, UI API extension assistant 1.6.0) No schema change. `assistant_conversation` is now usable by every user holding `assistant.hasAccess` (not only `assistant.admin`), together with three new record actions (Archive, Restore and Delete conversations). Rows stay locked to their owner. A user's table queries only return their own rows if their session carries their owner key: call `AssistantSecurity.applySessionKeys` from the authentication customizer for **every** user, not only for admins. Without it, non-admin users see an empty table. The panel can link to the table using `conversationsTable` from `GET /config`. That field is present only when the user may query the table. ## Starter prompts follow the user's access (Unreleased) `GET /assistant/config` no longer returns the profile's starter prompts as written. `profile.starterPrompts` (same field, still `string[]`) is now built per user: - Up to three prompts are generated from the tables the signed-in user can read through the assistant and that have rows (a count as the user), using the table labels, a date field when present, and "What changed in ... this week?" when the change-history tool is offered. The pick is stable for the user for the day and rechecked on every request, including table, row and field access. Generation uses bounded UI API calls and no model calls. Any failure yields no generated prompts. - A configured starter prompt (Assistant Profile > Starter prompts, one per line) is shown only when it declares the tables it needs and the user can read all of them. Declare them with a leading tag: `[blog_post] Which posts are drafts?`, or `[blog_post, page] ...` for several. `[none] What can you help with?` names no table and is always shown. A line without a tag is no longer shown, because nothing says which tables it mentions: add a tag to keep it. - Shown prompts are the permitted configured ones first, then generated ones, three in all (a profile with three or more permitted prompts shows only those). No schema change and no configuration. The panel needs no change. ## Chat turns are not jobs (Unreleased) Ordinary chat turns no longer create core tracking jobs, so they no longer appear in the Jobs tray or the Jobs tables and no longer trigger a per-answer "finished" notification. No schema change and no configuration is needed. The `AssistantRunTracker` SPI and `JobTrackingRunTracker` are removed, along with `AssistantQBitConfig.withRunTracker`, `setRunTracker` and `getRunTracker`. A host that called any of them must delete the call: `withRunTracker(AssistantRunTracker.NOOP)` is now the only behavior, and a custom tracker has no replacement hook. Turn progress, Stop and recovery are available through the assistant's own routes (`GET /turns/active`, the turn events stream and `POST /turns/{id}/cancel`). Bulk loads the assistant launches are still durable jobs. Their confirmed tool result now includes `jobHref` (the job's in-app link) and the confirm response's `href` points at the job. Scheduled task notifications now use core `QAlerts.notify`; they reach whatever alerts sink the host installed (or core's logging sink when none is). ## Provider setup state (Unreleased) Apply the **Provider setup state** block at the end of `docs/schema-postgres.sql` **before** deploying: the provider table now reads `setup_state`, so the new jar fails on `assistant_provider` without it. It adds a nullable `VARCHAR(16)` with default `'ACTIVE'` and a check for `ACTIVE` / `SETTING_UP`; existing rows behave as before. It is `IF NOT EXISTS` and safe to re-run. To stop an unfinished provider from being routed to or health-checked, edit it in Assistant > Assistant Provider (Provider section) and set **Setup state** to **Setting up** (SQL: `UPDATE assistant_provider SET setup_state = 'SETTING_UP' WHERE id = ;`). Enabled providers that are neither the default nor the only route for a configured model now report DEGRADED, not DOWN, when unreachable. No configuration change. ## Fail soft (Unreleased, UI API extension assistant 1.5.0) Apply the **Fail soft** block at the end of `docs/schema-postgres.sql` before deploying. It creates `assistant_client_error` (errors the panel reports through `POST /qqq/v1/assistant/client-errors`) with its indexes and `SET NULL` foreign keys to the conversation, message and turn. It is `IF NOT EXISTS` and safe to re-run. New configuration, all optional: `toolCallTimeoutSeconds` (default 60), `clientErrorsPerUserPerMinute` (default 30) and `clientErrorWarnPerHour` (default 20, when the `assistant.client-errors` health check turns degraded). The new table is in the Assistant app's nav for administrators. ## Transcript redaction (Unreleased) Apply the transcript-redaction column widening block in `docs/schema-postgres.sql` to existing databases. Stop reasons, request IDs, tool-call IDs, feedback/data-audit/ budget-override reasons and scheduled-run summaries/errors now use `TEXT`; token expansion must not fail a write or truncate secured-data tokens. The corresponding entity field limits are removed, including pending-action and tool-result summaries. ## Foreign keys (2026-10-14) Recommended: apply the "Foreign keys" block at the end of `docs/schema-postgres.sql` (after the index audit). It is guarded and safe to re-run. - Adds the missing foreign keys across the conversation tables, usage, data audit, budget accounting and profile skills, with the indexes they need. - Detail rows of a conversation `CASCADE`; the message/turn cycle, usage and the data audit use `SET NULL`, so usage keeps its cost rows when a conversation is deleted. - Usage, budget accounting and the data audit hold their provider (`NO ACTION`): disable a provider with history instead of deleting it. - `assistant_model.provider_id` changes from `NO ACTION` to `CASCADE` (constraint renamed `fk_assistant_model_provider`). - Rows that point at a missing parent are first copied to `qqq_fk_quarantine` (created if absent), then nulled, or deleted for the `NOT NULL` profile-skill links. Check that table after the upgrade. No code change. ## Index audit (2026-10-14) Recommended, not required: apply the "Index audit" block at the end of `docs/schema-postgres.sql`. It adds six indexes, every one `IF NOT EXISTS`: - usage by turn (read on each scheduled run) - the three retention date filters (turn events, tool calls, inactive conversations) - the two `ON DELETE SET NULL` foreign keys on `assistant_scheduled_run` No code change. ## Durable turns (Unreleased) Apply the **Durable turns** block at the end of `docs/schema-postgres.sql` before starting the new runtime. It adds nullable `heartbeat_at`, `lease_owner`, `cancel_requested_at`, `phase`, `concurrency_mode` and the `(user_id, status)` index. A partial unique index on terminal events also prevents two replicas from inserting separate `message.end` frames for the same turn. Check for historical duplicate terminal frames before applying it (resolve any duplicates through your normal migration process). Fresh installs run the full schema, including ALTERs. Existing rows with no heartbeat use `started_at` for lease expiry. During the first upgrade from a runtime without heartbeats, drain old replicas' turns first: a new replica cannot distinguish an old live turn from a dead owner after 45 s. Defaults: heartbeat 5 s, lease 45 s, hard duration 300 s, force-finalization grace 20 s, shutdown grace 8 s. Configure these through the corresponding `AssistantQBitConfig` withers. Heartbeat must be shorter than the lease. The JVM shutdown hook is enabled by default; tests disable `registerShutdownHook` and managed hosts may call `runtime.shutdown(Duration)` themselves. Give the process termination budget enough time for the configured shutdown grace and persistence. `POST /conversations/{id}/turns` accepts `concurrency: "supersede" | "concurrent"` (case-insensitive). Default `SUPERSEDE` stops prior runs in that conversation; `CONCURRENT` permits them. The default per-user cap is now 3; reaching it stops the oldest run instead of returning the old in-progress 429. Per-minute and budget 429 responses still apply. Superseded turns record `cancelReason=SUPERSEDED`. Cancel now returns HTTP **200**, including for terminal turns, with the current `status`. The OpenAPI fragment retains the old 202 response for mixed-version rollouts. Active runs are discoverable through `GET /qqq/v1/assistant/turns/active`; reattach through the existing events route. Consumers should recognize `turn.phase` and `message.start.startedAt`. Starts during shutdown return 503 `SHUTTING_DOWN`; clients may retry against a ready replica. `JobTrackingRunTracker` is now the default `AssistantRunTracker`, using core `JobTracking` in QQQ **4.1.0-RC.8** to publish answers in the Jobs tray. The host must provide the jobs tables (through qbit-jobs / core `DurableJobsMetaDataProvider`) and run `DurableJobsRuntime`. Without that runtime, answers complete normally and are simply not tracked. Each job is owned by the assistant user, links to its `assistant_conversation`, and reports thinking, tool and writing phases. Tool progress contains only the tool label; terminal messages are fixed and never contain prompts or answers. The tray's Stop cancels the assistant turn. All tracker callbacks remain isolated from turn execution. Opt out with `withRunTracker(AssistantRunTracker.NOOP)`; hosts may still supply their own `AssistantRunTracker`. ## Starter defaults, setup card and table help The jar now ships `db/liquibase/qbit-assistant/assistant-defaults.changelog.sql`. Include it from the host's master changelog **after** the changesets that create the `assistant_*` tables: ```yaml - include: { file: db/liquibase/qbit-assistant/assistant-defaults.changelog.sql } ``` It is insert-only and never changes a host that already configured the assistant: the policy, the **$50/month instance budget** (warn 80%, downgrade 100%, stop 120%) and the Anthropic list prices are seeded only into empty tables, and the `default` profile only when no default profile exists. Price rows take precedence over `AssistantQBitConfig.withPricing`, which is why they are seeded only when there are none. The four starter skills and a disabled example scheduled task are always added (by name); on a host with its own default profile the skills are not linked to it, and the Setup card says so. Requires Liquibase 4.x or later (preconditions are `sql-check`s). No DDL changes. New: the Assistant home's Setup card, the `assistant_data_access` table action **Add rows for every table** (`assistantDataAccessAddDefaults`, admin only) and bundle help on every assistant table (`help/qbit-assistant.yaml`). ## X1/Y1: channel wall and audit attribution Requires QQQ 4.1.0-RC.6. Every assistant table, process, report and widget is explicitly denied to channel `assistant`; startup rejects an exposed object. Host customizations must preserve these denials. Administration uses `next-ui`. Before enabling `AuditsMetaDataProvider.withClientChannelField(true)`, add the nullable `audit.client_channel VARCHAR(100)` column using the host migration conventions. kof22 needs a feature changeset under `changesets/features/` (for example `2026-10-14-audit-client-channel.sql`); no host migration is applied here. Existing audit rows remain null. The test fixture enables the field. The existing `assistant_tool_call.auditHref` column now points to audit rows filtered by record, table and client channel, including for deletes. It is empty when the host has not enabled the audit channel field. Apply the X1/Y1 DDL in `docs/schema-postgres.sql` to widen the existing `assistant_tool_call.audit_href` column to TEXT: encoded filters with long table names or string record ids can exceed the old 500-character limit. No new QBit column is required. `GET /assistant/access` accepts an optional owned `turnId` for attribution. ## Provider API extraction (#30) **BREAKING:** every provider API type now lives in the exclusive package `com.kingsrook.qbits.assistant.spi`. Update imports and recompile consumers. Hosts still receive `qbit-assistant-provider-api` transitively from `qbit-assistant`. No schema migration is needed. | Old import | New import | |---|---| | `com.kingsrook.qbits.assistant.provider.X` (API types) | `com.kingsrook.qbits.assistant.spi.X` | | `com.kingsrook.qbits.assistant.engine.ModelPricing` | `com.kingsrook.qbits.assistant.spi.ModelPricing` | Internal classes such as `provider.RegistryModelProvider` and `provider.fake.ScriptedModelProvider` stay in the runtime and are not API types. External consumers such as qbit-marketing depend only on `com.kingsrook.qbits:qbit-assistant-provider-api` for these contracts and allow package `com.kingsrook.qbits.assistant.spi` in their guardrails. qbit-bom will add this package to the G1 defaults. External providers and applications using only provider/pricing types should replace their `qbit-assistant` dependency with `com.kingsrook.qbits:qbit-assistant-provider-api` at the same version. This removes the assistant runtime and QQQ from that dependency path; only Jackson annotations are required by the API. Anthropic, OpenAI, Bedrock and Vertex adapters use this split; pgvector retains `qbit-assistant` for its runtime RAG interfaces. Recompile custom provider types that override `validate(AssistantProvider)` and change the signature to `validate(ProviderSettings)`. The settings carry the configured kind, URL, API version, region, project, CA bundle name, timeouts and `apiKeyEnvName`; the key and bearer-token supplier are not resolved for validation. Providers using the default validator need only the import migration. Keep the runtime and provider artifacts on the same version; old validator overrides must be rebuilt. ## P-g: scheduled tasks Apply the **P-g** DDL in [docs/schema-postgres.sql](docs/schema-postgres.sql) before deploying. The unique `(task_id, scheduled_for)` constraint is required for multi-replica safety; retain run rows as schedule-slot claim history. Existing conversations default to channel `panel`. Tasks start disabled. Set `withScheduledTasksSchedulerName(...)` to an existing QQQ scheduler and configure `withUiApiBaseUrl(...)` with this replica's own listener URL. The runner polls every 60 seconds. QQQ must supply a scheduler session able to manage the assistant tables; this QBit never creates that session. The configured backend must enforce unique keys atomically (Postgres does). Allow only designated credential references with `withAllowedScheduledCredentialEnvNames(Set.of("ASSISTANT_SCHEDULED_TOKEN"))`. Provide that variable through the host's secret manager. It must hold a token accepted by the host's `manageSession` authentication provider for `runAsUserId`. The runner fails closed on missing/disallowed credentials or an identity mismatch. See [scheduled-task setup](README.md#scheduled-tasks) for kof22 provisioning. QQQ RC.5 has no conditional UpdateInput. The runner uses a database-unique schedule-slot insertion as its optimistic claim, then advances `nextRunAt` before starting work. Crashes can skip a slot; they never retry it. No ArchUnit exception or fabricated session is introduced. Core RC.6 enforces client-channel denials; scheduled requests carry `assistant/scheduled/`. Notifications use the optional Alerts QBit notification SPI with a single-user audience. Without it, delivery logs run id/status only. All output modes retain the owner-locked audit row and conversation. HIPAA run summaries never copy the answer; they contain only `see conversation`. ## P-f: knowledge retrieval Apply the **P-f** assistant-table DDL in [docs/schema-postgres.sql](docs/schema-postgres.sql) before deployment. It adds `assistant_model.model_kind` (existing rows default to CHAT), `embedding_dimensions`, and the admin-only `assistant_rag_source` table. No sources are seeded. Existing chat selections remain unchanged; explicitly EMBEDDING models are excluded from chat, classifier, fallback and downgrade selection. Correct discovery's kind/dimensions if a model name is ambiguous. For persistent vectors, add `qbit-assistant-rag-pgvector` at the same version as the QBit, supply the host's JDBC DataSource/driver, and install pgvector in the database. A DBA runs `CREATE EXTENSION IF NOT EXISTS vector`; the application role needs schema creation rights for initial setup (or a DBA-created schema), then normal DML rights. `ensureSchema()` checks for an existing extension first and does not require extension installation privileges when it is already present. The optional pgvector DDL is a **commented reference block**, separate from the assistant-table migration. See [RAG setup](README.md#rag-setup). Use a distinct validated schema for each QQQ instance. `vector(N)` fixes dimensions for that store; changing dimensions requires a new schema and re-indexing. Sources can use different models with that dimension; ranking is restricted to sources using the query's model. If the weights behind an unchanged model id change, clear and rebuild its sources. Editing source chunk/filter/model settings or registry model identity/dimensions automatically clears affected vectors. Every indexing batch produces EMBED usage and updates existing budget rollups. PHI source content and PHI conversation queries require a HIPAA-eligible embedding provider. No background runner or designated credentials are installed in P-f. The default in-memory store is lost on restart and must be indexed again. ## P-e: profile routing and provider fallback Apply the additive **P-e** ALTER TABLE statements at the end of [docs/schema-postgres.sql](docs/schema-postgres.sql) before deploying. Existing profiles default to OFF; optional model references and health columns start null. No routing or fallback configuration is seeded. Existing turns retain unknown routing/final-provider values; fallback_count defaults to zero. Profiles now have a **Model routing** section. Select HEURISTIC or CLASSIFIER, then optional simple/complex registry models and a classifier model. Empty route slots retain provider/policy selection. CLASSIFIER with no usable classifier uses HEURISTIC. OFF preserves prior provider selection. With no effective profile, code-configured escalation supplies the complex model/effort when enabled. Set a model's **Fallback model** to opt into a cross-provider chain. Saves reject cycles, more than four edges, or disabled/missing targets. Provider health is read-only; NETWORK/TIMEOUT opens a 60-second circuit, and successful calls close it. Local endpoints with stale health get a bounded two-second probe. Automatic fallback without an explicit link is confined to local models of the same adapter family. PHI/HIPAA eligibility and budgets apply to every destination. Classifier usage is recorded with purpose ROUTE and included in budgets. Reports that filter usage purpose should include ROUTE. Turn screens show route decision, source, fallback count and final provider; the home shows health and fallback totals. All configuration remains assistant.admin-only, with AI exposure NONE. ## P-d: data-driven budgets Requires QQQ 4.1.0-RC.5 for the core Alerts API and alert type metadata. Create `assistant_budget`, `assistant_budget_override`, `assistant_budget_event` and `assistant_budget_usage` using the P-d DDL in [schema-postgres.sql](docs/schema-postgres.sql) before deploying. The event unique key is required: it deduplicates each state per budget, scope and UTC period across replicas. Do not remove it or truncate events during a period. Budgets appear in Assistant navigation. Overrides and immutable events are child lists. All four tables require `assistant.admin` and have AI exposure NONE. Overrides record the actual session grantor and require a reason and expiry. The standard host QQQ audit configuration applies to budget and override edits. `assistant_budget_usage` is a private accounting projection populated from persisted usage writes. It copies only counters, time, user, provider and model, with no owner lock, so shared INSTANCE/PROVIDER/MODEL sums can run under the caller's own session. The source usage table retains its owner locks. The projection is read-only, has no nav entry and no AI exposure. **Pause usage writes during migration and run the DDL's backfill before restarting**; otherwise shared totals would omit pre-upgrade usage. Keep accounting rows through their budget periods even if detail rows are removed. ROLE budgets give each permission holder a separate allowance, checked with their current session. Override scopeValue, when set, narrows the allowance to one user id. Existing policy/config budgets and provider monthly caps remain additional limits; an override of a budget row does not waive those existing caps. Provider and MODEL scope values are numeric provider/model registry row ids; USER is a user id and ROLE is a permission name. INSTANCE has no scope value. Periods reset at midnight UTC or the first of the month UTC. Token usage includes input, output, cache-read and cache-write tokens; USD uses the recorded micro-dollar cost, not today's model price. No default budget rows are seeded. ## P-c: classification, PHI routing and encrypted storage Apply these additive schema changes before deploying P-c (adjust column mappings for your backend). New conversations/turns record `PUBLIC`, `CONFIDENTIAL`, `PII` or `PHI`; legacy null classifications read as PUBLIC. Backfill known historical PHI conversations to PHI before allowing their history to be used with a provider. ```sql ALTER TABLE assistant_conversation ADD COLUMN max_classification VARCHAR(16); ALTER TABLE assistant_turn ADD COLUMN classification VARCHAR(16); ALTER TABLE assistant_turn ADD COLUMN classification_tables VARCHAR(500); ALTER TABLE assistant_conversation ALTER COLUMN title TYPE TEXT; ALTER TABLE assistant_tool_call ALTER COLUMN result_summary TYPE TEXT; ALTER TABLE assistant_pending_action ALTER COLUMN summary TYPE TEXT; ALTER TABLE assistant_pending_action ALTER COLUMN result_summary TYPE TEXT; CREATE TABLE assistant_data_audit ( id SERIAL PRIMARY KEY, user_id VARCHAR(255), conversation_id INTEGER, turn_id INTEGER, provider_id INTEGER, provider_name VARCHAR(200), model VARCHAR(200), hipaa_eligible BOOLEAN, classification VARCHAR(16), tables VARCHAR(500), decision VARCHAR(16), reason VARCHAR(1000), create_date TIMESTAMP WITH TIME ZONE ); CREATE INDEX assistant_data_audit_user_id ON assistant_data_audit (user_id); CREATE INDEX assistant_data_audit_conversation_id ON assistant_data_audit (conversation_id); CREATE INDEX assistant_data_audit_turn_id ON assistant_data_audit (turn_id); ``` `assistant_data_audit` is an admin read-only, owner-locked child list on a conversation, outside navigation. It records each model call carrying PII/PHI and each routing block, without record values. It expires with the conversation. PHI conversations use `hipaaRetentionDays` (2190 by default), even outside HIPAA mode; null uses normal retention. Existing tool-result/replay cleanup still uses `toolResultRetentionDays`. Before enabling HIPAA mode, mark the permitted provider rows `hipaaEligible = true` and provision `conversationEncryptionKeyEnvName` with a base64-encoded 32-byte key. Startup refuses missing or invalid keys. A code-only provider is not eligible. The flag records the operator's eligibility decision; it does not establish a BAA. New/updated message parts, titles, conversation context, tool payloads/redactions and summaries, replay data, and pending-action payloads/summaries use `enc:v1:` (AES-256-GCM, random 12-byte IV, 16-byte tag). Only `AssistantStore` decrypts; direct backend/admin record views show ciphertext. String columns holding encrypted summaries/titles must be TEXT to allow expansion. Legacy plaintext reads are supported; existing rows are not automatically rewritten. For an existing deployment, migrate legacy payloads through AssistantStore under the appropriate owner/admin session before treating the whole archive as encrypted. Keep the key available for the lifetime of encrypted data and backups. Changing the key requires a controlled decrypt/re-encrypt migration; P-c has no key rotation job. Corrupt ciphertext, a wrong key, and encrypted data without a key fail closed. ## 0.1.0-RC.3 to 0.1.0-RC.4: provider settings, prices, per-call usage, app home Three new tables. Create them before you deploy (see `docs/schema-postgres.sql`, which also seeds the Anthropic prices): - `assistant_provider` (with the `api_key_status` column: it is filled on read and never written, but the backend selects it) - `assistant_model_price` - `assistant_usage` Then, to keep answering exactly as before: 1. Register the provider type: `config.withProviderType(new AnthropicProviderType())`. Keep `withModelProvider(AnthropicModelProvider.fromEnvironment())` as the fallback. 2. Add one provider row (or seed it in your migration): type `anthropic`, model = your current main model, enabled, default, `apiKeyEnvName` = `ANTHROPIC_API_KEY` (or leave it empty for the default). No key value is ever written. 3. Run **Test connection** on it. Until a row exists, the provider registered in code answers, as in RC.3. Other changes: the app label is **Assistant**; the nav no longer lists the retention process (it is a table action on conversations) or the audit tables (they are child lists). Grants on `assistant.admin` cover everything new. ## 0.1.0-RC.1 to 0.1.0-RC.3: snake_case names The rename shipped in 0.1.0-RC.3. 0.1.0-RC.2 on Maven Central is an accidental republish of the RC.1 code (see CHANGELOG.md), so upgrading from RC.2 is the same as upgrading from RC.1. RC.3 applies the QRun-IO naming rule (owner decision, 2026-10-12): *"table names should always be lowercase and use _, and qbits should always be prefixed with their name"*. The QQQ table names, the owner security key type and the possible-value source change. Permissions do not. **This is a metadata-only change**: no table, column or index in your database changes, and no Liquibase or DDL step is needed. ### What changed | Kind | RC.1 (and RC.2) name | RC.3 name | |---|---|---| | Table | `assistantConversation` | `assistant_conversation` | | Table | `assistantMessage` | `assistant_message` | | Table | `assistantTurn` | `assistant_turn` | | Table | `assistantTurnEvent` | `assistant_turn_event` | | Table | `assistantToolCall` | `assistant_tool_call` | | Table | `assistantFeedback` | `assistant_feedback` | | Table | `assistantPolicy` | `assistant_policy` | | Table | `assistantUsageDaily` | `assistant_usage_daily` | | Possible-value source (conversations) | `assistantConversation` | `assistant_conversation` | | Permissions | `assistant.hasAccess`, `assistant.admin` | unchanged (QQQ's standard `.hasAccess` suffix; the `assistant` base already follows the rule) | | Security key type | `assistantUserId` | `assistant_user_id` | | All-access key | `assistantUserIdAllAccess` | `assistant_user_id_all_access` | Unchanged: Java class names, field names (`userId`, `conversationId`, ...), the `assistantAdmin` app, the `assistantRetention` process, the `/qqq/v1/assistant` routes and the `assistant` supplemental instance meta-data. The old names stay available as `@Deprecated` constants for one release, so migration code can refer to them: `.LEGACY_TABLE_NAME`, `AssistantQBitConfig.LEGACY_DEFAULT_OWNER_KEY_TYPE` and `AssistantMetaDataBuilder.LEGACY_ALL_ACCESS_SUFFIX`. They will be removed in 0.2.0. ### Physical tables `docs/schema-postgres.sql` already creates `assistant_*` tables. If your RDBMS backend mapped the old QQQ names to those tables (for example with `inferBackendName`), the new QQQ names now equal the physical names and nothing else is needed; the mapping becomes a no-op. If you created tables literally named `assistantConversation` and so on, either rename them: ```sql ALTER TABLE "assistantConversation" RENAME TO assistant_conversation; ALTER TABLE "assistantMessage" RENAME TO assistant_message; ALTER TABLE "assistantTurn" RENAME TO assistant_turn; ALTER TABLE "assistantTurnEvent" RENAME TO assistant_turn_event; ALTER TABLE "assistantToolCall" RENAME TO assistant_tool_call; ALTER TABLE "assistantFeedback" RENAME TO assistant_feedback; ALTER TABLE "assistantPolicy" RENAME TO assistant_policy; ALTER TABLE "assistantUsageDaily" RENAME TO assistant_usage_daily; ``` or keep them and set `RDBMSTableBackendDetails.tableName` to the old name in your table customizer. ### Stored references to update QQQ stores table names, permission names and key names outside this qbit. Update them in the same deployment. The examples are for Postgres with QQQ's default snake_case backend names; adjust the table and column names to your schema. 1. **Security keys.** Permission grants (`assistant.hasAccess`, `assistant.admin`) need no change. If your authentication customizer grants the all-access key itself rather than calling `AssistantSecurity.applySessionKeys`, grant `assistant_user_id_all_access`. If you set `ownerSecurityKeyType` explicitly, the all-access key is now `_all_access`. 2. **Saved views and saved reports** on the assistant tables: ```sql UPDATE saved_view SET table_name = CASE table_name WHEN 'assistantConversation' THEN 'assistant_conversation' WHEN 'assistantMessage' THEN 'assistant_message' WHEN 'assistantTurn' THEN 'assistant_turn' WHEN 'assistantTurnEvent' THEN 'assistant_turn_event' WHEN 'assistantToolCall' THEN 'assistant_tool_call' WHEN 'assistantFeedback' THEN 'assistant_feedback' WHEN 'assistantPolicy' THEN 'assistant_policy' WHEN 'assistantUsageDaily' THEN 'assistant_usage_daily' ELSE table_name END WHERE table_name IN ('assistantConversation', 'assistantMessage', 'assistantTurn', 'assistantTurnEvent', 'assistantToolCall', 'assistantFeedback', 'assistantPolicy', 'assistantUsageDaily'); ``` Run the same statement against `saved_report` (and `quick_saved_view` / `shared_saved_view` only if they store a table name in your schema). 3. **Audit table names.** QQQ audits reference tables through the `audit_table` lookup. Rename the rows so old and new audits stay under one table: ```sql UPDATE audit_table SET name = CASE name WHEN 'assistantConversation' THEN 'assistant_conversation' WHEN 'assistantMessage' THEN 'assistant_message' WHEN 'assistantTurn' THEN 'assistant_turn' WHEN 'assistantTurnEvent' THEN 'assistant_turn_event' WHEN 'assistantToolCall' THEN 'assistant_tool_call' WHEN 'assistantFeedback' THEN 'assistant_feedback' WHEN 'assistantPolicy' THEN 'assistant_policy' WHEN 'assistantUsageDaily' THEN 'assistant_usage_daily' ELSE name END WHERE name IN ('assistantConversation', 'assistantMessage', 'assistantTurn', 'assistantTurnEvent', 'assistantToolCall', 'assistantFeedback', 'assistantPolicy', 'assistantUsageDaily'); ``` If a new-name row was already created (the app ran RC.3 before this update), repoint `audit.audit_table_id` from the old row to the new one first, then delete the old row. 4. **Anything else that stores a table name**: frontend links or bookmarks to `/app/.../assistantConversation`, Quick Search index rows (`quick_search_index.table_name`; reindex instead of editing), ESB topics or reports you configured by table name. ### Order Deploy RC.3 and run the statements above in the same maintenance window. Until the update runs, saved views and reports on the assistant tables do not open, and admins who get the all-access key from their own customizer only see their own rows. ## 0.1.0-RC.6: tools through the UI API Database (see `docs/schema-postgres.sql`): - new tables `assistant_data_access`, `assistant_pending_action`, `assistant_profile`, `assistant_skill` and `assistant_profile_skill`; - new columns `assistant_tool_call.ui_api_operation`, `http_status`, `audit_href`, `pending_action_id`; - new columns `assistant_policy.writes_require_confirmation`, `allowed_tools`, `max_rows_per_call`, `redact_pii`. Runtime: the tools call this server's own `/qqq/v1` on `127.0.0.1` and the port the first assistant request arrived on. If the server is not reachable that way (a different bind address, a TLS-only listener), set `withUiApiBaseUrl(...)`. Grant `assistant.admin` holders the new tables through the qbit's existing admin permission (no new permission names). Behavior: nothing is writable until an admin adds a READ_WRITE data access row; before that the assistant reads exactly what it did before, now through the UI API. ## P-a: provider and model registry Before starting the new version, database-backed hosts add the provider columns and model sub-table below. Memory-backed hosts need no migration. Existing rows derive kind and location from the adapter and keep their model behavior until models are registered. Keys remain environment-variable references. ```sql ALTER TABLE assistant_provider ADD COLUMN kind VARCHAR(30), ADD COLUMN tls_ca_bundle VARCHAR(100), ADD COLUMN location VARCHAR(10), ADD COLUMN hipaa_eligible BOOLEAN DEFAULT FALSE, ADD COLUMN region VARCHAR(50), ADD COLUMN api_version VARCHAR(30), ADD COLUMN connect_timeout_seconds INTEGER DEFAULT 10 CHECK (connect_timeout_seconds BETWEEN 1 AND 600), ADD COLUMN request_timeout_seconds INTEGER DEFAULT 120 CHECK (request_timeout_seconds BETWEEN 1 AND 600), ADD COLUMN last_discovery_at TIMESTAMP WITH TIME ZONE, ADD COLUMN last_discovery_status VARCHAR(16), ADD COLUMN last_discovery_error VARCHAR(500); ALTER TABLE assistant_provider ALTER COLUMN model TYPE VARCHAR(200); ALTER TABLE assistant_provider ALTER COLUMN last_test_model TYPE VARCHAR(200); ALTER TABLE assistant_usage ALTER COLUMN model TYPE VARCHAR(200); ALTER TABLE assistant_message ALTER COLUMN model TYPE VARCHAR(200); ALTER TABLE assistant_turn ALTER COLUMN model TYPE VARCHAR(200); CREATE TABLE assistant_model ( id SERIAL PRIMARY KEY, provider_id INTEGER NOT NULL REFERENCES assistant_provider(id), model_id VARCHAR(200) NOT NULL, display_name VARCHAR(200), enabled BOOLEAN, supports_tools BOOLEAN, supports_vision BOOLEAN, supports_streaming BOOLEAN, supports_reasoning_effort BOOLEAN, context_window_tokens INTEGER, max_output_tokens INTEGER, input_usd_per_m_tok NUMERIC(12, 4), output_usd_per_m_tok NUMERIC(12, 4), source VARCHAR(16), discovered_at TIMESTAMP WITH TIME ZONE, last_test_at TIMESTAMP WITH TIME ZONE, last_test_status VARCHAR(16), last_test_latency_ms INTEGER, last_test_error VARCHAR(500), create_date TIMESTAMP WITH TIME ZONE, modify_date TIMESTAMP WITH TIME ZONE, UNIQUE (provider_id, model_id) ); ``` Register the optional `qbit-assistant-provider-openai` module and `OpenAiCompatibleProviderType` to offer its kinds. Azure and generic endpoints require an explicit `allowedBaseUrls` entry; local defaults may be keyless. Discover models preserves existing rows. Cloud catalogs larger than 20 are added disabled; enable the models to offer before leaving the provider's model empty. HIPAA eligibility records an administrator's fact; P-a does not implement PHI routing. Custom CA bundles are server configuration, never database content. Register them with `withTrustedCaBundle(name, pem)` or `withTrustedCaBundleFile(name, path)` at startup, then set the HTTPS provider row's `tlsCaBundle` to that name. Empty references retain JVM default trust. The bundle adds trust without replacing JVM roots; hostname verification remains enabled. If the P-a columns were already applied, add only `tls_ca_bundle VARCHAR(100)` to `assistant_provider`. ## P-b: AWS Bedrock and Google Vertex Before starting this version, database-backed hosts that already applied P-a add: ```sql ALTER TABLE assistant_provider ADD COLUMN cloud_project VARCHAR(100); ``` Fresh installations use `docs/schema-postgres.sql`; memory-backed hosts need no migration. Existing providers leave the new column null. Vertex requires the GCP project id in `cloudProject`; Bedrock and Vertex both require `region` and reject `apiKeyEnvName`. They default to CLOUD; `hipaaEligible` remains a manual admin fact. Add the optional `qbit-assistant-provider-bedrock` and/or `qbit-assistant-provider-vertex` module at the QBit version and register `BedrockProviderType` / `VertexProviderType`. Credentials come from the server's AWS default chain / Google Application Default Credentials. No credentials are stored in provider rows. Hosts using AWS IRSA or web identity supply `software.amazon.awssdk:sts` on their own runtime classpath (matching the transitive AWS SDK version); this QBit does not add it. See README Providers for configuration, endpoint overrides and static discovery limitations.