qbit-assistant/UPGRADE.md

Upgrading qbit-assistant

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:

   - 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.

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:

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<String> 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 = <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:

- 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-checks).

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 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 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/<taskId>.

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 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.

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 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 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.

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:<base64(iv|ciphertext|tag)> (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 <base>.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: <Entity>.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:

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 <keyType>_all_access.

2. Saved views and saved reports on the assistant tables:

   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:

   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.

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:

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.