@yadsh/dsh-qa-surface 0.11.2 → 0.13.0

package/lib/types/admin/service.d.ts

@@ -2,9 +2,9 @@ import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaAccounts } from "../accounts/store.js";
 import type { QaAccessService } from "../access/service.js";
 import type { QaRoleRepository } from "../access/role-repository.js";
-import type { QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminSkillScope, QaAdminSkillsView, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaPasswordResetRequest, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillToolDescriptor, QaSkillValidation, QaUserQuery } from "../types.js";
+import type { QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminSkillScope, QaAdminSkillsView, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaFeedbackHarvestEntry, QaFeedbackHarvestResult, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaPasswordResetRequest, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillToolDescriptor, QaSkillValidation, QaUserQuery } from "../types.js";
 import type { QaPersonalSkills } from "../personal-skills/index.js";
-import type { QaQualityStore } from "./quality-store.js";
+import { type QaQualityStore } from "./quality-store.js";
 import type { QaAdminRedactor } from "./redaction.js";
 import type { QaSessionLogReader, QaStoredSessionEraser } from "./session-log.js";
 /**
@@ -52,6 +52,8 @@ export interface QaAdminServiceOptions {
 export declare class QaAdminService {
     private readonly options;
     private readonly redactor;
+    /** The aggregate pass running now, shared by the callers waiting for it. */
+    private scanning;
     private readonly transcripts;
     constructor(options: QaAdminServiceOptions);
     private requireAccounts;
@@ -74,11 +76,46 @@ export declare class QaAdminService {
      * costs a listing per interval at most.
      */
     private index;
-    /** One conversation's projected log, cached for the TTL unless asked fresh. */
+    /**
+     * One conversation's projected log, held across calls.
+     *
+     * A log the Harness no longer holds is finished — nothing can append to it —
+     * so its projection stays valid until the cache evicts it or the conversation
+     * is deleted. Only a log this process is still writing is re-read once the TTL
+     * expires. A cache hit counts as a use: an aggregate pass walks the whole
+     * window, and evicting by read time would drop the conversations the pages ask
+     * for most often and then read them again.
+     *
+     * The one answer this can hold back is a conversation resumed and finished
+     * between two page loads: its counters lag until the log is read for another
+     * reason. The conversation itself is never affected — the detail view always
+     * reads the log — and what the aggregate pages show instead is the newest
+     * projection of every finished conversation, which is the cheaper lie.
+     */
     private transcript;
-    private facts;
-    overview(token: string): Promise<QaAdminOverview>;
-    metrics(token: string): Promise<QaQualityMetrics>;
+    /** Insert or re-touch one projection, keeping the cache inside its budget. */
+    private retain;
+    /**
+     * The aggregate rows of the newest scan window, read in one pass.
+     *
+     * The message counts and the tool failures come from the same projections, so
+     * one walk fills both. While a walk runs, a caller that wants the same window
+     * joins it rather than starting a second scan of the deployment's logs, and the
+     * walk stops once no caller waits for it: a scan nobody is reading is only ever
+     * a load on the store.
+     */
+    private scanOf;
+    /**
+     * Walk one scan window, filling the counts and the failure signals as it goes.
+     *
+     * `waiting` is the caller set of the pass this walk belongs to: the walk gives
+     * up between two reads once every caller has left, so a reviewer who abandons a
+     * page that has not answered does not keep the deployment reading logs for an
+     * answer nobody will see.
+     */
+    private walk;
+    overview(token: string, signal?: AbortSignal): Promise<QaAdminOverview>;
+    metrics(token: string, signal?: AbortSignal): Promise<QaQualityMetrics>;
     private metricsOf;
     /** One attention line per condition worth an administrator's time. */
     private alertsOf;
@@ -108,7 +145,7 @@ export declare class QaAdminService {
     private assertAdminSurvives;
     /** Validate an assignment against the enabled roles before storing it. */
     private exactAssignment;
-    conversations(token: string, query: QaConversationQuery, cursor: string | undefined, limit: number | undefined): Promise<QaAdminPage<QaConversationSummary>>;
+    conversations(token: string, query: QaConversationQuery, cursor: string | undefined, limit: number | undefined, signal?: AbortSignal): Promise<QaAdminPage<QaConversationSummary>>;
     private summaryOf;
     conversation(token: string, conversationId: string): Promise<QaConversationDetail>;
     /**
@@ -130,17 +167,31 @@ export declare class QaAdminService {
      */
     deleteConversation(token: string, conversationId: string): Promise<QaConversationDeletion>;
     private failuresOf;
-    private failureSignals;
     /**
      * Record the caller's verdict on one assistant message. The conversation must
      * be the caller's own: a rating is the user's own signal, and nobody rates
      * someone else's answer on their behalf.
      */
     rateMessage(token: string, conversationId: string, messageId: string, input: QaMessageFeedbackInput): QaMessageFeedback;
+    /**
+     * Replay the ratings a browser still holds from the window in which a thumbs
+     * never reached the Host.
+     *
+     * A harvest never overwrites. The browser's map stores no timestamp, so an
+     * entry may well be a rating the same user has since filed together with a
+     * reason and a comment; replacing that record with the bare thumbs would
+     * delete exactly what a reviewer reads. An entry the Host already answers for
+     * is counted as present and left alone.
+     *
+     * One unusable or foreign entry costs that entry alone: a browser keeps
+     * ratings of chats it no longer owns, and the rest of the replay must not be
+     * lost because of them.
+     */
+    harvestFeedback(token: string, entries: readonly QaFeedbackHarvestEntry[]): QaFeedbackHarvestResult;
     feedback(token: string, query: QaFeedbackQuery, cursor: string | undefined, limit: number | undefined): Promise<QaAdminPage<QaFeedbackRow>>;
     private feedbackRows;
     private queueRows;
-    reviewQueue(token: string, cursor: string | undefined, limit: number | undefined): Promise<QaAdminPage<QaReviewQueueRow>>;
+    reviewQueue(token: string, cursor: string | undefined, limit: number | undefined, signal?: AbortSignal): Promise<QaAdminPage<QaReviewQueueRow>>;
     /** Park a conversation for review without rating it. */
     queueConversation(token: string, conversationId: string, messageId: string | undefined): QaReviewQueueItem;
     /** Save a reviewer's verdict, and take the item out of the queue when done. */

package/lib/types/client/QaAccountsController.d.ts

@@ -49,6 +49,17 @@ export interface QaAccountsControllerOptions {
      */
     readonly legacyChatIds?: () => readonly string[];
     readonly forgetChat?: (sessionId: string) => void;
+    /**
+     * Replay this browser's locally held ratings onto the account it just signed
+     * in as, for the chats that account owns. Runs once per account: the surface
+     * is usable while it is in flight, and a failure costs only the retry the
+     * next login performs.
+     */
+    readonly harvestRatings?: (context: {
+        readonly token: string;
+        readonly accountId: string;
+        readonly ownedIds: readonly string[];
+    }) => Promise<void>;
 }
 /**
  * Browser-side account lifecycle: token persistence, the checking → gate →
@@ -145,7 +156,7 @@ export declare class QaAccountsController {
      */
     revokeServiceToken(tokenId: string): Promise<QaIntegrationTokenResult<null>>;
     private authenticate;
-    /** Own the account, migrate the legacy index, then project authed. */
+    /** Own the account, migrate the legacy index, replay held ratings, then auth. */
     private enterSession;
     /** Refresh the owned list after index changes; cheap enough to re-pull. */
     refreshOwned(): Promise<void>;

package/lib/types/client/admin/shared.d.ts

@@ -7,12 +7,27 @@ export declare function errorMessage(error: unknown): string;
  * and no deployment detail leaks into the browser.
  */
 export declare function adminErrorMessage(error: unknown): string;
+/**
+ * One cancellable request slot. A page that starts a second request has stopped
+ * waiting for the first, and a page that is gone waits for nothing at all —
+ * either way the abandoned call should end instead of holding its connection and
+ * the deployment's log reader open. The aggregate pages take minutes to answer on
+ * a real store, so an abandoned page used to keep working long after the reviewer
+ * moved on, and the calls it queued behind it paid for that.
+ */
+export declare function useRequestSlot(): {
+    readonly start: () => AbortController;
+    readonly cancel: () => void;
+};
 /**
  * Load one administrative resource, keeping the previous value visible while
  * it refreshes. Reviewers page through lists while new conversations arrive;
  * blanking the table on every reload would make that unusable.
+ *
+ * `load` receives the cancellation of the call it is making: pass it on to the
+ * Remote, and a page the reviewer left stops being read on the server.
  */
-export declare function useAdminResource<T>(load: () => Promise<RemoteResult<T>>, deps: readonly unknown[]): {
+export declare function useAdminResource<T>(load: (signal: AbortSignal) => Promise<RemoteResult<T>>, deps: readonly unknown[]): {
     readonly data: T | undefined;
     readonly error: string | undefined;
     readonly loading: boolean;

package/lib/types/client/markdown/MermaidBlock.d.ts

@@ -0,0 +1,6 @@
+/** Remove executable and remotely loading SVG features before DOM insertion. */
+export declare function sanitizeMermaidSvg(svg: string): Element;
+export declare const MermaidBlock: import("react").MemoExoticComponent<({ code, }: {
+    readonly code: string;
+}) => import("react/jsx-runtime").JSX.Element>;
+//# sourceMappingURL=MermaidBlock.d.ts.map

package/lib/types/client/rating-harvest.d.ts

@@ -0,0 +1,49 @@
+import type { QaFeedbackHarvestEntry, QaFeedbackHarvestResult } from "../types.js";
+import type { RemoteResult, StorageLike } from "./types.js";
+/** `StorageLike` plus the enumeration a browser's `localStorage` offers. */
+export interface HarvestStorage extends StorageLike {
+    readonly length: number;
+    key(index: number): string | null;
+}
+export type QaRatingHarvestStatus = 
+/** This account was already read out; nothing is offered again. */
+"already-harvested"
+/** Nothing addressable was found, so the account is marked as read. */
+ | "nothing-to-harvest" | "harvested"
+/** A request failed; the marker stays unset and the next login retries. */
+ | "failed";
+export interface QaRatingHarvestReport {
+    readonly status: QaRatingHarvestStatus;
+    /** Ratings this browser offered for that account. */
+    readonly entries: number;
+    /** Ratings the Host stored. What it already held counts as nothing. */
+    readonly recorded: number;
+}
+/** Whether this browser has already been read out for that account. */
+export declare function ratingsHarvested(storage: HarvestStorage, namespace: string, accountId: string): boolean;
+/**
+ * Every rating this browser holds for that namespace, addressed by the
+ * conversation and by the durable log position the Host files a verdict under.
+ *
+ * An answer row's browser id is `assistant:<position>`, so those keys are
+ * addressable. Anything else — a work row, a half-streamed answer, an id the
+ * Host named rather than numbered — cannot be traced back to a log position,
+ * and is left where it is instead of guessed at.
+ */
+export declare function collectLocalRatings(storage: HarvestStorage, namespace: string): readonly QaFeedbackHarvestEntry[];
+/**
+ * Read this browser's ratings out through `send`, once per account.
+ *
+ * `send` is the Host call; the caller chooses the token and the remote it
+ * travels on. The marker is written only after every batch landed, so a
+ * half-failed harvest is retried by the next login rather than lost.
+ */
+export declare function harvestLocalRatings(options: {
+    readonly storage: HarvestStorage;
+    readonly namespace: string;
+    readonly accountId: string;
+    /** The chats the account owns; a rating of anyone else's chat is not offered. */
+    readonly ownedIds: readonly string[];
+    readonly send: (batch: readonly QaFeedbackHarvestEntry[]) => Promise<RemoteResult<QaFeedbackHarvestResult>>;
+}): Promise<QaRatingHarvestReport>;
+//# sourceMappingURL=rating-harvest.d.ts.map

package/lib/types/client/settings/sections/docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Documentation: which edition of the corpus a question is answered from.
+ *
+ * A published corpus carries several editions of the same module under
+ * `docs/<module>/<version>/…`, and a chat asked about "the product" reads
+ * whichever edition it meets first. A stand that knows which edition it is
+ * about names it here, and `docs_search` stays inside it unless the call itself
+ * names a `version` or narrows `path`. The switch keeps the value while turning
+ * the behaviour off, so a stand can stop defaulting without losing the version
+ * it configured.
+ */
+import { type ConfigProps } from "./common.js";
+/** The documentation corpus the QA tools read, and the edition they default to. */
+export declare function DocsSection(props: ConfigProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=docs.d.ts.map

package/lib/types/client/settings/sections.d.ts

@@ -15,6 +15,7 @@ export { AccessSection } from "./sections/access.js";
 export { AccountsSection } from "./sections/accounts.js";
 export { AttachmentsSection } from "./sections/attachments.js";
 export { BrandingSection } from "./sections/branding.js";
+export { DocsSection } from "./sections/docs.js";
 export { EmbeddingSection } from "./sections/embedding.js";
 export { InterfaceSection } from "./sections/interface.js";
 export { LockdownSection } from "./sections/lockdown.js";

package/lib/types/client/types.d.ts

@@ -52,7 +52,14 @@ export interface QaAccessApi {
  * the page renders.
  */
 export interface QaAdminApi {
-    overview(token: string): Promise<RemoteResult<QaAdminOverview>>;
+    /**
+     * The four aggregate pages (`overview`, `conversations`, `reviewQueue`,
+     * `metrics`) take the caller's cancellation: each of them reads the newest
+     * conversation logs of the deployment, which is minutes of work on a real
+     * store, and a page that has been left must stop waiting for the answer
+     * instead of holding the request — and the deployment's log reader — open.
+     */
+    overview(token: string, signal?: AbortSignal): Promise<RemoteResult<QaAdminOverview>>;
     users(token: string, query: QaUserQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaAdminUserRow>>>;
     user(token: string, userId: string): Promise<RemoteResult<QaAdminUserDetail>>;
     updateUser(token: string, userId: string, update: QaAdminUserUpdate): Promise<RemoteResult<QaAdminUserDetail>>;
@@ -66,7 +73,7 @@ export interface QaAdminApi {
      * account's live sessions end with the token-version bump.
      */
     resetPassword(token: string, userId: string, password: string): Promise<RemoteResult<QaAdminUserDetail>>;
-    conversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaConversationSummary>>>;
+    conversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null, signal?: AbortSignal): Promise<RemoteResult<QaAdminPage<QaConversationSummary>>>;
     conversation(token: string, conversationId: string): Promise<RemoteResult<QaConversationDetail>>;
     /**
      * Remove the conversation from the deployment, stored logs included. Only an
@@ -76,10 +83,10 @@ export interface QaAdminApi {
     feedback(token: string, query: QaFeedbackQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaFeedbackRow>>>;
     /** The signed-in user's own verdict on one of their assistant messages. */
     rateMessage(token: string, conversationId: string, messageId: string, input: QaMessageFeedbackInput): Promise<RemoteResult<QaMessageFeedback>>;
-    reviewQueue(token: string, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaReviewQueueRow>>>;
+    reviewQueue(token: string, cursor: string | null, limit: number | null, signal?: AbortSignal): Promise<RemoteResult<QaAdminPage<QaReviewQueueRow>>>;
     queueConversation(token: string, conversationId: string, messageId: string | null): Promise<RemoteResult<QaReviewQueueItem>>;
     saveReview(token: string, input: QaConversationReviewInput): Promise<RemoteResult<QaConversationReview>>;
-    metrics(token: string): Promise<RemoteResult<QaQualityMetrics>>;
+    metrics(token: string, signal?: AbortSignal): Promise<RemoteResult<QaQualityMetrics>>;
     audit(token: string, query: QaAuditQuery, cursor: string | null, limit: number | null): Promise<RemoteResult<QaAdminPage<QaAdminAuditEvent>>>;
     /**
      * Skill files an administrator may edit: the deployment's shared store, or

package/lib/types/config-resolvers/integration.d.ts

@@ -4,13 +4,13 @@ type ResolvedIntegration = ResolvedQaSurfaceConfig["integration"];
 export declare const QA_INTEGRATION_TTL_DAYS_MIN = 1;
 export declare const QA_INTEGRATION_TTL_DAYS_MAX = 3650;
 /**
- * Floor only: how long an integration may wait for its answer is the operator's
- * call. The deployment spends no budget of its own by waiting, and the ceiling
- * this constant used to carry (10 minutes) truncated exactly the long questions
- * an integration exists for — a nineteen-minute analysis came back as
- * "escalate" while the answer was still being written.
+ * The operator may choose any wait Node can represent faithfully. The former
+ * ten-minute product ceiling cut off legitimate long analyses, while values
+ * above the runtime ceiling wrap to an almost immediate timer.
  */
 export declare const QA_INTEGRATION_TIMEOUT_MS_MIN = 5000;
+/** Largest delay Node schedules without overflowing to an immediate timer. */
+export declare const QA_INTEGRATION_TIMEOUT_MS_MAX = 2147483647;
 export declare const QA_INTEGRATION_CONCURRENCY_MIN = 1;
 export declare const QA_INTEGRATION_CONCURRENCY_MAX = 16;
 export declare const QA_INTEGRATION_RATE_MIN = 1;

package/lib/types/config-resolvers/tools.d.ts

@@ -2,5 +2,14 @@ import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "../types.js";
 type ToolsSlice = ResolvedQaSurfaceConfig["tools"];
 /** Resolve the QA tool delivery domain: activation trigger, policy, and scope. */
 export declare function resolveTools(input: QaSurfaceConfig): ToolsSlice;
+/**
+ * The version one search runs under, or `""` when the deployment's default is
+ * off, unset, or not what the call is about.
+ *
+ * The readers take a single fallback, and a switch that is off must not fall
+ * back at all — the value stays configured for the day it is turned on, and an
+ * enabled-but-empty pair is simply no default.
+ */
+export declare function docsDefaultVersionOf(tools: ResolvedQaSurfaceConfig["tools"]): string;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import type { Context } from "@deepseek-ai/cordis";
 import type { QaTurnSources } from "./provenance/types.js";
-import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaIssuedServiceToken, QaLockdownProof, QaOwnershipEntry, QaPasswordResetRequest, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaServiceTokenCreateInput, QaServiceTokenSummary, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaAdminSkillScope, QaAdminSkillsView, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
+import type { QaAccountProfileInput, QaAccountSession, QaAccountStartersInput, QaAccountUserPublic, QaApprovalDecision, QaClaimResult, QaDocumentPreview, QaIssuedServiceToken, QaLockdownProof, QaOwnershipEntry, QaPasswordResetRequest, QaPendingApproval, QaPendingQuestion, QaQuestionAnswerItem, QaServiceTokenCreateInput, QaServiceTokenSummary, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaAdminSkillScope, QaAdminSkillsView, QaSkillDocument, QaSkillDraftInput, QaSkillRemoval, QaSkillSummary, QaSkillToolDescriptor, QaSkillValidation, QaSourceFilePreview, QaWhoamiResult, QaWorkspaceFile, QaWorkspaceListing, QaPrincipal, QaAccessAdminSnapshot, QaAdminAuditEvent, QaAdminOverview, QaAdminPage, QaAdminUserDetail, QaAdminUserRow, QaAdminUserUpdate, QaAuditQuery, QaCapabilitySelection, QaConversationDetail, QaConversationDeletion, QaConversationQuery, QaConversationReview, QaConversationReviewInput, QaConversationSummary, QaCurrentAccess, QaFeedbackHarvestEntry, QaFeedbackHarvestResult, QaFeedbackQuery, QaFeedbackRow, QaMessageFeedback, QaMessageFeedbackInput, QaQualityMetrics, QaReviewQueueItem, QaReviewQueueRow, QaSessionAccess, QaSlashCatalog, QaSlashExecution, QaSlashSubmitAttachment, QaSkillActivationRecord, QaSkillAssignmentOverride, QaSubrole, QaUserAccess, QaUserQuery } from "./types.js";
 export declare const name = "qa-surface";
 export declare const inject: string[];
 import { QA_SURFACE_SETTINGS_NAMESPACE } from "./shared/settings.js";
@@ -232,15 +232,22 @@ export declare class QaSurface extends TypertRemoteService {
     adminSkillTools(token: string, scope: QaAdminSkillScope): Promise<{
         readonly tools: readonly QaSkillToolDescriptor[];
     }>;
-    /** Counters, attention lines and the newest quality signals. */
-    adminOverview(token: string): Promise<QaAdminOverview>;
+    /**
+     * Counters, attention lines and the newest quality signals.
+     *
+     * The Host hands the last parameter its cancellation: this call reads the
+     * newest conversation logs of the deployment, which on a real store is minutes
+     * of work, and a reviewer who leaves the page while it runs must not leave it
+     * running — every other administrative call waits behind it.
+     */
+    adminOverview(token: string, signal: AbortSignal): Promise<QaAdminOverview>;
     adminUsers(token: string, query: QaUserQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaAdminUserRow>>;
     adminUser(token: string, userId: string): Promise<QaAdminUserDetail>;
     /** Authorization role, status and subrole assignment of one account. */
     adminUpdateUser(token: string, userId: string, update: QaAdminUserUpdate): Promise<QaAdminUserDetail>;
     adminPasswordResetRequests(token: string): Promise<readonly QaPasswordResetRequest[]>;
     adminResetPassword(token: string, userId: string, password: string): Promise<QaAdminUserDetail>;
-    adminConversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaConversationSummary>>;
+    adminConversations(token: string, query: QaConversationQuery, cursor: string | null, limit: number | null, signal: AbortSignal): Promise<QaAdminPage<QaConversationSummary>>;
     /** One conversation with its messages, tool calls and review state. */
     adminConversation(token: string, conversationId: string): Promise<QaConversationDetail>;
     /**
@@ -255,11 +262,16 @@ export declare class QaSurface extends TypertRemoteService {
      * ratable conversation, exactly as the self-service profile write does.
      */
     adminRateMessage(token: string, conversationId: string, messageId: string, input: QaMessageFeedbackInput): QaMessageFeedback;
-    adminReviewQueue(token: string, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaReviewQueueRow>>;
+    /**
+     * Replay the ratings a browser still holds from before a thumbs reached the
+     * Host. Insert-only: what the deployment already records is never rewritten.
+     */
+    adminHarvestFeedback(token: string, entries: readonly QaFeedbackHarvestEntry[]): QaFeedbackHarvestResult;
+    adminReviewQueue(token: string, cursor: string | null, limit: number | null, signal: AbortSignal): Promise<QaAdminPage<QaReviewQueueRow>>;
     /** Park a conversation for review without rating it. */
     adminQueueConversation(token: string, conversationId: string, messageId: string | null): QaReviewQueueItem;
     adminSaveReview(token: string, input: QaConversationReviewInput): QaConversationReview;
-    adminMetrics(token: string): Promise<QaQualityMetrics>;
+    adminMetrics(token: string, signal: AbortSignal): Promise<QaQualityMetrics>;
     adminAudit(token: string, query: QaAuditQuery, cursor: string | null, limit: number | null): Promise<QaAdminPage<QaAdminAuditEvent>>;
     /** Pin and attest the effective policy. The browser supplies identity only. */
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;

package/lib/types/qa-tools/catalog.d.ts

@@ -23,7 +23,12 @@ export interface QaToolsSelfcheckDeps {
      * Documentation root the two readers use, or `""` for the `docs/` directory
      * inside each chat's own workspace.
      */
-    readonly docsRoot?: string;
+    readonly docsRoot?: string | (() => string);
+    /**
+     * Version a search without `version` and without `path` stays inside, or `""`
+     * for a search across every edition the corpus carries.
+     */
+    readonly docsDefaultVersion?: string | (() => string);
 }
 /**
  * Build the shipped QA tool catalog.

package/lib/types/qa-tools/docs-tools.d.ts

@@ -19,6 +19,14 @@ import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
  * names are accepted as filters. A path the convention does not describe is
  * still searched and still read — it simply carries no identity.
  *
+ * A real corpus also carries its own working material: the stand publishes an
+ * asset tree, inventories and triage notes beside the documents, under leading
+ * underscores. None of that is what a question is asked about, and an inventory
+ * names every module and version there is, so a walk that met it first spent the
+ * whole answer on it. The walk therefore visits the documented modules first,
+ * loose files next, and the underscored service material last — searched, but
+ * never at the expense of the documents.
+ *
  * Nothing here is destructive and building it registers nothing: like the rest
  * of the catalog these are side-effect-free definitions, and the workspace root
  * is read from `exec.agent` at call time.
@@ -67,6 +75,13 @@ interface QaDocsExecution {
 export interface QaDocsOptions {
     /** Absolute documentation root, or `""` for `<chat workspace>/docs`. */
     readonly root?: string;
+    /**
+     * Documentation version a search stays inside when the caller named neither
+     * `version` nor `path`; `""` (the default) leaves every edition in scope. The
+     * deployment sets it so a chat's questions do not have to carry the stand's
+     * edition, and an explicit `version` or `path` still decides for itself.
+     */
+    readonly defaultVersion?: string;
 }
 /** The resolved documentation root of one call. */
 export interface QaDocsRoot {
@@ -146,8 +161,8 @@ export interface QaDocsSearchRequest {
 /**
  * Search the documentation tree of one chat workspace.
  *
- * Matching is a case-insensitive substring test, line by line: a hit is a
- * line, not a file, so the caller can cite it. The result is bounded twice —
+ * Matching uses one case-insensitive, grep-style regular expression, line by
+ * line: a hit is a line, not a file, so the caller can cite it. The result is bounded twice —
  * by `limit` hits and by the byte budget of the rendered report — and reports
  * which bound cut it short instead of silently dropping matches.
  * @throws QaDocsError when the tree is missing, the scope path is wrong, or the query is empty.

package/lib/types/qa-tools/index.d.ts

@@ -9,7 +9,12 @@ export interface QaToolsOptions {
     readonly activationMode: string;
     readonly activationPresets: readonly string[];
     /** Documentation root the readers use; `""` reads each chat's own `docs/`. */
-    readonly docsRoot: string;
+    readonly docsRoot: string | (() => string);
+    /**
+     * Version a search falls back to when the model named neither `version` nor
+     * `path`; `""` searches every edition the corpus carries.
+     */
+    readonly docsDefaultVersion: string | (() => string);
 }
 /**
  * The QA tool subsystem: one catalog, one per-agent activation manager, and the

package/lib/types/shared/docs-version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The documentation version grammar, shared by the Host and the browser half.
+ *
+ * This module must stay dependency-free: the settings card bundle inlines the
+ * resolver that validates a configured default version, and a browser build
+ * must not pull the QA tool runtime — or the Node builtins it reads files with
+ * — into the page just to learn what a version looks like.
+ */
+/**
+ * Whether a path segment — or a configured default version — is a documentation
+ * version. A default the corpus can never match is refused where it is written
+ * rather than answered with an empty search.
+ */
+export declare function isDocumentationVersion(value: string): boolean;
+//# sourceMappingURL=docs-version.d.ts.map

package/lib/types/types.d.ts

@@ -721,6 +721,21 @@ export interface QaSurfaceConfig {
          * per-user directory, which is otherwise unreadable to those tools.
          */
         readonly docsRoot?: string;
+        /**
+         * Documentation version `docs_search` stays inside when the model named
+         * neither `version` nor `path`. A corpus carries several editions of the
+         * same module, and a chat asked about "the product" answers out of whichever
+         * edition it happened to read first; naming the stand's edition here lets a
+         * search default to it, and an explicit `version` or `path` still decides
+         * for itself.
+         */
+        readonly docsDefaultVersion?: string;
+        /**
+         * Whether `docsDefaultVersion` is applied. The value stays configured while
+         * the switch is off, so a stand can turn the default back on without
+         * retyping it.
+         */
+        readonly docsDefaultVersionEnabled?: boolean;
     };
     readonly lockdown?: {
         readonly enabled?: boolean;
@@ -1002,6 +1017,13 @@ export interface ResolvedQaSurfaceConfig {
          * `docs/` directory inside each chat's own workspace.
          */
         readonly docsRoot: string;
+        /**
+         * Version a search without `version` and without `path` stays inside, or
+         * `""` for a search across every edition the corpus carries.
+         */
+        readonly docsDefaultVersion: string;
+        /** Whether the deployment's default version is in force. */
+        readonly docsDefaultVersionEnabled: boolean;
     };
     readonly sources: {
         readonly enabled: boolean;
@@ -1568,6 +1590,26 @@ export interface QaMessageFeedbackInput {
     readonly reasons?: readonly QaFeedbackReason[];
     readonly comment?: string;
 }
+/**
+ * One rating a browser still holds locally: a verdict given while the surface
+ * had no way to file it, replayed by the harvest. Reasons never ride along —
+ * the browser's map only ever stored the thumbs.
+ */
+export interface QaFeedbackHarvestEntry {
+    readonly conversationId: string;
+    /** The durable log position, exactly as a live rating carries it. */
+    readonly messageId: string;
+    readonly rating: QaFeedbackRating;
+}
+/** What one harvest write did; the counts answer for the whole batch. */
+export interface QaFeedbackHarvestResult {
+    /** Ratings the Host stored now. Replaying the same batch stores none. */
+    readonly recorded: number;
+    /** Entries the Host already held a rating for, left as they were. */
+    readonly present: number;
+    /** Entries refused: not the caller's conversation, or unusable. */
+    readonly rejected: number;
+}
 /** Review workflow state of a conversation or one of its messages. */
 export type QaReviewStatus = "unreviewed" | "in_review" | "reviewed" | "needs_followup";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -131,13 +131,14 @@
     "react-dom": "^18.2.0"
   },
   "dependencies": {
+    "mermaid": "^11.12.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "@yadsh/dsh-audit-core": "^0.1.0",
-    "@yadsh/dsh-documents": "^0.5.1",
-    "@yadsh/dsh-plugin-log": "^0.4.0",
     "@yadsh/dsh-audit-ui": "^0.1.1",
-    "@yadsh/dsh-plugin-kit": "^0.3.0"
+    "@yadsh/dsh-documents": "^0.5.1",
+    "@yadsh/dsh-plugin-kit": "^0.4.0",
+    "@yadsh/dsh-plugin-log": "^0.4.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",