@yadsh/dsh-qa-surface 0.1.1 → 0.3.0

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

@@ -0,0 +1,93 @@
+import type { ClientRemote } from "@deepseek-ai/dsh-api-gateway/client";
+import type { ISessions, SessionFace } from "@deepseek-ai/dsh-api-session-controller/client";
+import type { UiConversation } from "@deepseek-ai/dsh-client-ui-conversation/client";
+import type { QaAccountSession, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSessionState, QaSourceFilePreview, QaTurnSources, QaWhoamiResult } from "../types.js";
+/** Wire content one prompt carries: text plus base64 image uploads. */
+export type QaPromptContent = Parameters<SessionFace["prompt"]>[0];
+/** DSH session runtime surface the QA controller is allowed to touch. */
+export type QaSessions = ISessions;
+/** Narrow client API slice used to pin the preset and model of a fresh chat. */
+export type QaSessionsApi = {
+    selectModel: ClientRemote["session"]["selectModel"];
+    selectAgentPreset: ClientRemote["agentPresets"]["select"];
+};
+/**
+ * Conversation assembly the QA transcript is projected from: the per-Session
+ * binding carries the assembled Chat view (nodes, partials, tool calls).
+ */
+export type QaConversation = Pick<UiConversation, "binding">;
+/**
+ * Attestation channel to the Host admission boundary
+ * (`qaSurface/secureSession`). The account token rides as the first argument
+ * when accounts are enabled; an empty string is the anonymous caller.
+ */
+export type QaSecureSession = (token: string, sessionId: string) => Promise<{
+    readonly ok: true;
+    readonly value: QaLockdownProof;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+}>;
+export interface QaSourceApi {
+    sources(token: string, sessionId: string): Promise<{
+        readonly ok: true;
+        readonly value: readonly QaTurnSources[];
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+    readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<{
+        readonly ok: true;
+        readonly value: QaSourceFilePreview;
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+}
+/** A source API with the account token already bound at the call site. */
+export type QaBoundSourceApi = {
+    sources(sessionId: string): Promise<{
+        readonly ok: true;
+        readonly value: readonly QaTurnSources[];
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+    readSourceFile(sessionId: string, sourcePath: string): Promise<{
+        readonly ok: true;
+        readonly value: QaSourceFilePreview;
+    } | {
+        readonly ok: false;
+        readonly error: unknown;
+    }>;
+};
+/** Account remotes exposed by the plugin's own typert namespace. */
+export interface QaAccountsApi {
+    accountsWhoami(token: string): Promise<RemoteResult<QaWhoamiResult>>;
+    accountsLogin(email: string, password: string): Promise<RemoteResult<QaAccountSession>>;
+    accountsRegister(email: string, password: string): Promise<RemoteResult<QaAccountSession>>;
+    accountsClaimSessions(token: string, sessionIds: readonly string[]): Promise<RemoteResult<QaClaimResult>>;
+    accountsOwnedSessions(token: string): Promise<RemoteResult<{
+        readonly ids: readonly string[];
+    }>>;
+    accountsListOwnership(token: string): Promise<RemoteResult<{
+        readonly entries: readonly QaOwnershipEntry[];
+    }>>;
+}
+type RemoteResult<Value> = {
+    readonly ok: true;
+    readonly value: Value;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+};
+/** Minimal persistence contract; backed by `window.localStorage` in the app. */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** The state projected while no QA chat is bound (route inactive or booting). */
+export declare const QA_SESSION_IDLE_STATE: QaSessionState;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/client/use-session-ui-state.d.ts

@@ -0,0 +1,35 @@
+import { type Dispatch, type SetStateAction } from "react";
+import type { QaImageDraft, QaSource, QaTurnSources } from "../types.js";
+/** Snapshot completeness captured when a drawer was opened from a message. */
+export interface QaDrawerCompleteness {
+    readonly complete: boolean;
+    readonly incompleteOrigins?: QaTurnSources["incompleteOrigins"];
+}
+export interface QaSessionUiState {
+    /** Per group: how many answers back from the newest is shown (0 = newest). */
+    readonly variantOffsets: Record<string, number>;
+    readonly setVariantOffsets: Dispatch<SetStateAction<Record<string, number>>>;
+    /** The turn the transcript's reading line currently owns. */
+    readonly activeTurn: number | null;
+    readonly setActiveTurn: Dispatch<SetStateAction<number | null>>;
+    readonly agentsOpen: boolean;
+    readonly setAgentsOpen: Dispatch<SetStateAction<boolean>>;
+    readonly sourcesOpen: boolean;
+    readonly setSourcesOpen: Dispatch<SetStateAction<boolean>>;
+    readonly drawerSources: readonly QaSource[] | null;
+    readonly setDrawerSources: Dispatch<SetStateAction<readonly QaSource[] | null>>;
+    readonly drawerCompleteness: QaDrawerCompleteness | null;
+    readonly setDrawerCompleteness: Dispatch<SetStateAction<QaDrawerCompleteness | null>>;
+    readonly drawerDetail: QaSource | null;
+    readonly setDrawerDetail: Dispatch<SetStateAction<QaSource | null>>;
+    readonly pendingImages: readonly QaImageDraft[];
+    readonly setPendingImages: (next: readonly QaImageDraft[]) => void;
+}
+/**
+ * Per-chat UI state: composer attachments, variant offsets, the rail mark and
+ * the drawers. Everything here describes the chat it was made in, so a
+ * session change clears it instead of leaking a draft, an image or a drawer
+ * from one conversation into the next.
+ */
+export declare function useSessionUiState(sessionId: string | null): QaSessionUiState;
+//# sourceMappingURL=use-session-ui-state.d.ts.map

package/lib/types/client/use-transcript-view.d.ts

@@ -0,0 +1,20 @@
+import type { QaMessage } from "../types.js";
+import { type QaTurnRailItem } from "./components/QaTurnRail.js";
+import { type QaVariantGroup } from "./components/VariantSwitcher.js";
+export interface QaTranscriptView {
+    readonly visibleMessages: readonly QaMessage[];
+    /** Answer groups by the user message id that opens them. */
+    readonly groupByPromptId: ReadonlyMap<string, QaVariantGroup>;
+    /** Per group: the turn the current variant offset selects. */
+    readonly selectedTurn: ReadonlyMap<string, number>;
+    readonly railItems: readonly QaTurnRailItem[];
+}
+/**
+ * Memoized transcript view model. The controller republishes state with a
+ * fresh messages array on every stream frame, but re-renders that keep the
+ * transcript unchanged (drawers, the active turn mark, variant offsets) must
+ * not re-run the projections — and per-row group lookups go through a map
+ * instead of a linear find inside the render loop.
+ */
+export declare function useTranscriptView(messages: readonly QaMessage[], variantOffsets: Record<string, number>): QaTranscriptView;
+//# sourceMappingURL=use-transcript-view.d.ts.map

package/lib/types/client/wait-for.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve with the first snapshot of an observable source that satisfies
+ * `predicate`, or reject after `timeoutMs`. This is the DSH-runtime glue the
+ * QA surface needs instead of ad-hoc sleeps; the source only has to expose
+ * the getSnapshot/subscribe store pair used across the client bundle.
+ */
+export declare function waitFor<T>(source: {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}, predicate: (value: T) => boolean, timeoutMs: number): Promise<T>;
+//# sourceMappingURL=wait-for.d.ts.map

package/lib/types/entry-redirect.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * The operator/LAN split is decided client-side on `location.hostname` on
+ * purpose: behind the qa-deploy proxy every request appears loopback to the
+ * Host, and the deployment convention is "operator uses localhost, QA users
+ * use the LAN address". `?ui=admin` persists the operator escape hatch under
+ * the deployment's storage key; `?ui=qa` clears it again.
+ */
+export declare function entryRedirectScript(config: ResolvedQaSurfaceConfig): string;
+export interface EntryRedirectRow {
+    readonly kind: "script";
+    readonly placement: "head";
+    readonly text: string;
+}
+/**
+ * The structured index-injection row for one config snapshot, or undefined
+ * when the plugin is disabled or the redirect flag is off.
+ */
+export declare function entryRedirectRow(config: ResolvedQaSurfaceConfig): EntryRedirectRow | undefined;
+//# sourceMappingURL=entry-redirect.d.ts.map

package/lib/types/host-route.d.ts

@@ -1,9 +1,22 @@
+import type { IncomingMessage } from "node:http";
 import type { WebServer } from "@deepseek-ai/dsh-host-webserver";
 import type { ResolvedQaSurfaceConfig } from "./types.js";
+import type { LaunchTokenSource } from "./launch-token.js";
+export interface QaNavigationRouteOptions {
+    /**
+     * Resolves the process launch token; when supplied and the browser carries
+     * no host-auth cookie, the route defers the marker hand-off in favor of the
+     * one-time `/?token=` exchange (relative location: the browser mints the
+     * cookie on the origin it actually used).
+     */
+    readonly launchToken?: LaunchTokenSource;
+}
+/** Presence-only check: an invalid cookie still fails the root gate later. */
+export declare function hasHostAuthCookie(request: IncomingMessage): boolean;
 /**
  * DSH 0.1.1 static hosting returns 404 for missing paths. Redirect a browser
  * navigation through its canonical index entry; the client restores the
  * requested pathname before activating the QA overlay.
  */
-export declare function registerQaNavigationRoute(webServer: Pick<WebServer, "register">, config: ResolvedQaSurfaceConfig): () => void;
+export declare function registerQaNavigationRoute(webServer: Pick<WebServer, "register">, config: ResolvedQaSurfaceConfig, options?: QaNavigationRouteOptions): () => void;
 //# sourceMappingURL=host-route.d.ts.map

package/lib/types/index.d.ts

@@ -1,29 +1,89 @@
-import { Service, type Context } from "@deepseek-ai/cordis";
-import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaTurnSources } from "./provenance/types.js";
+import type { QaAccountSession, QaClaimResult, QaLockdownProof, QaOwnershipEntry, QaSurfaceConfig, ResolvedQaSurfaceConfig, QaSourceFilePreview, QaWhoamiResult } from "./types.js";
 export declare const name = "qa-surface";
-export declare const inject: readonly string[];
-export declare const QA_SURFACE_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const inject: string[];
+export declare const QA_SURFACE_SETTINGS_NAMESPACE = "qa-surface";
 export declare const Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
 declare module "@deepseek-ai/cordis" {
     interface Context {
         qaSurface: QaSurface;
     }
 }
-/** Small Host companion: validates config and exposes it through DSH settings. */
-export declare class QaSurface extends Service {
-    static inject: readonly string[];
+/** Host companion: validates config, owns the admission boundary and the route. */
+export declare class QaSurface extends TypertRemoteService {
+    static inject: string[];
     static Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
     private source;
     private readonly logger;
+    private readonly admission;
+    private readonly provenance;
+    private accounts;
+    private accountsOptions;
+    private readonly launchToken;
     private webServer;
     private disposeRoute;
     private routeKey;
     constructor(ctx: Context, entry?: QaSurfaceConfig);
     getConfig(): ResolvedQaSurfaceConfig;
+    /**
+     * The accounts store behind the runtime toggle. Rebuilt only when the
+     * account-affecting options change; the file is shared across rebuilds.
+     */
+    private accountsFor;
+    /** The accounts store, or the disabled refusal the browser maps to copy. */
+    private requireAccounts;
+    /** Account failures ride the shared `(reason: <code>)` wire marker. */
+    private accountsRemote;
+    /**
+     * Self-service signup; the first account ever created becomes admin. The
+     * display name derives from the email: the generated client enforces exact
+     * wire arity, so an optional name parameter would still be required.
+     */
+    accountsRegister(email: string, password: string): QaAccountSession;
+    accountsLogin(email: string, password: string): QaAccountSession;
+    /** Identity probe; safe to call with an empty or expired token. */
+    accountsWhoami(token: string): QaWhoamiResult;
+    /** Migrate a browser's local chat index into server-side ownership. */
+    accountsClaimSessions(token: string, sessionIds: readonly string[]): QaClaimResult;
+    /** The token user's owned session ids; the sidebar list authority. */
+    accountsOwnedSessions(token: string): {
+        readonly ids: readonly string[];
+    };
+    /**
+     * Every chat-ownership entry with owner display names; the cross-user view
+     * admin browsers group the sidebar by. Ordinary accounts are refused with
+     * the dedicated reason, anonymous ones with auth-required.
+     */
+    accountsListOwnership(token: string): {
+        readonly entries: readonly QaOwnershipEntry[];
+    };
+    /**
+     * Serve the effective QA configuration to the browser. The DSH gateway pins
+     * settings RPCs to loopback, so a browser served over the LAN always sees
+     * the settings namespace as unavailable; this method is the config channel
+     * such a browser falls back to. It is read-only projection — the admission
+     * boundary stays in {@link secureSession}.
+     */
+    describe(): ResolvedQaSurfaceConfig;
+    /** Pin and attest the effective policy. The browser supplies identity only. */
+    secureSession(token: string, sessionId: string): QaLockdownProof;
+    /** Return canonical Host snapshots; replay is rebuilt from qa/sources events. */
+    sources(token: string, sessionId: string): readonly QaTurnSources[];
+    /** Narrow read-only preview capability for files already present as sources. */
+    readSourceFile(token: string, sessionId: string, sourcePath: string): Promise<QaSourceFilePreview>;
     private refreshRoute;
 }
 export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
+export { QaAttestationError } from "./attestation.js";
+export type { QaAttestationReason } from "./attestation.js";
+export { QaAccounts, QaAccountsError } from "./accounts/store.js";
+export { entryRedirectRow, entryRedirectScript } from "./entry-redirect.js";
 export { registerQaNavigationRoute } from "./host-route.js";
+export { qaToolDenial, qaToolPolicyPlan } from "./lockdown-policy.js";
+export { QaPolicyAdmission } from "./secure-session.js";
+export * from "./provenance/index.js";
 export type * from "./types.js";
 export default QaSurface;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/launch-token.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plugin-side launch-token bridge (the pattern proven by dsh-auth-gate): the
+ * 0.1.x host exposes `connection.authenticatedUrl(baseUrl)` whose `?token=`
+ * parameter carries the per-process launch token. The `/qa` route handler
+ * uses it to send cookie-less browsers through the one-time host-cookie
+ * exchange themselves, so the transparent entry works without the qa-deploy
+ * proxy. The host/scheme of the resolved URL are dropped — the redirect is
+ * relative, so the browser stays on the origin it actually used.
+ */
+export type LaunchTokenSource = () => string | undefined;
+interface AuthenticatedUrlFace {
+    authenticatedUrl?(baseUrl: string): string;
+}
+/**
+ * Resolve the launch token once per process (it is stable for the process
+ * lifetime); a missing connection service or an unusable answer warns once
+ * and permanently disables the bridge instead of retrying per request.
+ */
+export declare function makeLaunchTokenSource(getConnection: () => AuthenticatedUrlFace | undefined, warn: (message: string) => void): LaunchTokenSource;
+export {};
+//# sourceMappingURL=launch-token.d.ts.map

package/lib/types/lockdown-policy.d.ts

@@ -0,0 +1,18 @@
+export interface QaToolPolicyPlan {
+    /** Exact names that must remain visible after the scoped restriction. */
+    readonly allow: readonly string[];
+    /** Configured names absent from the agent's composed tool view. */
+    readonly unknown: readonly string[];
+}
+/**
+ * Validate an allow-list against the complete agent-scoped view.
+ *
+ * Preset tools live on an ancestor scope, not necessarily in the global tool
+ * layer. The restriction must therefore retain the configured names verbatim;
+ * deriving it from the global view would hide every preset-owned tool after a
+ * successful first attestation and make the next attestation fail.
+ */
+export declare function qaToolPolicyPlan(allow: readonly string[], isMounted: (toolName: string) => boolean): QaToolPolicyPlan;
+/** Monotonic execution decision shared by inherited, scoped and transport tools. */
+export declare function qaToolDenial(allowed: ReadonlySet<string>, toolName: string): string | undefined;
+//# sourceMappingURL=lockdown-policy.d.ts.map

package/lib/types/provenance/collector.d.ts

@@ -0,0 +1,26 @@
+import type { QaSourceReference, QaTurnSources, SourceExtractorContext } from "./types.js";
+import type { SourceExtractorRegistry } from "./extractors.js";
+export interface QaSourceCollectorOptions {
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly registry: SourceExtractorRegistry;
+    readonly displayScoreThreshold?: number;
+    readonly mergeFileRanges?: boolean;
+}
+/** Mutable turn-local accumulator; snapshots are immutable plain data. */
+export declare class QaSourceCollector {
+    private readonly options;
+    private readonly collected;
+    private readonly incompleteOrigins;
+    private readonly threshold;
+    constructor(options: QaSourceCollectorOptions);
+    observe(context: SourceExtractorContext): void;
+    add(sources: readonly QaSourceReference[]): void;
+    markIncomplete(origin: {
+        readonly subagentRunId?: string;
+        readonly provider?: string;
+        readonly reason: string;
+    }): void;
+    snapshot(): QaTurnSources;
+}
+//# sourceMappingURL=collector.d.ts.map

package/lib/types/provenance/connectors.d.ts

@@ -0,0 +1,11 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { SourceExtractor } from "./types.js";
+type UrlOptions = Parameters<typeof canonicalizeUrl>[1];
+export declare function createJiraExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare function createConfluenceExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare function createKnowledgeExtractor(urlOptions?: UrlOptions): SourceExtractor;
+export declare const jiraExtractor: SourceExtractor;
+export declare const confluenceExtractor: SourceExtractor;
+export declare const knowledgeExtractor: SourceExtractor;
+export {};
+//# sourceMappingURL=connectors.d.ts.map

package/lib/types/provenance/dedupe.d.ts

@@ -0,0 +1,6 @@
+import type { QaSourceReference } from "./types.js";
+/** Merge by canonical id and rank by score, preserving first-use order on ties. */
+export declare function dedupeAndRankSources(sources: readonly QaSourceReference[], options?: {
+    readonly mergeFileRanges?: boolean;
+}): readonly QaSourceReference[];
+//# sourceMappingURL=dedupe.d.ts.map

package/lib/types/provenance/extractors.d.ts

@@ -0,0 +1,14 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { QaSourceReference, SourceExtractor, SourceExtractorContext } from "./types.js";
+export declare const readFileExtractor: SourceExtractor;
+export declare function createWebSearchExtractor(maxPromotedPerSearch?: number, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractor;
+export declare function createWebFetchExtractor(urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractor;
+export declare const webFetchExtractor: SourceExtractor;
+export declare const fileSearchExtractor: SourceExtractor;
+export declare class SourceExtractorRegistry {
+    private readonly extractors;
+    register(extractor: SourceExtractor): () => void;
+    extract(context: SourceExtractorContext): readonly QaSourceReference[];
+}
+export declare function createDefaultSourceExtractorRegistry(maxPromotedPerSearch?: number, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): SourceExtractorRegistry;
+//# sourceMappingURL=extractors.d.ts.map

package/lib/types/provenance/file-preview.d.ts

@@ -0,0 +1,10 @@
+import type { QaSourceFilePreview } from "../types.js";
+export interface QaSourceFilePreviewOptions {
+    readonly root: string;
+    readonly sourcePath: string;
+    readonly maxBytes: number;
+    readonly maxMarkdownRenderBytes: number;
+}
+/** Read one canonical in-root file without following a symlink outside root. */
+export declare function readSourceFilePreview({ root, sourcePath, maxBytes, maxMarkdownRenderBytes, }: QaSourceFilePreviewOptions): Promise<QaSourceFilePreview>;
+//# sourceMappingURL=file-preview.d.ts.map

package/lib/types/provenance/host-store.d.ts

@@ -0,0 +1,54 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaTurnSources } from "./types.js";
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+export declare const QA_REPORT_SOURCES_TOOL = "qa_report_sources";
+declare module "@deepseek-ai/dsh-session" {
+    interface SessionEventMap {
+        "qa/sources": QaTurnSources;
+    }
+}
+interface SubagentInfo {
+    readonly runId: string;
+    readonly provider: string;
+    readonly id: string;
+    readonly local: boolean;
+}
+declare module "@deepseek-ai/cordis" {
+    interface Events {
+        "subagent/start"(info: SubagentInfo): void;
+        "subagent/end"(info: SubagentInfo): void;
+    }
+}
+/** Host authority for collection, replay, delegation inheritance and snapshots. */
+export declare class QaProvenanceHost {
+    private readonly ctx;
+    private readonly config;
+    private readonly collectors;
+    private readonly snapshots;
+    private readonly calls;
+    private readonly lineage;
+    private readonly disposers;
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig);
+    dispose(): void;
+    /**
+     * Drop every per-session record of one chat. Long-lived servers outlive
+     * their sessions by weeks; without this the collector, snapshot, call and
+     * lineage maps grow with every chat and turn forever.
+     */
+    private forget;
+    private forgetAll;
+    bundles(sessionId: string): readonly QaTurnSources[];
+    sourceAllowed(sessionId: string, path: string): boolean;
+    private seed;
+    private observeEvent;
+    private shouldCollect;
+    private materialize;
+    private startSubagent;
+    private endSubagent;
+    private registerReportTool;
+    private collector;
+    private sessionCalls;
+    private sessionSnapshots;
+}
+export {};
+//# sourceMappingURL=host-store.d.ts.map

package/lib/types/provenance/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./collector.js";
+export * from "./connectors.js";
+export * from "./dedupe.js";
+export * from "./extractors.js";
+export * from "./file-preview.js";
+export * from "./host-store.js";
+export * from "./normalize.js";
+export * from "./reported.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/types/provenance/normalize.d.ts

@@ -0,0 +1,13 @@
+import type { QaSourceLocation } from "./types.js";
+/** Strip model-added XML-like wrappers without interpreting arbitrary prose. */
+export declare function unwrapSourceTarget(value: string): string;
+/** Canonical HTTP(S) identity while retaining business-relevant parameters. */
+export declare function canonicalizeUrl(value: string, options?: {
+    readonly normalize?: boolean;
+    readonly stripTrackingParams?: boolean;
+}): string | null;
+/** Normalize separators and, when possible, make a path workspace-relative. */
+export declare function canonicalizeWorkspacePath(value: string, workspaceRoot?: string): string;
+/** Union exact anchors and compact overlapping or adjacent ranges. */
+export declare function compactLocations(locations: readonly QaSourceLocation[]): readonly QaSourceLocation[];
+//# sourceMappingURL=normalize.d.ts.map

package/lib/types/provenance/reported.d.ts

@@ -0,0 +1,5 @@
+import { canonicalizeUrl } from "./normalize.js";
+import type { QaReportedSource, QaSourceOrigin, QaSourceReference } from "./types.js";
+/** Normalize a source explicitly reported by a delegated provider. */
+export declare function normalizeReportedSource(source: QaReportedSource, origin: QaSourceOrigin, workspaceRoot?: string, urlOptions?: Parameters<typeof canonicalizeUrl>[1]): QaSourceReference | null;
+//# sourceMappingURL=reported.d.ts.map

package/lib/types/provenance/types.d.ts

@@ -0,0 +1,78 @@
+export type QaSourceKind = "file" | "code" | "web" | "jira" | "confluence" | "knowledge" | "other";
+export type QaSourceEvidence = "read" | "fetched" | "queried" | "reported" | "inherited" | "discovered";
+export type QaSourceMetadataValue = string | number | boolean | null | readonly QaSourceMetadataValue[] | {
+    readonly [key: string]: QaSourceMetadataValue;
+};
+export interface QaSourceMetadata {
+    readonly [key: string]: QaSourceMetadataValue;
+}
+export interface QaSourceLocation {
+    readonly path?: string;
+    readonly lineStart?: number;
+    readonly lineEnd?: number;
+    readonly anchor?: string;
+    readonly jiraKey?: string;
+    readonly confluencePageId?: string;
+}
+export interface QaSourceOrigin {
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly step?: number;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly agentId?: string;
+    readonly role: "parent" | "subagent";
+    readonly subagentRunId?: string;
+    readonly subagentSessionId?: string;
+}
+export interface QaSourceReference {
+    /** Stable identity after path, URL or provider-specific normalization. */
+    readonly id: string;
+    readonly kind: QaSourceKind;
+    readonly title: string;
+    readonly uri?: string;
+    readonly path?: string;
+    readonly snippet?: string;
+    readonly locations: readonly QaSourceLocation[];
+    readonly evidence: QaSourceEvidence;
+    readonly origins: readonly QaSourceOrigin[];
+    readonly score: number;
+    readonly metadata?: QaSourceMetadata;
+}
+export interface QaTurnSources {
+    readonly version: 1;
+    readonly sessionId: string;
+    readonly turn: number;
+    readonly sources: readonly QaSourceReference[];
+    readonly discovered?: readonly QaSourceReference[];
+    readonly complete: boolean;
+    readonly incompleteOrigins?: readonly {
+        readonly subagentRunId?: string;
+        readonly provider?: string;
+        readonly reason: string;
+    }[];
+}
+export interface SourceExtractorContext {
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly result: unknown;
+    readonly presentation?: unknown;
+    readonly origin: QaSourceOrigin;
+    /** Canonical session/workspace root used to make local paths portable. */
+    readonly workspaceRoot?: string;
+}
+export interface QaReportedSource {
+    readonly kind: QaSourceKind;
+    readonly title: string;
+    readonly uri?: string;
+    readonly path?: string;
+    readonly snippet?: string;
+    readonly locations?: readonly QaSourceLocation[];
+    readonly metadata?: QaSourceMetadata;
+}
+export interface SourceExtractor {
+    readonly id: string;
+    matches(context: SourceExtractorContext): boolean;
+    extract(context: SourceExtractorContext): readonly QaSourceReference[];
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/secure-session.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaLockdownProof, ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * The accounts half of admission, resolved per call by the entry (accounts
+ * may be toggled at runtime). A gate must either accept the token/session
+ * pair or throw the coarse `QaAttestationError`; see {@link QaAccounts}.
+ */
+export interface QaAccountsGate {
+    enforceSessionAccess(token: string, sessionId: string): void;
+}
+/**
+ * Host-side QA policy admission boundary — the only browser-callable operation
+ * that turns a session into a locked QA session. It verifies the immutable
+ * session composition against the effective deployment config, refuses to
+ * adopt a non-QA session with user history, validates the named permission
+ * preset, pins the scoped tool restriction plus the monotonic execution guard,
+ * and returns a sanitized proof. Every refusal carries only a coarse reason.
+ */
+export declare class QaPolicyAdmission {
+    private readonly ctx;
+    private readonly config;
+    private readonly logger;
+    private readonly accounts?;
+    private readonly appliedPolicies;
+    constructor(ctx: Context, config: () => ResolvedQaSurfaceConfig, logger: PluginLogger, accounts?: QaAccountsGate | undefined);
+    secureSession(token: string, sessionId: string): QaLockdownProof;
+    /** Detach every pinned tool policy; wired as a disposal effect by the entry. */
+    dispose(): void;
+}
+//# sourceMappingURL=secure-session.d.ts.map