@sparkelf/dsh-knowledge-base 0.1.0 → 0.1.1

package/lib/index.js

@@ -2130,6 +2130,144 @@ function sshManagerRunner(options) {
 		}
 	};
 }
+/**
+* Create an extraction queue.
+*
+* @param options - the runner and the predicate that decides whether a path has a reader.
+* @returns a queue that runs at most {@link MAX_CONCURRENT_EXTRACTIONS} task at a time.
+*/
+function createExtractionQueue(options) {
+	/** Tasks by source path, in submission order. */
+	const tasks = /* @__PURE__ */ new Map();
+	/** Work waiting for the single worker slot. */
+	const waiting = [];
+	/** Resolvers waiting for the queue to drain. */
+	let idleWaiters = [];
+	/**
+	* Resolvers waiting for ONE path's task to become terminal, keyed by that path.
+	*
+	* Per-task rather than a single queue-wide signal: a retry must not be woken by an
+	* unrelated upload finishing, and a caller that registered a waiter must receive the
+	* terminal state of its own task even if the bound evicts the record afterwards.
+	*/
+	const taskWaiters = /* @__PURE__ */ new Map();
+	let running;
+	let started = false;
+	/** Forget the oldest finished task once the bound is exceeded. */
+	function evictFinished() {
+		if (tasks.size <= 200) return;
+		for (const [relPath, task] of tasks) {
+			if (task.state === "pending" || task.state === "running") continue;
+			tasks.delete(relPath);
+			if (tasks.size <= 200) return;
+		}
+	}
+	/** Resolve everyone waiting on an idle queue. */
+	function settleIdle() {
+		if (running !== void 0 || waiting.length > 0) return;
+		const waiters = idleWaiters;
+		idleWaiters = [];
+		for (const resolve of waiters) resolve();
+	}
+	/** Run one task, recording its terminal state. */
+	async function runOne(item) {
+		const task = tasks.get(item.relPath);
+		if (task === void 0) return;
+		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		task.state = "running";
+		task.startedAt = startedAt;
+		running = item.relPath;
+		try {
+			const outcome = await options.run(item.relPath, item.mineruBaseUrl);
+			task.state = outcome.state;
+			if (outcome.markdown !== void 0) task.markdown = outcome.markdown;
+			if (outcome.via !== void 0) task.via = outcome.via;
+			if (outcome.reason !== void 0) task.reason = outcome.reason;
+		} catch (error) {
+			task.state = "failed";
+			task.reason = error instanceof Error ? error.message : String(error);
+		} finally {
+			task.finishedAt = (/* @__PURE__ */ new Date()).toISOString();
+			running = void 0;
+			const waiters = taskWaiters.get(item.relPath);
+			if (waiters !== void 0) {
+				taskWaiters.delete(item.relPath);
+				const terminal = { ...task };
+				for (const resolve of waiters) resolve(terminal);
+			}
+			evictFinished();
+		}
+	}
+	/** Pull work until the queue is empty, then let idle waiters go. */
+	async function work() {
+		if (started) return;
+		started = true;
+		try {
+			while (waiting.length > 0) {
+				const item = waiting.shift();
+				if (item === void 0) break;
+				if (!tasks.has(item.relPath)) continue;
+				await runOne(item);
+			}
+		} finally {
+			started = false;
+			running = void 0;
+			settleIdle();
+		}
+	}
+	return {
+		enqueue(relPath, mineruBaseUrl) {
+			const existing = tasks.get(relPath);
+			if (existing !== void 0 && (existing.state === "pending" || existing.state === "running")) return { ...existing };
+			const task = {
+				relPath,
+				state: options.isExtractable(relPath) ? "pending" : "unsupported",
+				queuedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			if (task.state === "pending") waiting.push({
+				relPath,
+				...mineruBaseUrl === void 0 ? {} : { mineruBaseUrl }
+			});
+			else {
+				task.reason = "this file type has no extractor";
+				task.finishedAt = task.queuedAt;
+			}
+			tasks.set(relPath, task);
+			evictFinished();
+			if (task.state === "pending") Promise.resolve().then(() => work());
+			return { ...task };
+		},
+		get(relPath) {
+			const task = tasks.get(relPath);
+			return task === void 0 ? void 0 : { ...task };
+		},
+		snapshot() {
+			const visible = [];
+			for (const task of tasks.values()) visible.push({ ...task });
+			return {
+				running,
+				size: waiting.length + (running === void 0 ? 0 : 1),
+				tasks: visible
+			};
+		},
+		settled(relPath) {
+			const task = tasks.get(relPath);
+			if (task === void 0) return Promise.resolve(void 0);
+			if (task.state !== "pending" && task.state !== "running") return Promise.resolve({ ...task });
+			return new Promise((resolve) => {
+				const pending = taskWaiters.get(relPath) ?? [];
+				pending.push((value) => resolve(value));
+				taskWaiters.set(relPath, pending);
+			});
+		},
+		drain() {
+			if (running === void 0 && waiting.length === 0) return Promise.resolve();
+			return new Promise((resolve) => {
+				idleWaiters.push(resolve);
+			});
+		}
+	};
+}
 //#endregion
 //#region src/extract.ts
 /**
@@ -3573,9 +3711,13 @@ async function fetchPrincipals(ctx, config, kind) {
 		const uuid = typeof row.id === "string" ? row.id : void 0;
 		const id = kind === "user" ? uuid : code;
 		if (id === void 0) return void 0;
+		const name = typeof row.displayName === "string" ? row.displayName : typeof row.name === "string" ? row.name : typeof row.username === "string" ? row.username : id;
+		const roleCodes = kind === "user" && Array.isArray(row.roles) ? row.roles.map((role) => role.code).filter((code) => typeof code === "string" && code !== "") : void 0;
 		return {
 			id,
-			label: typeof row.displayName === "string" ? row.displayName : typeof row.name === "string" ? row.name : typeof row.username === "string" ? row.username : id
+			label: name,
+			...kind !== "user" || typeof row.username !== "string" ? {} : { username: row.username },
+			...roleCodes === void 0 ? {} : { roleCodes }
 		};
 	}).filter((row) => row !== void 0);
 }
@@ -3950,6 +4092,42 @@ async function extractBeside(config, relPath, mineruUrl) {
 	};
 }
 /**
+* Translate {@link extractBeside}'s answer into a queue terminal state.
+*
+* The extractor reports three different outcomes through two fields, and they mean
+* different things to a reader deciding what to do next:
+*
+* - `markdown` set, no `reason` — the sibling was written (`succeeded`).
+* - `markdown` set WITH a `reason` — the text was produced but writing the sibling was
+*   refused, typically because it already exists. The reason is kept so a retry can
+*   report why nothing changed (`failed`, with the refusal verbatim).
+* - `markdown` empty, `reason` set — no authority could read the document; this is the
+*   `no-extractor-succeeded: …` case a reader retries after an upgrade.
+*
+* An `undefined` answer means the format has no extractor at all, which the queue
+* normally prevents by asking `isExtractable` first; it is mapped for the caller that
+* bypassed that gate rather than left to throw.
+*
+* @param outcome - what {@link extractBeside} returned.
+* @returns the state the queue records.
+*/
+function extractionOutcomeOf(outcome) {
+	if (outcome === void 0) return {
+		state: "unsupported",
+		reason: "this file type has no extractor"
+	};
+	if (outcome.markdown !== "" && outcome.reason === void 0) return {
+		state: "succeeded",
+		markdown: outcome.markdown,
+		...outcome.via === void 0 ? {} : { via: outcome.via }
+	};
+	return {
+		state: "failed",
+		...outcome.markdown === "" ? {} : { markdown: outcome.markdown },
+		...outcome.reason === void 0 ? {} : { reason: outcome.reason }
+	};
+}
+/**
 * MinerU's base URL for this deployment, or undefined when it is not configured.
 *
 * @param config - resolved plugin config.
@@ -4313,6 +4491,22 @@ function apply(ctx, deploymentConfig) {
 	/** Completed and in-flight step runs, newest last. */
 	const runs = [];
 	/**
+	* Background extraction, one worker for this deployment.
+	*
+	* Upload and extraction are separate promises (see `extractionQueue.ts`): the bytes
+	* must be visible when the upload answers, while the `.md` sibling may take a minute
+	* on a scanned PDF. `run` reuses the same permission-checked `extractBeside` path the
+	* upload used, so a background run and a manual retry cannot diverge. One queue per
+	* registration means one worker per process, which is what keeps two parses from
+	* competing for the same small box.
+	*/
+	const extractionQueue = createExtractionQueue({
+		isExtractable: (relPath) => isExtractable(relPath),
+		run: async (relPath, mineruBaseUrl) => {
+			return extractionOutcomeOf(await extractBeside(config, relPath, mineruBaseUrl));
+		}
+	});
+	/**
 	* Callers whose missing pointer has already been repaired once this process.
 	*
 	* A caller with nothing granted never gains a pointer from a sync, so without
@@ -4972,7 +5166,6 @@ function apply(ctx, deploymentConfig) {
 								content: encoding === "base64" ? void 0 : content,
 								...encoding === "base64" ? { bytes: payloadBytes } : {}
 							});
-							const extraction = await extractBeside(config, relPath, uploadSettings.mineruBaseUrl);
 							await appendAuditEntry(uploadViewDir, {
 								at: (/* @__PURE__ */ new Date()).toISOString(),
 								actor: caller.userId,
@@ -4984,7 +5177,7 @@ function apply(ctx, deploymentConfig) {
 							const afterWrite = await refreshViewIfStale(true, created.relPath);
 							const reply = writeReplyAfterSync({
 								created,
-								...extraction === void 0 ? {} : { extraction }
+								extraction: extractionQueue.enqueue(relPath, uploadSettings.mineruBaseUrl)
 							}, afterWrite);
 							return writeJson(res, reply.status, reply.body);
 						} catch (error) {
@@ -5034,11 +5227,91 @@ function apply(ctx, deploymentConfig) {
 							error: "the permission service did not identify this caller",
 							detail: callerFailure
 						});
+						const visible = await listDirectoryWithPermissions(host, config, root, target, callerId);
+						const present = new Set(visible.map((entry) => entry.name));
+						const entries = visible.map((entry) => {
+							if (entry.isDir) return entry;
+							const extractable = isExtractable(entry.relPath);
+							return {
+								...entry,
+								canExtract: extractable,
+								hasMarkdown: extractable ? present.has(entry.name + ".md") : false
+							};
+						});
 						return writeJson(res, 200, {
-							entries: await listDirectoryWithPermissions(host, config, root, target, callerId),
+							entries,
+							total: entries.length,
 							permissionsResolved: true
 						});
 					}
+					case "extract.status": return writeJson(res, 200, extractionQueue.snapshot());
+					case "extract.retry": {
+						if (config.baseUrl.trim() === "") return writeJson(res, 409, { error: "DataOps permission API is not configured" });
+						const body = await readJsonBody(req);
+						const relPath = String(body.relPath ?? "");
+						if (relPath.trim() === "") return writeJson(res, 400, { error: "relPath is required" });
+						if (!isContainedRelPath(relPath)) return writeJson(res, 400, {
+							error: "path escapes the knowledge root",
+							refused: [relPath]
+						});
+						if (!isExtractable(relPath)) return writeJson(res, 200, {
+							outcome: "unsupported",
+							relPath,
+							message: "this file type has no extractor"
+						});
+						const localRoot = localConfig(config);
+						const target = join(localRoot.actualRoot, relPath);
+						const source = await stat(target).catch(() => void 0);
+						if (source === void 0 || !source.isFile()) return writeJson(res, 404, { error: "no such file" });
+						if (!await canWritePath(host, config, relPath)) return writeJson(res, 403, {
+							error: "write access is required to extract here",
+							refused: [relPath]
+						});
+						const sibling = markdownSiblingOf(relPath);
+						const existing = await stat(join(localRoot.actualRoot, sibling)).catch(() => void 0);
+						if (existing !== void 0 && existing.isFile()) return writeJson(res, 200, {
+							outcome: "exists",
+							relPath,
+							markdown: sibling
+						});
+						const settings = await readSettings(viewPathFor({
+							actualRoot: localRoot.actualRoot,
+							viewRoot: localRoot.viewRoot,
+							userId: (await fetchCaller(host, config).catch(() => void 0))?.userId ?? ""
+						}));
+						const accepted = extractionQueue.enqueue(relPath, settings.mineruBaseUrl);
+						if (body.wait === false) return writeJson(res, 202, {
+							outcome: "queued",
+							relPath,
+							extraction: accepted
+						});
+						const settled = await extractionQueue.settled(relPath);
+						const outcome = settled === void 0 ? {
+							state: "failed",
+							reason: "the extraction task was not recorded"
+						} : {
+							state: settled.state === "succeeded" ? "succeeded" : settled.state === "unsupported" ? "unsupported" : "failed",
+							...settled.markdown === void 0 ? {} : { markdown: settled.markdown },
+							...settled.via === void 0 ? {} : { via: settled.via },
+							...settled.reason === void 0 ? {} : { reason: settled.reason }
+						};
+						if (outcome.state === "succeeded") {
+							const afterWrite = await refreshViewIfStale(true, sibling);
+							const reply = writeReplyAfterSync({
+								outcome: "extracted",
+								relPath,
+								markdown: outcome.markdown,
+								...outcome.via === void 0 ? {} : { via: outcome.via }
+							}, afterWrite);
+							return writeJson(res, reply.status, reply.body);
+						}
+						return writeJson(res, 200, {
+							outcome: outcome.state === "unsupported" ? "unsupported" : "failed",
+							relPath,
+							...outcome.reason === void 0 ? {} : { reason: outcome.reason },
+							...outcome.markdown === void 0 ? {} : { markdown: outcome.markdown }
+						});
+					}
 					case "search": {
 						const body = await readJsonBody(req);
 						const term = String(body.term ?? "");
@@ -5172,13 +5445,17 @@ function apply(ctx, deploymentConfig) {
 						const plan = localConfig(config);
 						const caller = await fetchCaller(host, config);
 						if (!isSafeUserId(caller.userId)) return writeJson(res, 400, { error: "unsafe caller id; cannot key a view by it" });
+						const settings = await readSettings(viewPathFor({
+							actualRoot: plan.actualRoot,
+							viewRoot: plan.viewRoot,
+							userId: caller.userId
+						}));
+						const canEdit = await canManageGrants(host, config);
+						const mineruUrl = mineruUrlFor(config);
 						return writeJson(res, 200, {
-							settings: await readSettings(viewPathFor({
-								actualRoot: plan.actualRoot,
-								viewRoot: plan.viewRoot,
-								userId: caller.userId
-							})),
-							canEdit: await canManageGrants(host, config)
+							settings,
+							canEdit,
+							...mineruUrl === void 0 ? {} : { mineruUrl }
 						});
 					}
 					case "settings.set": {
@@ -5280,7 +5557,11 @@ function apply(ctx, deploymentConfig) {
 								outcome: "applied"
 							}).catch(() => void 0);
 							const afterWrite = await refreshViewIfStale(true, created.relPath);
-							const reply = writeReplyAfterSync({ approved: created }, afterWrite);
+							const approveSettings = await readSettings(viewDir);
+							const reply = writeReplyAfterSync({
+								approved: created,
+								extraction: extractionQueue.enqueue(created.relPath, approveSettings.mineruBaseUrl)
+							}, afterWrite);
 							return writeJson(res, reply.status, reply.body);
 						} catch (error) {
 							if (error instanceof KnowledgeWriteError) return writeJson(res, writeStatusFor(error.code), {
@@ -5721,4 +6002,4 @@ async function executeStep(runner, step, hostId, record) {
 	}
 }
 //#endregion
-export { Config, KB_ROOT_RESOURCE_ID, KNOWLEDGE_SKILL_DESCRIPTION, KNOWLEDGE_SKILL_INVOCATION, KNOWLEDGE_SKILL_NAME, KNOWLEDGE_SKILL_PROVIDER, KNOWLEDGE_SKILL_RANK, KnowledgeError, KnowledgeWriteError, MAX_KNOWLEDGE_WRITE_BYTES, TEMPLATE_READ_TIMEOUT_MS, apply, canManageGrants, canReadPath, canWritePath, classifyMount, createGrant, createKnowledgeEntry, extractBeside, fetchCaller, fetchGrants, fetchPrincipals, inject, knowledgeAncestorsFor, knowledgeBaseSkillProvider, knowledgeSkillPath, listDirectory, listDirectoryShapes, listDirectoryWithPermissions, listRelativeFiles, localConfig, localStatus, mineruUrlFor, name, planContext, readDepartmentOf, readKnowledgeFile, readKnowledgeFileForDownload, revokeGrant, searchKnowledge, syncCallerView, withStoredStorage };
+export { Config, KB_ROOT_RESOURCE_ID, KNOWLEDGE_SKILL_DESCRIPTION, KNOWLEDGE_SKILL_INVOCATION, KNOWLEDGE_SKILL_NAME, KNOWLEDGE_SKILL_PROVIDER, KNOWLEDGE_SKILL_RANK, KnowledgeError, KnowledgeWriteError, MAX_KNOWLEDGE_WRITE_BYTES, TEMPLATE_READ_TIMEOUT_MS, apply, canManageGrants, canReadPath, canWritePath, classifyMount, createGrant, createKnowledgeEntry, extractBeside, extractionOutcomeOf, fetchCaller, fetchGrants, fetchPrincipals, inject, knowledgeAncestorsFor, knowledgeBaseSkillProvider, knowledgeSkillPath, listDirectory, listDirectoryShapes, listDirectoryWithPermissions, listRelativeFiles, localConfig, localStatus, mineruUrlFor, name, planContext, readDepartmentOf, readKnowledgeFile, readKnowledgeFileForDownload, revokeGrant, searchKnowledge, syncCallerView, withStoredStorage };

package/lib/types/api.d.ts

@@ -108,6 +108,16 @@ export declare const KB_API: {
     readonly templateSave: "template.save";
     /** Remove one template: its document and its metadata record. */
     readonly templateRemove: "template.remove";
+    /**
+     * Read what this process knows about extraction.
+     *
+     * The queue lives in memory, so this reports the tasks of the running process only;
+     * a file that is neither queued nor beside a `.md` sibling reads as never attempted,
+     * which is a fact about this process rather than a claim about the document.
+     */
+    readonly extractStatus: "extract.status";
+    /** Re-run extraction for one document that could not finish. */
+    readonly extractRetry: "extract.retry";
     /** Read the caller's pinned paths. */
     readonly favoritesGet: "favorites.get";
     readonly favoritesSet: "favorites.set";
@@ -572,3 +582,39 @@ export interface KnowledgeTemplateSaveInput {
     /** Set when editing an existing template, so its document is replaced in place. */
     id?: string;
 }
+/** Where one extraction task is in its lifecycle, as the Host reports it. */
+export type ExtractionStateView = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported';
+/**
+ * One extraction task.
+ *
+ * Mirrors the Host's own record: the source path, the state, and whatever it managed to
+ * learn about the outcome. `reason` is the extractor's verbatim text, which is the only
+ * thing that tells a reader whether to retry or give up.
+ */
+export interface ExtractionTaskView {
+    /** Knowledge-relative path of the source document. */
+    relPath: string;
+    /** Where the task is in its lifecycle. */
+    state: ExtractionStateView;
+    /** When the task was accepted, ISO-8601. */
+    queuedAt: string;
+    /** When the run started, ISO-8601. */
+    startedAt?: string;
+    /** When the run reached a terminal state, ISO-8601. */
+    finishedAt?: string;
+    /** The Markdown sibling that was written, when one was. */
+    markdown?: string;
+    /** Which authority produced the text. */
+    via?: string;
+    /** Why the extraction produced nothing. */
+    reason?: string;
+}
+/** The extraction queue's snapshot. */
+export interface ExtractionStatusView {
+    /** The path of the task running right now, when one is. */
+    running?: string;
+    /** How many tasks are queued or running. */
+    size: number;
+    /** Every task this process knows about. */
+    tasks: ExtractionTaskView[];
+}

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

@@ -34,10 +34,18 @@ export interface ContextTarget {
 }
 /** The clipboard the copy/cut entries fill. */
 export interface TreeClipboard {
-    /** The path that was copied or cut. */
-    relPath: string;
-    /** Its display name, so the paste label can name the entry. */
-    name: string;
+    /**
+     * Every entry taken, in the order they were selected.
+     *
+     * A list rather than one path because a multi-row copy is a normal gesture and the
+     * paste has to put all of them somewhere. A single-row copy is a one-element list,
+     * which is why there is no separate single-row clipboard: one shape means the paste
+     * path cannot be right for one row and wrong for five.
+     */
+    entries: readonly {
+        relPath: string;
+        name: string;
+    }[];
     /** True when the source is removed on paste (cut); false for a copy request. */
     cut: boolean;
 }
@@ -45,6 +53,18 @@ export interface TreeClipboard {
 export interface KnowledgeContextMenuProps {
     /** The row the menu is open on, or null when closed. */
     target: ContextTarget | null;
+    /**
+     * Every row the menu acts on, when the reader right-clicked inside a multi-selection.
+     *
+     * Absent or shorter than two means single-row behaviour, which is why the component
+     * stays one menu rather than gaining a batch twin: the entries, the handlers and the
+     * clipboard are identical, and only the LABELS change to say how many rows they will
+     * touch. A second menu is how the two surfaces drifted apart before.
+     *
+     * `target` is still the row under the pointer -- it anchors the menu and supplies the
+     * name used by rename/download, which have no batch meaning.
+     */
+    selection?: readonly ContextTarget[];
     /** Where the pointer was, in viewport coordinates. */
     at: {
         x: number;
@@ -66,8 +86,13 @@ export interface KnowledgeContextMenuProps {
     onFavorite: (path: string, favorite: boolean) => void;
     /** Whether this path is currently favourited. */
     favorite: boolean;
-    /** Insert a reference to this path into the conversation. */
-    onReference: (path: string, isDir: boolean) => void;
+    /**
+     * Insert references into a conversation, via the picker.
+     *
+     * `targets` is present only for a multi-row selection; the single-row case passes the
+     * one path. The picker renders one dialog either way.
+     */
+    onReference: (path: string, isDir: boolean, targets?: readonly ContextTarget[]) => void;
     /** Called after a rename succeeds, so the page reloads the tree. */
     onRenamed: () => void;
     /** Called after a delete-to-trash succeeds, so the page reloads the tree. */

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

@@ -79,6 +79,35 @@ export interface KnowledgeFileTreeProps {
      * worse than the code they can at least match against their own department.
      */
     departmentPath?: DepartmentPath;
+    /**
+     * Whether one path is currently favourited, so its row can draw the star.
+     *
+     * The borrowed explorer has no row-decoration hook, so the star is applied by this
+     * wrapper observing the rows it renders (see `useRowFavorites`). Absent means the
+     * caller has no favourites store, which keeps the wrapper from touching the DOM at all.
+     */
+    isFavorite?: (relPath: string) => boolean;
+    /**
+     * Open the row context menu for one row.
+     *
+     * The explorer builds its own menu inside itself and marks the event handled, so the
+     * only place to intercept is a capture-phase listener above it. This wrapper does
+     * that and forwards the row here; the page then renders the SAME menu component the
+     * home table uses, so both surfaces offer one action set.
+     *
+     * Absent means "leave the explorer's own menu alone", which is what a read-only
+     * surface embedding this tree would want.
+     */
+    onRowContextMenu?: (relPath: string, isDir: boolean, at: {
+        x: number;
+        y: number;
+    }, selection?: readonly {
+        relPath: string;
+        name: string;
+        isDir: boolean;
+    }[]) => void;
+    /** The favourites star's accessible name. */
+    favoriteMarkLabel?: string;
 }
 /**
  * The knowledge tree, rendered by the product's file explorer.

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

@@ -70,6 +70,29 @@ export interface KnowledgeHomeProps {
      * re-read; the page owns the tick that triggers it.
      */
     onTreeChanged?: () => void;
+    /**
+     * Upload files dropped onto the table area.
+     *
+     * The table lists documents only -- there is no directory row here to aim at -- so
+     * the whole surface is one target and the destination has to be decided rather than
+     * read off the row under the pointer. `dropDirectory` carries that decision.
+     * Omitted by a read-only caller, which keeps the surface from accepting a drop that
+     * would then be refused on the Host.
+     * @param directory - the tree-relative directory the files land in.
+     * @param files - the dropped files with paths relative to that directory.
+     */
+    onUpload?: (directory: string, files: readonly {
+        file: unknown;
+        relativePath: string;
+    }[]) => void;
+    /**
+     * Where a drop on this table lands, tree-relative.
+     *
+     * The reader's own folder is the right default: `global` is the bucket everyone
+     * reads, so defaulting there would publish a private draft without asking. Empty
+     * means the mount root, which is what a caller with no personal bucket gets.
+     */
+    dropDirectory?: string;
 }
 /**
  * Render the Home surface.

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

@@ -73,6 +73,20 @@ export interface KnowledgeListingProps {
      * row is the tree's root, which has no parent to paste beside.
      */
     pasteTargetFor?: (relPath: string, isDir: boolean) => string | null;
+    /**
+     * Upload external files dropped onto a directory row.
+     *
+     * Distinct from the row-to-row move handled above: a file dragged in from the
+     * desktop carries no `KB_DRAG_MIME`, so it is the only case this callback serves.
+     * Omitted by a read-only caller, which keeps the rows from accepting a drop that
+     * would then be refused on the Host.
+     * @param relPath - the directory the files were dropped onto.
+     * @param files - the dropped files with paths relative to that directory.
+     */
+    onUpload?: (relPath: string, files: readonly {
+        file: unknown;
+        relativePath: string;
+    }[]) => void;
     /**
      * Called after a menu-driven delete or paste succeeded.
      *

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

@@ -21,12 +21,37 @@
 import type { GrantView, KnowledgeGrantSubjectType } from '../api.ts';
 import { type RoleSummary } from './roleSummary.ts';
 /** Which reading of the grant table the tabs are showing. */
-export type OverviewTab = 'person' | 'resource';
+export type OverviewTab = 'person' | 'role' | 'resource';
 /** Copy for the overview, supplied by the caller's locale record. */
 export interface OverviewCopy {
     tabByPerson: string;
+    tabByRole: string;
     tabByResource: string;
     empty: string;
+    /** Empty state per view, so "nobody is directly granted" is not shown for a role. */
+    emptyByPerson: string;
+    emptyByRole: string;
+    emptyByResource: string;
+    /** Where a principal's access comes from. */
+    sourceDirect: string;
+    /** Format "inherited via role X": `{role}` is replaced by the role code. */
+    sourceViaRole: (role: string) => string;
+    /** Shown when the user directory could not be read, so inheritance is unknowable. */
+    sourceUnavailable: string;
+    /** Word for a permission set that could not be fully determined. */
+    actionsUnknown: string;
+    actionsUnknownHint: string;
+    /** Column headers unique to the three views. */
+    colAccount: string;
+    colSource: string;
+    /** "{count} member(s)". */
+    roleMemberCount: (count: number) => string;
+    /** Pager copy, shared with the audit table's wording. */
+    pagerPrev: string;
+    pagerNext: string;
+    pagerStatus: (page: number, pageCount: number, total: number) => string;
+    pageSizeLabel: string;
+    pageSizeOption: (size: number) => string;
     pathsHeld: (count: number) => string;
     rolesHeld: string;
     actionsHeld: string;
@@ -75,6 +100,24 @@ export interface KnowledgePermissionOverviewProps {
     grants: readonly GrantView[];
     /** Display names by `principalType:principalId`. */
     labels?: Readonly<Record<string, string>>;
+    /**
+     * The DataOps account directory, when the caller could read it.
+     *
+     * Absent means the same as an unavailable read: inheritance cannot be attributed, and
+     * the page says so instead of listing accounts that look like they hold nothing.
+     */
+    directory?: {
+        kind: 'available';
+        users: ReadonlyArray<{
+            id: string;
+            label: string;
+            username?: string;
+            roleCodes?: string[];
+        }>;
+    } | {
+        kind: 'unavailable';
+        reason: string;
+    };
     /** Built-in role summaries, so the person view can explain what a role means. */
     roles?: readonly RoleSummary[];
     /** Locale copy. */
@@ -92,8 +135,13 @@ export interface KnowledgePermissionOverviewProps {
     busy?: boolean;
 }
 /**
- * Render the permission overview as stat cards over a two-tab table.
+ * Render the permission overview as stat cards over a three-tab table.
+ *
+ * THREE views, not two, because the old pair answered different questions under one
+ * heading: "by person" listed ROLE grants, so the only rows were 管理员 and 超级管理员
+ * and a reader concluding "these are the people with access" was reading the page
+ * correctly and being told something false. A role is not a person.
  *
- * @param props - grants, labels, role summaries, locale copy and the revoke hook.
+ * @param props - grants, labels, directory, role summaries, copy and the revoke hook.
  */
 export declare function KnowledgePermissionOverview(props: KnowledgePermissionOverviewProps): import("react").JSX.Element;