@sparkelf/dsh-knowledge-base 0.1.5 → 0.1.20

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

@@ -13,25 +13,43 @@
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 import { type KnowledgeKey } from './locales.ts';
+import { type WorkflowPlazaInjected } from './workflows/WorkflowPlaza.tsx';
 declare module '@deepseek-ai/dsh-client-ui-slots' {
     interface LocaleNamespaceMap {
         'settings.knowledgeBase': KnowledgeKey;
     }
+    /**
+     * The workflow-plaza seat inside the automation-task page.
+     *
+     * That page belongs to `ui-schedule`, which this plugin cannot extend at build time
+     * (the running Host ships it as a built bundle). The seat is declared here as a
+     * type-level contract and contributed at runtime: if the deployed page does not
+     * declare the child slot, the registration simply never renders, and every other
+     * knowledge surface is unaffected.
+     *
+     * `single` = one tab id shows one body; `root` = the task page is root-scoped and a
+     * plaza belongs to no Session.
+     */
+    interface SlotMap {
+        'schedule.manager.tabs': {
+            kind: 'single';
+            scope: 'root';
+            owner: Record<string, never>;
+            hookContext: unknown;
+            inject: WorkflowPlazaInjected;
+        };
+        /**
+         * Header actions contributed by another plugin (the DataOps notification bell).
+         * This plugin declares and renders the seat; it never imports the contributor.
+         */
+        'workflow-plaza.actions': {
+            kind: 'single';
+            scope: 'root';
+            owner: Record<string, never>;
+            hookContext: unknown;
+        };
+    }
 }
-/**
- * Client services required for these contributions.
- *
- * `sessions` and `workspaces` are here because the `@`-reference dialog inserts into a
- * conversation draft, and that insert resolves the target session's scope through
- * `ctx.sessions` before it can write anything. Without the injection the service is not
- * on this plugin's ctx at all: the call throws `cannot get property "sessions" without
- * inject`, `referenceInChat` catches it into a `console.warn`, and the reader sees a
- * dialog that closes and inserts nothing -- the exact "clicked, nothing happened"
- * symptom this injection fixes at the root rather than by reporting the failure.
- *
- * `workspaces` is the other half: the mention is spelled relative to the workspace that
- * owns the session, so the insert needs that root to project the path.
- */
 export declare const inject: string[];
 /**
  * Register the knowledge-base navigation entry and Settings section.

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

@@ -0,0 +1,58 @@
+/**
+ * In-place narrowing of a listing by row name.
+ *
+ * Kept as a pure function, out of the component, because the component cannot be mounted
+ * in a unit test (it pulls the UI primitives and the workspace path helpers) and the rules
+ * below are the part that is easy to get wrong: case folding, substring vs prefix, and —
+ * most of all — keeping a hit reachable from the root.
+ *
+ * @module dsh-better-sidebar/client/listing-filter
+ */
+/**
+ * The little a row must expose to be filtered.
+ *
+ * Only the NAME is required: callers key their rows differently (the explorer by absolute
+ * path), so the child lookup is passed in as {@link childrenOf} rather than assumed to be
+ * a field name.
+ */
+export interface FilterableEntry {
+    /** Base name, what the reader scans. */
+    name: string;
+    /** Whether the row opens a level. */
+    isDir: boolean;
+}
+/** Resolve one directory row's loaded children, if that level has been read. */
+export type ChildrenOf<T extends FilterableEntry> = (entry: T) => readonly T[] | undefined;
+/**
+ * Whether a name matches the reader's term.
+ *
+ * Substring, case-insensitive, on the NAME only: this is the tree's in-place narrowing,
+ * and reading file bodies is what the cross-directory search is for.
+ * @param name - the row's base name.
+ * @param needle - the term, already trimmed and lower-cased by {@link normaliseNeedle}.
+ * @returns Whether the row itself matches.
+ */
+export declare function nameMatches(name: string, needle: string): boolean;
+/**
+ * Prepare the reader's raw input for matching.
+ *
+ * Trimmed because a trailing space is invisible and would otherwise make every term match
+ * nothing; lower-cased once here rather than once per row.
+ * @param raw - what the field holds.
+ * @returns The term to compare against.
+ */
+export declare function normaliseNeedle(raw: string): string;
+/**
+ * Narrow one level, recursively, keeping every hit reachable.
+ *
+ * A directory is kept when it matches, when anything under it matches, or when an ANCESTOR
+ * matched — the last case is what makes typing a folder name show the folder's contents
+ * instead of an empty row. A deeply nested hit therefore drags its whole chain with it,
+ * which is the only way a file inside a collapsed folder can be seen.
+ * @param rows - this level's rows, in display order.
+ * @param childrenOf - one directory row's loaded children; `undefined` means "not loaded".
+ * @param needle - the term, already normalised.
+ * @param withinMatch - whether an ancestor already matched the term.
+ * @returns The rows to draw at this level.
+ */
+export declare function filterLevel<T extends FilterableEntry>(rows: readonly T[], childrenOf: ChildrenOf<T>, needle: string, withinMatch?: boolean): T[];

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

@@ -14,6 +14,8 @@ export declare const en: {
     readonly storageModeIntro: "Storage location";
     readonly storageModeLocal: "Local";
     readonly storageModeRemote: "Remote (NFS)";
+    readonly storageRoot: "Knowledge storage path";
+    readonly storageRootHint: "Authoritative directory (default ~/kb). Each workspace gets a .kb view of hardlinks; the two paths must be on the same filesystem.";
     readonly storageModeLocalHint: "Stored in the workspace. No mount or sync.";
     readonly storageModeRemoteHint: "Documents live in a shared NFS view that is synchronized from the authoritative tree. Requires a mount and a storage host.";
     readonly connection: "Connection";
@@ -342,10 +344,94 @@ export declare const en: {
     readonly 'step.sshfs-mount': "Mount the share over SSHFS";
     readonly 'step.sshfs-verify': "Verify the SSHFS mount";
     readonly deployLocalOnly: "Deployment steps run on a remote host. This workspace stores documents locally, so there is nothing to deploy.";
+    readonly sortByMtime: "By modified time";
+    readonly sortByName: "By name";
+    readonly sortBySize: "By size";
+    readonly sortByType: "By type";
+    readonly sortHeading: "Sort";
+    readonly filterHeading: "Filter";
+    readonly actionSortAndFilter: "Sort and filter";
+    readonly progressAlreadyMarkdown: "Already Markdown — no extraction needed";
+    readonly colActions: "Actions";
+    readonly progressIdle: "Nothing is uploading or extracting right now.";
+    readonly progressBadge: "{n} pending";
+    readonly progressBadgeMore: "99+";
+    readonly progressOpen: "Upload and extraction progress";
+    readonly progressClose: "Close";
     readonly dropRefusedNoCaller: "Cannot place this upload";
     readonly dropRefusedNoCallerReason: "The host has not reported your account yet, so the personal folder cannot be resolved. Reload and try again.";
     readonly progressResize: "Drag to resize";
     readonly shareEmpty: "Nothing has been shared yet.";
+    readonly workflowPlaza: "Workflow plaza";
+    readonly workflowPlazaTab: "Plaza";
+    readonly workflowReviewTab: "Review";
+    readonly workflowReviewEmpty: "No workflows waiting for review.";
+    readonly workflowReviewLoading: "Loading review queue…";
+    readonly workflowReviewFailed: "Review action failed; try again.";
+    readonly workflowReviewAuthor: "Author";
+    readonly workflowReviewCreated: "Submitted";
+    readonly workflowReviewPrompt: "View prompt";
+    readonly workflowReviewNote: "Rejection reason (optional)";
+    readonly workflowReviewApprove: "Approve";
+    readonly workflowReviewReject: "Reject";
+    readonly workflowMineTab: "My shared";
+    readonly workflowMineEmpty: "You have not shared a workflow yet.";
+    readonly workflowMineUpdated: "Updated";
+    readonly workflowMineReviewNote: "Review note";
+    readonly workflowMineResubmit: "Resubmit";
+    readonly workflowMineUnpublish: "Unpublish";
+    readonly workflowMineDetails: "View details";
+    readonly workflowMineActionFailed: "Action failed; try again.";
+    readonly workflowMineStatusPending: "In review";
+    readonly workflowMineStatusApproved: "Shared";
+    readonly workflowMineStatusRejected: "Rejected";
+    readonly workflowMineStatusUnpublished: "Unpublished";
+    readonly workflowMineScopeGlobal: "Global";
+    readonly workflowMineScopePrivate: "Private";
+    readonly workflowMineScopeDepartment: "{name} department";
+    readonly workflowSubscribe: "Subscribe";
+    readonly workflowSubscribed: "Subscribed";
+    readonly workflowUnsubscribe: "Unsubscribe";
+    readonly workflowFrequency: "Frequency";
+    readonly workflowModel: "Model";
+    readonly workflowModelLoading: "Loading models…";
+    readonly workflowModelUnavailable: "Default model (catalog unavailable)";
+    readonly workflowModelDefault: "Workspace default model";
+    readonly workflowEffort: "Reasoning effort";
+    readonly workflowDaily: "Daily";
+    readonly workflowWeekly: "Weekly";
+    readonly workflowMonthly: "Monthly";
+    readonly workflowCustom: "Custom";
+    readonly workflowEveryHours: "Every N hours";
+    readonly workflowEveryMinutes: "Every N minutes";
+    readonly workflowHoursCount: "Hours";
+    readonly workflowMinutesCount: "Minutes";
+    readonly workflowIntervalInvalid: "Enter a whole number between {min} and {max}";
+    readonly workflowIntervalUnitHours: "hour(s)";
+    readonly workflowIntervalUnitMinutes: "minute(s)";
+    readonly workflowCronLabel: "Cron expression";
+    readonly workflowCronInvalid: "Enter a 5-field cron (minute hour day month weekday)";
+    readonly workflowSubscribing: "Subscribing…";
+    readonly workflowSubscribeFailed: "Subscribe failed: {reason}";
+    readonly workflowNoSchedules: "No workflows subscribed yet";
+    readonly workflowDialogTitle: "Subscribe to this workflow";
+    readonly workflowDialogConfirm: "Create task";
+    readonly workflowDialogCancel: "Cancel";
+    readonly workflowRetry: "Retry";
+    readonly workflowAlreadySubscribed: "Already subscribed";
+    readonly workflowOrganizeTitle: "Tidy up my personal knowledge base";
+    readonly workflowOrganizeDescription: "Groups personal documents into topic folders and writes an index for each level, so the bucket stays readable as it grows.";
+    readonly workflowIndexTitle: "Tidy document text copies";
+    readonly workflowIndexDescription: "Scans personal documents and fills in the Markdown text copies that are still missing, so every file can be read as text.";
+    readonly workflowArchiveTitle: "Archive stale personal documents";
+    readonly workflowArchiveDescription: "Moves documents untouched for 90 days into an Archive folder and marks them as archived in the index.";
+    readonly workflowTaskDetail: "Task detail";
+    readonly workflowReasonAlready: "this workflow already has a task";
+    readonly workflowReasonModel: "the selected model is unavailable — choose another model";
+    readonly workflowReasonSession: "the session ended with an error — open it to see the reason";
+    readonly workflowReasonPrompt: "the instruction could not be sent";
+    readonly workflowReasonNotCreated: "the task has not appeared yet — it may still be creating; refresh in a moment";
+    readonly workflowReasonCancel: "the task could not be removed";
     readonly shareGroupReceived: "Inbound";
     readonly shareGroupGiven: "Outbound";
     readonly shareColRelation: "Sharing";
@@ -396,9 +482,16 @@ export declare const en: {
     readonly progressUploading: "Uploading {done}/{total}";
     readonly progressPending: "Queued";
     readonly progressExtracting: "Extracting";
+    readonly progressStepParse: "Parsing document";
+    readonly progressStepChunk: "Chunking text";
+    readonly progressStepIndex: "Writing FTS5 index";
+    readonly progressStepDone: "Finishing";
     readonly progressExtractingVia: "Extracting ({via})";
     readonly progressSucceeded: "Done";
     readonly progressFailed: "Failed: {reason}";
+    readonly progressFailedTitle: "Failed";
+    readonly progressRawReason: "Raw error: {reason}";
+    readonly extractReasonMissingFile: "The source file no longer exists or has moved";
     readonly progressUnsupported: "This file type has no extractor";
     readonly progressRetry: "Retry";
     readonly progressCollapse: "Collapse";
@@ -417,7 +510,33 @@ export declare const en: {
     readonly settingsMineruHint: "Where documents are parsed. Leave it empty to use the port this deployment was configured with.";
     readonly settingsMineruPlaceholder: "Leave empty to derive from the configured port";
     readonly settingsMineruDerived: "Currently derived from the configured port.";
+    readonly vectorHeading: "Vector retrieval";
+    readonly vectorHint: "Optional hybrid recall: FTS remains active; vectors only add semantic candidates. When disabled, search behaviour is unchanged and no embedding provider is called.";
+    readonly vectorEnabled: "Enable vector retrieval";
+    readonly vectorEnabledOn: "On: FTS and vector candidates are fused with RRF.";
+    readonly vectorEnabledOff: "Off: pure FTS, no embedding calls.";
+    readonly vectorProvider: "Provider";
+    readonly vectorBaseUrl: "Base URL";
+    readonly vectorModel: "Embedding model";
+    readonly vectorDimensions: "Dimensions";
+    readonly vectorCredentialRef: "API key credential reference";
+    readonly vectorCredentialHint: "A credential name only; the key is never stored or shown here.";
+    readonly vectorRrfK: "RRF k";
+    readonly vectorCandidateK: "Candidate K";
+    readonly vectorWeights: "RRF weights (FTS / vector)";
+    readonly vectorFtsWeight: "FTS weight";
+    readonly vectorVectorWeight: "Vector weight";
+    readonly vectorWeightsHint: "FTS weight 1.0 and vector weight 0.5 by default. Vector-only hits cannot outrank strong FTS hits.";
+    readonly vectorCoverage: "Embedded {embedded} / {total} chunks; failed {failed}.";
+    readonly vectorProgress: "Vectorizing {done} / {total} documents...";
+    readonly vectorRebuild: "Rebuild vector index";
+    readonly vectorRebuildHint: "Whole-library rebuild; asks for confirmation. Use kb-vectorize for one document or directory.";
+    readonly vectorRebuildConfirm: "Rebuild vectors for the whole knowledge base? This calls the embedding provider for every current chunk.";
+    readonly vectorBadNumber: "Vector settings contain an invalid number.";
     readonly settingsMineruExplicit: "Currently using the address above.";
+    readonly settingsMineruShared: "Currently using the address the 「Document recognition」 plugin configured for this deployment.";
+    readonly settingsMineruNone: "No parser address is available. Ask an administrator to configure one in 「Document recognition」.";
+    readonly settingsMineruSharedInvalid: "The address saved here is not a valid address, so a fallback is in use.";
     readonly settingsSave: "Save";
     readonly settingsSaving: "Saving…";
     readonly ownerGlobal: "Everyone";
@@ -485,6 +604,10 @@ export declare const en: {
     readonly createDestinationPicker: "Location";
     readonly createDestination: "Destination";
     readonly createAtRoot: "Top level";
+    readonly createStepBack: "Back";
+    readonly createDropTitle: "Drop files here, or click to choose";
+    readonly createSelectedCount: "Selected {n} files";
+    readonly createRemoveFile: "Remove {name}";
     readonly createAtUp: "Up one level";
     readonly createLoading: "Loading folders…";
     readonly createNoSubfolders: "No folders inside this one.";

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

@@ -23,7 +23,7 @@
  * @module @sparkelf/dsh-knowledge-base/client
  */
 /** Outcome of asking the host to show a document. */
-export type OpenOutcome = 'opened' | 'no-context' | 'no-registry' | 'unclaimed' | 'no-column';
+export type OpenOutcome = 'opened' | 'no-seat' | 'no-context' | 'no-registry' | 'unclaimed' | 'no-column';
 /**
  * Ask the host to open a document in its right-hand file window.
  *
@@ -35,7 +35,7 @@ export type OpenOutcome = 'opened' | 'no-context' | 'no-registry' | 'unclaimed'
  * @returns Why it did or did not open; the caller reports the failure rather than
  *   appearing to do nothing.
  */
-export declare function openInSidebar(ctx: unknown, sessionId: string | undefined, cwd: string | undefined, absolutePath: string): OpenOutcome;
+export declare function openInSidebar(ctx: unknown, sessionId: string | undefined, cwd: string | undefined, absolutePath: string, ensureSession?: () => Promise<string | undefined>): Promise<OpenOutcome>;
 /**
  * Return the right column's width to the page.
  *

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

@@ -35,20 +35,201 @@ export declare function failureReason(body: {
     error?: unknown;
     code?: unknown;
 } | undefined, status: number): string;
-/** The strip's height bounds, in pixels. */
-export declare const PROGRESS_MIN_HEIGHT = 44;
-export declare const PROGRESS_DEFAULT_HEIGHT = 180;
-/** The share of the panel's height the strip may take, leaving the tree the rest. */
-export declare const PROGRESS_MAX_SHARE = 0.6;
-/**
- * Clamp a dragged height into the strip's legal range.
- *
- * The upper bound is a share of the PANEL, not a constant: the strip must never grow
- * until the file tree is unreachable, and how much room that is depends on how tall the
- * panel currently is. A 600px panel and a 1200px panel therefore allow different
- * maximums, which is what keeps the tree visible on both.
- * @param desired - the height the pointer asked for.
- * @param panelHeight - the panel's own height, when known.
- * @returns The height to use.
- */
-export declare function clampProgressHeight(desired: number, panelHeight: number | undefined): number;
+/** How a group of tasks breaks down, with every task counted exactly once. */
+export interface TaskTally {
+    /** Tasks that produced what the reader asked for. */
+    done: number;
+    /** Tasks that ended without producing it, for any reason. */
+    failed: number;
+    /** Tasks inside an unsupported format, kept apart from ordinary failures. */
+    unsupported: number;
+    /** Tasks still queued or running. */
+    active: number;
+    /** Every task in the group. */
+    total: number;
+}
+/**
+ * Count a group of extraction tasks.
+ *
+ * The invariant this exists for: `done + failed + active === total`. A tally that drops a
+ * state makes the summary read "0 extracted, 0 failed" beside a list holding one row --
+ * the reader sees a task that neither succeeded nor failed and has no way to learn what
+ * happened to it.
+ *
+ * `unsupported` is counted in BOTH its own field and in `failed`. The two audiences are
+ * different: the summary groups it with failures (a reader who did not get their Markdown
+ * does not care why), while the row still says "this file type has no extractor", which is
+ * where the specific reason belongs.
+ * @param tasks - the tasks to count.
+ * @returns The breakdown.
+ */
+export declare function tallyExtraction(tasks: readonly {
+    state: string;
+}[]): TaskTally;
+/**
+ * Count a group of upload tasks.
+ *
+ * Same invariant as {@link tallyExtraction}, for the upload batch: every row is exactly
+ * one of done, failed, or still in flight.
+ * @param tasks - the upload rows.
+ * @returns The breakdown.
+ */
+export declare function tallyUploads(tasks: readonly {
+    state: string;
+}[]): TaskTally;
+/** One upload row, as the notification panel shows it. */
+export interface UploadTaskView {
+    /** The file's path relative to the drop target: the name the reader dropped. */
+    name: string;
+    /** The tree-relative directory it is landing in, `''` for the mount root. */
+    dir: string;
+    /** Where this file is in its own lifecycle. */
+    state: 'waiting' | 'uploading' | 'done' | 'failed';
+    /** Why it failed, in the Host's own words. */
+    reason?: string;
+    /**
+     * Bytes sent, as 0-100.
+     *
+     * Absent while the browser cannot know it (a body without a known length) and on every
+     * settled row: a percentage that never moves, or a track left behind after completion,
+     * both claim something that is not true.
+     */
+    percent?: number;
+}
+/**
+ * How many tasks are still worth the reader's attention.
+ *
+ * This is the notification badge's number: uploads that have not settled, plus extractions
+ * the Host is still queued on or running. Settled work is deliberately excluded -- a badge
+ * that still shows a count after everything finished trains the reader to ignore it, and
+ * the reason to open the panel is then gone.
+ *
+ * `unsupported` is settled too: no extractor exists for that format, so waiting on it
+ * would leave the badge lit forever.
+ * @param uploads - the current upload batch.
+ * @param extractions - the extraction tasks the Host reports.
+ * @returns The number of tasks still in flight.
+ */
+export declare function pendingCount(uploads: readonly {
+    state: string;
+}[], extractions: readonly {
+    state: string;
+}[]): number;
+/**
+ * How long an optimistic extraction entry may wait for the Host to confirm it.
+ *
+ * A request can fail in ways the browser never reports (a dropped connection, a proxy that
+ * swallows the body), so an entry added on click must expire on its own. Thirty seconds is
+ * longer than a healthy `extract.status` round trip and short enough that a reader is not
+ * left staring at a task that will never exist.
+ */
+export declare const OPTIMISTIC_TTL_MS = 30000;
+/**
+ * One row the reader asked for that the Host has not reported back yet.
+ *
+ * Kept separate from `ExtractionTaskView` on purpose: a server task has an authoritative
+ * state, and this has only a request that was sent. Merging them would let a guess outlive
+ * the truth.
+ */
+export interface OptimisticExtraction {
+    /** The document the reader asked to extract. */
+    relPath: string;
+    /** When the request was issued, in milliseconds. */
+    requestedAt: number;
+}
+/**
+ * Whether an optimistic entry is still waiting for the Host to mention it.
+ * @param entry - the pending request.
+ * @param now - the current time in milliseconds.
+ * @returns Whether it is still within its lifetime.
+ */
+export declare function optimisticAlive(entry: OptimisticExtraction, now: number): boolean;
+/**
+ * The entries the panel should still show as "queued".
+ *
+ * An entry is dropped for either of two reasons, and the distinction matters to the reader:
+ *
+ * - the Host has reported that document, so the authoritative row replaces the guess;
+ * - it has been waiting longer than {@link OPTIMISTIC_TTL_MS}, so the task was never
+ *   created and the panel has to stop claiming otherwise.
+ * @param pending - the optimistic entries.
+ * @param reported - the paths the Host currently reports.
+ * @param now - the current time in milliseconds.
+ * @returns The entries still worth showing.
+ */
+export declare function survivingOptimistic(pending: readonly OptimisticExtraction[], reported: readonly {
+    relPath: string;
+}[], now: number): OptimisticExtraction[];
+/**
+ * The rows the panel draws, with optimistic entries folded in.
+ *
+ * A path the Host reports ALWAYS wins: the guess exists only to cover the gap before the
+ * first `extract.status` answer, and showing both would read as two tasks.
+ * @param reported - what the Host reports, in its own order.
+ * @param pending - the optimistic entries, oldest first.
+ * @param now - the current time in milliseconds.
+ * @returns One row per document, plus the rows only the guest knows about.
+ */
+export declare function mergeOptimistic<T extends {
+    relPath: string;
+}>(reported: readonly T[], pending: readonly OptimisticExtraction[], now: number): {
+    rows: T[];
+    queued: OptimisticExtraction[];
+};
+/**
+ * Turn a failed extraction request into a sentence a reader can act on.
+ *
+ * The menu's entry used to discard the response entirely, which is why a failed click
+ * looked identical to a successful one. Each status here means something different about
+ * what to do next, so they are not collapsed into "failed".
+ * @param status - the HTTP status, or 0 when the request never completed.
+ * @param body - the parsed body, when it was JSON.
+ * @returns A reason for the reader.
+ */
+export declare function extractionFailureReason(status: number, body: {
+    error?: unknown;
+    message?: unknown;
+} | undefined): string;
+/** A failed extraction the panel knows about even when the Host has no task for it. */
+export interface FailedExtractionView {
+    /** Knowledge-relative path of the SOURCE document, as the request named it. */
+    relPath: string;
+    /** The raw reason, exactly as the Host or the transport reported it. */
+    reason: string;
+    /** When the failure was observed, in milliseconds. */
+    at: number;
+}
+/** Why an extraction produced nothing, as far as the reader is concerned. */
+export type ExtractionFailureKind = 
+/** The source document is no longer at the path the tree showed. */
+'missing-file'
+/** Anything else: keep the Host's own wording. */
+ | 'other';
+/**
+ * Classify one raw extraction failure.
+ *
+ * The Host answers `no such file` when the authoritative path it was given has no file.
+ * That string is the server's own words, not a sentence a reader can act on, so it is
+ * the one case with a dedicated translation; every other reason is shown verbatim
+ * because inventing a friendlier sentence for an unknown failure would hide the detail
+ * the operator needs.
+ * @param reason - the raw reason from the Host or transport.
+ * @returns The kind the UI maps to localized copy.
+ */
+export declare function classifyExtractionFailure(reason: string): ExtractionFailureKind;
+/**
+ * The client-side failure rows the panel should draw.
+ *
+ * A path the Host already reports always wins: after a retry the Host's own task is the
+ * authority, and showing both would read as two failures for one document. The same rule
+ * applies to a queued guess -- the click is newer than the recorded failure.
+ * @param reported - the tasks the Host reports.
+ * @param failures - the session's recorded request failures.
+ * @param queued - optimistic entries still waiting for the Host.
+ * @returns One row per document that only the client knows failed.
+ */
+export declare function survivingClientFailures<T extends {
+    relPath: string;
+}>(reported: readonly T[], failures: readonly FailedExtractionView[], queued: readonly {
+    relPath: string;
+}[]): FailedExtractionView[];

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

@@ -0,0 +1,20 @@
+/**
+ * Remove knowledge-explorer tabs that were persisted with the old placeholder id.
+ *
+ * Earlier builds let `@kb-explorer` reach a session-scoped sidebar tab address. The
+ * tab was stored in the browser's per-session layout; after the placeholder was
+ * removed from the open path, the old tab still made the restored sidebar resolve a
+ * non-existent Session. This one-way migration drops only those tab records. Host fs
+ * routes still use the placeholder key and are untouched.
+ */
+/**
+ * Remove persisted sidebar layouts that contain the retired explorer placeholder.
+ *
+ * Called once when the knowledge plugin activates. It is deliberately narrow: only
+ * tab records carrying a `session/@kb-explorer/` address are removed; all other tabs
+ * and per-session layout data survive byte-for-byte when nothing matches.
+ *
+ * @param storage - localStorage-like store, injectable for tests.
+ * @returns how many storage keys were rewritten or removed.
+ */
+export declare function sanitizeExplorerTabs(storage?: Pick<Storage, 'length' | 'key' | 'getItem' | 'setItem' | 'removeItem'> | undefined): number;

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

@@ -0,0 +1,65 @@
+/**
+ * Visibility gate for the knowledge-base Settings section.
+ *
+ * The Settings surface is an operator tool, not a reader feature: only the
+ * DataOps platform administrator roles may see it. The gate is deliberately a
+ * separate module so the rule and the register/dispose lifecycle can be tested
+ * without mounting React or a slot registry.
+ *
+ * The identity is presentation-only (`window.__DATAOPS_USER__`), posted by the
+ * portal. Authorization for actual writes still lives in DataOps; hiding the
+ * section is representation, and the Host routes refuse unauthorized callers
+ * independently.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/settingsGate
+ */
+/** The event the account plugin dispatches after replacing `__DATAOPS_USER__`. */
+export declare const DATAOPS_ACCOUNT_CHANGED_EVENT = "dataops-account:changed";
+/** Roles that may see and use the knowledge-base Settings section. */
+export declare const KNOWLEDGE_SETTINGS_ROLES: readonly ["超级管理员", "管理员"];
+/** The presentation identity fields this gate reads. */
+export interface SettingsIdentityLike {
+    readonly name?: string | null;
+}
+/** The window surface the gate reads and subscribes to. */
+export interface SettingsWindowLike {
+    readonly __DATAOPS_USER__?: SettingsIdentityLike | null;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/** Exactly the two DataOps platform roles; department admins are excluded. */
+export declare function canSeeKnowledgeSettings(identity: SettingsIdentityLike | null | undefined): boolean;
+/** Register one slot contribution; returns its disposer. */
+export type SettingsRegister = () => () => void;
+/** Options keep the gate injectable for a unit test. */
+export interface SettingsGateOptions {
+    /** Register the section; called only while visible and not already registered. */
+    readonly register: SettingsRegister;
+    /** Read the current identity; defaults to the live window. */
+    readonly readIdentity?: () => SettingsIdentityLike | null | undefined;
+    /** Subscribe to identity changes; defaults to the window event. */
+    readonly subscribe?: (listener: () => void) => () => void;
+    /**
+     * Extra same-tab signal, mirroring the account bridge's dataset write. The event is
+     * the contract; the observer exists because a portal/account bundle can publish the
+     * first identity without dispatching it, and the section must appear on first paint.
+     */
+    readonly observe?: (sync: () => void) => () => void;
+}
+/** A started gate with an explicit sync for tests and account events. */
+export interface SettingsGate {
+    /** Register if allowed and subscribe to future changes. */
+    start(): void;
+    /** Run the visibility rule now; register or dispose as needed. */
+    sync(): void;
+    /** Unsubscribe and dispose any live registration. */
+    stop(): void;
+}
+/**
+ * Build a gate around one slot registration.
+ *
+ * The gate never registers twice: an account event that leaves the role unchanged is
+ * a no-op, and a downgrade disposes the mounted section rather than merely hiding its
+ * controls. That is the "content area must also not render" requirement.
+ */
+export declare function createSettingsGate(options: SettingsGateOptions): SettingsGate;