@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.0

package/lib/types/views.d.ts

@@ -0,0 +1,923 @@
+/**
+ * Materialize each user's visible knowledge tree as a hardlink view.
+ *
+ * A grant in the DataOps database is a statement about what a principal MAY read;
+ * it is not a filesystem fact. A workspace process that mounts the shared export
+ * sees every file in it, so the grant has to be turned into an actual directory
+ * tree before it can mean anything: one directory per user, holding hardlinks to
+ * exactly the files that user may read. Nothing crosses into a view whose grant
+ * was not resolved by DataOps, so this module never decides who may see what --
+ * it only asks, and links what the answer allows.
+ *
+ * Hardlinks rather than copies: the link shares the inode, so a revoke unlinks
+ * the view's entry and the source is untouched, and a re-grant costs one link
+ * rather than a copy of the file. That is what makes permission changes
+ * incremental, and it is why the NFS export has to be one filesystem (a hardlink
+ * cannot span mounts).
+ *
+ * @module @sparkelf/dsh-knowledge-base/views
+ */
+/** One path a user may read, as DataOps resolved it. */
+export interface ResolvedPath {
+    /** Path relative to the authoritative root. */
+    relPath: string;
+}
+/** Which layout the listing uses for this caller. */
+export type ViewMode = 'list' | 'grid' | 'explorer';
+/** What one user's view currently holds. */
+export interface ViewDelta {
+    /** Paths linked into the view during this run. */
+    linked: string[];
+    /** Paths unlinked from the view during this run. */
+    unlinked: string[];
+    /** Paths left alone because the view already matched. */
+    unchanged: number;
+    /**
+     * Directories removed because a revoke emptied them.
+     *
+     * Kept apart from `unlinked` because a leftover empty directory is not a stale
+     * file: it still discloses a folder name the user has lost access to.
+     */
+    pruned: string[];
+    /**
+     * Set when the prune pass was deliberately skipped, with the reason.
+     *
+     * Reported rather than logged so a reader can see it: "the view is not being
+     * cleaned because nothing resolved this round" is a fact about the deployment,
+     * and the alternative -- silently keeping stale links -- would be indistinguishable
+     * from a view that is correct.
+     */
+    pruneSkipped?: string;
+}
+export interface ViewOptions {
+    /** Directory holding the authoritative files. */
+    actualRoot: string;
+    /** Directory holding one view per user. */
+    viewRoot: string;
+    /** Opaque user key; a directory name, so it must not contain a separator. */
+    userId: string;
+    /**
+     * Department code used to select the `department/` subtree, when the caller has one.
+     *
+     * Layout only: it decides which department bucket is linked, never whether a path
+     * may be read. Without it the view simply has no department bucket.
+     */
+    departmentCode?: string;
+    /**
+     * The caller's organization path, root first, as DataOps reported it.
+     *
+     * This is what turns the department bucket into nested folders: the view mirrors
+     * `department/<ancestor>/.../<own>/file` so a reader opening 「部门」 walks their
+     * own reporting line instead of one flat pile of every department's documents.
+     *
+     * Absent from an older backend that reports only `departmentCode`. The view then
+     * falls back to the single-level layout, which is exactly what it used to be, so
+     * an un-upgraded backend degrades to the old shape rather than to an empty bucket.
+     */
+    departmentPathCodes?: readonly string[];
+    /**
+     * Paths this caller has removed from their view, in view coordinates.
+     *
+     * A filter, not a permission: a hidden path keeps its grant, its inode and every
+     * other caller's link. It is checked while building the view because a view is
+     * hardlinks into one tree, so "remove" cannot mean "unlink" without also undoing
+     * a grant on the next sync.
+     */
+    hidden?: readonly string[];
+}
+/** A resolved set linked into a user's view. */
+export interface ViewSyncOptions extends ViewOptions {
+    /**
+     * Whether `resolved` is the complete answer for this caller.
+     *
+     * True when the caller enumerated the whole tree (the routine and full syncs), and
+     * false when it asked about specific paths (a write verifying its own result).
+     * Only a full scan may apply the prune-refusal rule below: a targeted sync that
+     * resolved nothing knows nothing about the rest of the tree, so it must never prune
+     * either -- but it also must not be mistaken for evidence that everything failed.
+     */
+    fullScan?: boolean;
+    /**
+     * Whether an empty `resolved` may be read as "nothing is readable".
+     *
+     * Default true: an empty set prunes, which is what a real revoke looks like and what
+     * every existing caller means. A caller that enumerated the tree and saw every
+     * resolve fail passes false, because an empty answer there is a failure rather than
+     * a permission decision, and must not delete the reader's links.
+     */
+    trustResolvedSet?: boolean;
+}
+/**
+ * The three top-level buckets every view exposes, in display order.
+ *
+ * A curated shared store needs one visible answer to "where does this document
+ * live" before it can have a delete policy: what everyone may read, what the
+ * caller's department may read, and what only the caller may read are three
+ * different audiences, and mixing them puts a department document beside a
+ * company-wide one with no way to tell them apart.
+ */
+/**
+ * File name of a caller's trash record inside their view directory.
+ *
+ * Named here rather than imported from `trash.ts` so the view builder does not
+ * depend on the trash module: the builder only needs to know not to prune it.
+ */
+export declare const TRASH_RECORD_NAME = ".kb-trash.json";
+/**
+ * Every bookkeeping file this plugin writes into a caller's view directory.
+ *
+ * The view directory is the directory the reader browses, so a state file left in it
+ * is a file the explorer will offer to open, rename or delete. The NAMES live in
+ * `viewMetadata.ts` because the client needs them too and cannot import this module
+ * (`node:fs/promises` is not available in a browser bundle).
+ *
+ * The list is cross-checked against the `*PathFor` helpers below at module load: a
+ * renamed state file then fails loudly here instead of quietly appearing in every
+ * reader's tree, which is how `.kb-favorites.json` reached it once.
+ */
+export declare const VIEW_METADATA_NAMES: readonly string[];
+export declare const VIEW_BUCKETS: readonly ["global", "department", "personal"];
+/** One bucket a view can hold. */
+export type ViewBucket = typeof VIEW_BUCKETS[number];
+/** Display name of each bucket, keyed for the client's locale files. */
+export declare const VIEW_BUCKET_LABELS: Readonly<Record<ViewBucket, string>>;
+/**
+ * The caller's organization path, cleaned and made safe to use as folder names.
+ *
+ * Three inputs can produce an empty answer, and all three mean "no hierarchy to
+ * render": no path at all (an older backend), an empty path, or a path whose codes
+ * are not ordinary path segments. The last one matters because the codes come from
+ * another system: a code carrying `/` or `..` would otherwise place a directory
+ * outside the view, which is the one thing this module must not allow. Rejecting
+ * the whole path rather than the offending segment keeps the layout all-or-nothing,
+ * so a caller never sees half a hierarchy that reads as a real one.
+ *
+ * @param codes - `departmentPathCodes` as DataOps reported it.
+ * @returns The usable codes, root first, or an empty array.
+ */
+export declare function usableDepartmentPath(codes: readonly string[] | undefined): string[];
+/**
+ * Which bucket a resolved path belongs to, and where it lands inside that bucket.
+ *
+ * The authoritative root carries the same three names as ordinary directories, so
+ * ownership is a fact of where the file lives rather than a per-file label that
+ * could disagree with it. Legacy flat files (written before the split) answer
+ * `global`, which keeps a view populated while a migration is still in progress.
+ *
+ * `global` owns no second segment, so only its own name is dropped. `department`
+ * and `personal` name an OWNER and drop it: a caller opening 「部门」 expects their
+ * department's documents inside it, not nested under a second copy of the code.
+ *
+ * The department bucket's DEPTH depends on the caller, so this function takes the
+ * caller's organization path. Everything below the caller's own department keeps
+ * its sub-directories, which is what makes the bucket read as a reporting line
+ * rather than a flat pile.
+ *
+ * @param relPath - path relative to the authoritative root.
+ * @param departmentPathCodes - the caller's usable organization path, root first.
+ *   Absent or empty keeps the legacy single-level department layout.
+ * @returns The bucket and the path to link inside it, or undefined when the path
+ * cannot be placed safely.
+ */
+export declare function bucketOf(relPath: string, departmentPathCodes?: readonly string[]): {
+    bucket: ViewBucket;
+    inner: string;
+} | undefined;
+/**
+ * Whether a `department/…` path belongs to the caller's own department.
+ *
+ * The department segment is compared exactly, so `OPS` does not match `OPS2`. A
+ * caller with no department matches nothing: their view gets no department bucket
+ * rather than every department a stray grant happens to mention.
+ *
+ * With an organization path there are two shapes a document of the caller's own
+ * department can have, and both are accepted because both exist on a live share:
+ *
+ * - **Nested**, `department/<ancestor>/.../<own>/<something>`: the whole chain must
+ *   match in order. Comparing the chain rather than the leaf alone is what keeps a
+ *   peer out, since a peer that merely shares the root (`A/B` vs `A/C`) would pass a
+ *   leaf-only test.
+ * - **Legacy flat**, `department/<own>/<something>`: written before the hierarchy
+ *   existed. The caller's own code is at the first position instead of the last, so it
+ *   is checked separately; refusing it would make every pre-upgrade document vanish.
+ *
+ * Both shapes need at least one segment BELOW the department, because the department
+ * folder itself is a container, not a document.
+ *
+ * @param relPath - authoritative path, already known to start with `department/`.
+ * @param departmentCode - the caller's department code, when DataOps reported one.
+ * @param departmentPathCodes - the caller's organization path, root first, when the
+ *   backend reported one. Falls back to {@link departmentCode} when absent.
+ * @returns true when the path sits under the caller's own department.
+ */
+export declare function departmentPrefixMatches(relPath: string, departmentCode: string | undefined, departmentPathCodes?: readonly string[]): boolean;
+/**
+ * Whether a user key is safe to use as one directory name.
+ *
+ * The key comes from the identity provider rather than from this plugin, so it is
+ * validated before it reaches the filesystem: a value carrying a separator or a
+ * parent reference would place the view outside the view root, which is the one
+ * thing this module must not allow.
+ * @param userId - the candidate key.
+ * @returns true when it is a single ordinary path segment.
+ */ export declare function isSafeUserId(userId: string): boolean;
+/**
+ * The directory one user's view lives in.
+ * @param options - the roots and the user key.
+ * @returns The absolute view directory.
+ */
+/**
+ * Whether a path is a mount point.
+ *
+ * Read from `/proc/self/mountinfo` rather than inferred from `stat`: comparing a
+ * directory's device against its parent's reports a bind mount of the SAME
+ * filesystem as "not a mount point", and the whole point of this check is to catch
+ * the deployment where the share IS the path being retargeted. The file is the
+ * kernel's own list, so a path present in it is mounted by definition.
+ *
+ * Field 5 of each line is the mount point, escaped (`\040` for a space). A path
+ * that is not absolute, or a kernel without the file, answers false: the remaining
+ * guards in {@link pointMountAtView} still refuse a non-empty directory, so this
+ * check failing open cannot on its own authorize a destructive replace.
+ * @param path - absolute path to test.
+ * @returns true when the kernel lists it as a mount point.
+ */
+export declare function isMountPoint(path: string): Promise<boolean>;
+/**
+ * Point the browsable mount at one user's view.
+ *
+ * The view is built beside the authoritative tree, but the page browses
+ * `mountPoint`. Without this step every user would browse the same directory and a
+ * grant would change nothing they can see: the view would be correct and
+ * unreachable at the same time.
+ *
+ * A symlink is the mechanism because the browsable path is a fixed path the caller
+ * configured, while the view is per user.
+ *
+ * This function REPLACES whatever sits at `mountPoint`, so it refuses two shapes
+ * outright rather than removing them:
+ *
+ * - a **mount point**, because removing it would delete the mounted filesystem's
+ *   contents on the server. Measured on 2026-10-17: a deployment whose
+ *   `mountPoint` was the NFS root had `actual/` and every user's `views/` deleted
+ *   by the old unconditional `rm -rf`, and the share root replaced by a symlink.
+ * - a **non-empty real directory**, because its contents are someone else's data
+ *   and a retarget is not a reason to delete them.
+ *
+ * What remains is exactly the set of shapes a pointer may legitimately occupy: an
+ * absent path (first sync), a symlink (a repeat sync), an empty directory (a
+ * leftover), or an already-correct link. A refusal throws rather than returning
+ * false, because false means "the view was not ready" while this means "the
+ * configuration is wrong" -- two different things for the caller to report.
+ * @param options - the roots the paths are resolved against.
+ * @param mountPoint - the browsable path to retarget.
+ * @returns True when the link now points at the view.
+ */
+export declare function pointMountAtView(options: ViewOptions, mountPoint: string): Promise<boolean>;
+export declare function viewPathFor(options: ViewOptions): string;
+/**
+ * The view-relative path one authoritative entry is expected to appear at.
+ *
+ * A write knows the path it just created; this answers "where should the reader see
+ * it". Used to VERIFY a refresh rather than trust its status: `syncCallerView` reports
+ * success as soon as it has walked the tree, and its per-path permission question
+ * fails closed, so a resolve that failed for every path still answers 200 with
+ * `resolved: 0`. Comparing the expected view path against the disk is what turns
+ * "the sync ran" into "the reader can see it".
+ *
+ * @param options - the roots and the user key, for the department layout.
+ * @param relPath - authoritative path of the entry.
+ * @returns The view-relative path, or undefined when the caller's layout excludes it.
+ */
+export declare function expectedViewPathFor(options: ViewOptions, relPath: string): string | undefined;
+/**
+ * Reject a relative path that would escape the root it is joined to.
+ *
+ * The resolved paths come from the authorization service, but they name files in
+ * a shared export. A `..` segment would let a grant for one path reach another, so
+ * it is refused here rather than trusted: the service decides visibility, this
+ * module decides that a visible path still lands inside the tree.
+ * @param relPath - the candidate path.
+ * @returns true when the path is relative and stays under its root.
+ */
+export declare function isContainedRelPath(relPath: string): boolean;
+/**
+ * Bring one user's view in line with the paths DataOps resolved for them.
+ *
+ * Only the difference is touched: a path already linked is left alone, a missing
+ * one is linked, and one that is no longer resolved is unlinked. A run over an
+ * unchanged grant set therefore performs no filesystem writes at all, which is
+ * what makes this safe to repeat after every permission change.
+ *
+ * A link whose source has gone stale is reported as unlinked rather than failing
+ * the run, so one deleted file cannot leave a user's whole view half-applied.
+ * @param options - the roots and the user key.
+ * @param resolved - the paths DataOps says this user may read.
+ * @returns What changed, so a caller can report or log the delta.
+ */
+export declare function syncView(options: ViewSyncOptions, resolved: readonly ResolvedPath[]): Promise<ViewDelta>;
+/**
+ * Remove one user's whole view.
+ *
+ * Used when a user is removed rather than merely re-scoped: their grants are gone
+ * from DataOps, so the view directory has no reason to exist. The authoritative
+ * files are untouched, because every entry in the view is a link to them.
+ * @param options - the roots and the user key.
+ * @returns true when a directory was removed, false when there was none.
+ */
+export declare function dropView(options: ViewOptions): Promise<boolean>;
+/**
+ * The dotfile holding one user's list/grid preference.
+ *
+ * Beside `.pinned.json` and for the same reasons: the view directory is already
+ * per-user, already on the share, and the choice should follow the reader rather
+ * than the browser profile. Written through {@link writeViewMode} and skipped by
+ * the sync walk, which is what keeps a preference from being deleted as if it
+ * were a stale grant.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the view-mode file.
+ */
+export declare function viewModePathFor(viewDir: string): string;
+/**
+ * The dotfile holding this knowledge base's review settings.
+ *
+ * A third sibling of `.pinned.json` and `.view-mode.json`, for the same reasons: the
+ * view directory already exists per user, already lives on the share, and the setting
+ * belongs to the knowledge base rather than to one browser profile. It MUST be named in
+ * the sync walk's metadata set, or the next sync deletes it as if it were a stale grant.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the settings file.
+ */
+export declare function settingsPathFor(viewDir: string): string;
+/**
+ * The append-only audit log.
+ *
+ * A `.jsonl` file rather than a JSON array: an audit entry is appended with a single
+ * `appendFile`, so recording one action never rewrites the history before it. A JSON
+ * array would have to be read, extended and rewritten in full, which both costs more and
+ * creates a window where a crash truncates the whole trail.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the audit log.
+ */
+export declare function auditLogPathFor(viewDir: string): string;
+/**
+ * Where content waits while review is required.
+ *
+ * Deliberately NOT under a view: the sync walk unlinks every file in a view that the
+ * caller's resolved grants do not name, so pending content parked there would be
+ * deleted by the next sync, which is the same failure that made writing new documents
+ * into a view wrong. It lives in the authoritative root instead, in a directory whose
+ * name starts with a dot so the tree listing already hides it.
+ * @param actualRoot - the authoritative root.
+ * @returns The absolute path of the pending directory.
+ */
+export declare function pendingDirFor(actualRoot: string): string;
+/**
+ * Build the stable filename one pending write is parked under.
+ *
+ * The caller's id is part of the name so the trail of who submitted what survives even
+ * when the same path is submitted twice by different people; the timestamp keeps the
+ * two submissions from overwriting each other.
+ * @param userId - the submitting caller.
+ * @param relPath - the path the caller wanted to write.
+ * @param at - when it was submitted.
+ * @returns A filename that is safe as one path segment.
+ */
+export declare function pendingFileNameFor(userId: string, relPath: string, at: string): string;
+/**
+ * Park one write for review instead of applying it.
+ *
+ * The payload is a small JSON envelope beside a copy of the bytes, both inside the
+ * pending directory. Keeping the content rather than only the intent means an approver
+ * can read exactly what was submitted, which is the whole point of reviewing it.
+ * @param actualRoot - the authoritative root.
+ * @param submission - what was submitted.
+ * @returns The directory the submission was parked in.
+ */
+export declare function parkPendingWrite(actualRoot: string, submission: {
+    userId: string;
+    relPath: string;
+    content: string;
+    at: string;
+}): Promise<string>;
+/** One submission waiting for review. */
+export interface PendingWrite {
+    /** The parking name, which is also the handle a reviewer acts on. */
+    name: string;
+    /** Who submitted it. */
+    userId: string;
+    /** The path it wants to occupy in the authoritative tree. */
+    relPath: string;
+    /** When it was submitted. */
+    at: string;
+    /** Size of the submitted bytes. */
+    bytes: number;
+}
+/**
+ * Decide whether a value is one parking name and not a path.
+ *
+ * A reviewer acts on a name that came back from {@link listPendingWrites}, but the
+ * request is still browser input. Refusing separators and dot segments here means a
+ * crafted name cannot reach outside the pending directory, whatever the caller sends.
+ * @param value - the candidate name.
+ * @returns Whether it is usable as one path segment.
+ */
+export declare function isPendingName(value: unknown): value is string;
+/**
+ * Read every submission waiting for review.
+ *
+ * The envelope is the source of truth rather than the filename, because the name escapes
+ * characters out of `relPath` and that escaping is lossy: a reviewer must see the path
+ * the submitter actually asked for. A submission whose envelope cannot be read is
+ * skipped rather than aborting the queue.
+ * @param actualRoot - the authoritative root.
+ * @returns The pending submissions, oldest first.
+ */
+export declare function listPendingWrites(actualRoot: string): Promise<PendingWrite[]>;
+/**
+ * Read one submission's bytes.
+ *
+ * The name is checked again rather than trusted: this is the function that returns
+ * content to be written into the shared tree, so it is the last place a traversal could
+ * turn into a write outside the pending directory.
+ * @param actualRoot - the authoritative root.
+ * @param name - the parking name.
+ * @returns The submitted content, or null when it is not there.
+ */
+export declare function readPendingContent(actualRoot: string, name: string): Promise<string | null>;
+/**
+ * Forget one submission.
+ *
+ * Used by both the approve and the reject path: approving means the bytes now live in the
+ * authoritative tree, and rejecting means nobody wants them. Either way the parked copy
+ * must not linger, or the queue would re-offer a decision already made.
+ * @param actualRoot - the authoritative root.
+ * @param name - the parking name.
+ * @returns Whether anything was removed.
+ */
+export declare function discardPendingWrite(actualRoot: string, name: string): Promise<boolean>;
+/**
+ * Storage choices the operator may change from the panel.
+ *
+ * A strict subset of the plugin's configuration, and every field here is one the panel
+ * can meaningfully write: which shape to run, which transport a remote deployment uses,
+ * and where that transport reaches. Everything omitted -- `mountPoint`, `actualRoot`,
+ * `viewRoot`, `permitted` -- is left to the deployment because those paths are bound into
+ * the container when it is created, so writing them here would only point the plugin at
+ * paths nothing serves.
+ *
+ * There is deliberately no private-key field. `sshKeyRef` names a credential; the secret
+ * lives in the credential store, which is the only place a key may live.
+ */
+export interface KnowledgeStorageSettings {
+    /** Which storage shape to run, when the operator has chosen one. */
+    storageMode?: 'local' | 'remote';
+    /** Transport a remote deployment reaches its share by. */
+    storageProtocol?: 'nfs' | 'sshfs';
+    /** NFS export host. */
+    nfsServer?: string;
+    /** SSHFS: remote host. */
+    sshHost?: string;
+    /** SSHFS: login user. */
+    sshUser?: string;
+    /** SSHFS: SSH daemon port. */
+    sshPort?: number;
+    /** SSHFS: absolute path of the shared directory on the remote host. */
+    sshRemotePath?: string;
+    /** SSHFS: extra `-o` options. */
+    sshMountOptions?: string;
+    /** SSHFS: credential reference holding the private key -- a name, never the key. */
+    sshKeyRef?: string;
+}
+/** Whether a write must be reviewed before it counts as published. */
+export interface KnowledgeSettings extends KnowledgeStorageSettings {
+    /**
+     * When true, content a caller adds is recorded as pending instead of taking effect.
+     *
+     * Defaults to false: the product ships with review OFF and an audit trail only, which
+     * is the behaviour the operator asked for. Turning it on is a deliberate act.
+     */
+    reviewRequired: boolean;
+    /**
+     * MinerU's full base address, or `''` to derive it from the port.
+     *
+     * The port alone cannot express anything but this machine: a service reached through
+     * a tunnel, a gateway or another host has no port to put here. An empty value means
+     * "derive it", which keeps every existing deployment working without a migration.
+     */
+    mineruBaseUrl: string;
+}
+/** The settings a caller who has never opened the page gets. */
+export declare const DEFAULT_KNOWLEDGE_SETTINGS: KnowledgeSettings;
+/**
+ * Normalise a MinerU base address.
+ *
+ * Only an absolute http(s) address is storable. A bare host, a `file:` URL or a typo
+ * would be handed to a parser that can only fail on it, and the failure would surface
+ * as "extraction broke" rather than "this setting is wrong", so the value is checked
+ * where it is written instead.
+ * @param raw - the candidate value.
+ * @returns The trimmed address without a trailing slash, or `''`.
+ */
+export declare function normalizeMineruBaseUrl(raw: unknown): string;
+/**
+ * Copy the storage fields out of a parsed settings object.
+ *
+ * Values are validated here rather than at the render site so a hand-edited or foreign file
+ * cannot put an unknown mode into the effective configuration: an unrecognized value is
+ * dropped and the deployment default stands.
+ * @param raw - the parsed settings object.
+ * @returns The recognized storage fields, omitting anything invalid.
+ */
+export declare function storageSettingsOf(raw: Record<string, unknown>): KnowledgeStorageSettings;
+/**
+ * Read this knowledge base's settings.
+ *
+ * Anything unrecognized answers the defaults rather than an error: a corrupt settings
+ * file should cost the reader their preferences, not the page. `reviewRequired` is
+ * coerced to a real boolean so a hand-edited `"false"` string cannot switch review on.
+ * @param viewDir - the user's view directory.
+ * @returns The stored settings, or the defaults.
+ */
+export declare function readSettings(viewDir: string): Promise<KnowledgeSettings>;
+/**
+ * Replace this knowledge base's settings.
+ *
+ * Atomic by rename for the same reason the pins and the view mode are: a reader must
+ * never observe a half-written settings file. The view directory is created because a
+ * setting can be recorded before the first sync has built one.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param settings - the settings to store.
+ * @returns The settings actually written.
+ */
+export declare function writeSettings(viewDir: string, settings: KnowledgeSettings): Promise<KnowledgeSettings>;
+/**
+ * The deployment-level settings file, addressed from the mounted knowledge tree.
+ *
+ * A separate accessor from {@link settingsPathFor} because the two files answer different
+ * questions and are read at different moments. The per-user file is only reachable once a
+ * caller is known, while this one must be readable on the very first `config` call -- before
+ * any identity has been resolved -- because the storage shape is what tells the page whether
+ * a caller is needed at all. `mountPoint` is the one path the panel knows without asking
+ * anyone, so the file hangs off it.
+ *
+ * Named `.kb-settings.json` so it lands in the same metadata set the sync walk already
+ * skips; a sync that deleted it would silently revert the operator's choice.
+ * @param mountPoint - the mounted knowledge tree.
+ * @returns The absolute path of the settings file.
+ */
+export declare function storageSettingsPathFor(mountPoint: string): string;
+/**
+ * Read the stored storage settings, tolerating every ordinary absence.
+ *
+ * A missing mount point, a missing file, and a file written by an older build are all the
+ * same answer here: nothing has been chosen yet, so the deployment defaults stand. Only a
+ * value that IS present and unrecognized is dropped, and it is dropped on its own rather
+ * than invalidating its neighbours.
+ * @param mountPoint - the mounted knowledge tree.
+ * @returns The stored storage fields, empty when nothing usable is on disk.
+ */
+export declare function readStorageSettings(mountPoint: string): Promise<KnowledgeStorageSettings>;
+/**
+ * Merge a patch into the stored storage settings and write the file atomically.
+ *
+ * A merge rather than a replace: the panel sends only the fields the operator touched, and a
+ * save that blanked the others would make editing one field erase the rest. Written by
+ * `rename` so a reader never sees a half-written file, for the same reason the per-user
+ * settings are.
+ * @param mountPoint - the mounted knowledge tree, created if absent.
+ * @param patch - the fields to change.
+ * @returns The settings now on disk.
+ */
+export declare function writeStorageSettings(mountPoint: string, patch: KnowledgeStorageSettings): Promise<KnowledgeStorageSettings>;
+/**
+ * Read one user's list/grid preference.
+ *
+ * Anything unrecognized answers `list`, which is the shape the page was built
+ * around: a corrupt or hand-edited preference should cost the reader a layout
+ * choice, not the page. A missing file is that same ordinary first read.
+ * @param viewDir - the user's view directory.
+ * @returns The stored mode.
+ */
+export declare function readViewMode(viewDir: string): Promise<ViewMode>;
+/**
+ * Replace one user's list/grid preference.
+ *
+ * Atomic by rename for the same reason the pins are: a reader must never observe
+ * a half-written file. The view directory is created because the preference can
+ * be recorded before the first sync has built one.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param mode - the mode to store.
+ * @returns The mode actually written.
+ */
+export declare function writeViewMode(viewDir: string, mode: ViewMode): Promise<ViewMode>;
+/**
+ * The dotfile holding one user's expanded folders in the explorer.
+ *
+ * A sibling of `.pinned.json` and `.view-mode.json`, for the same reasons: the view
+ * directory is already per-user and already on the share, so "the same person sees
+ * the same tree" needs no new storage of its own. It MUST be named in the sync
+ * walk's metadata set, or the next sync deletes it as if it were a stale grant --
+ * which reads as a preference that will not stick rather than as a bug in that walk.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the tree-state file.
+ */
+export declare function treeStatePathFor(viewDir: string): string;
+/**
+ * Read one user's expanded folders.
+ *
+ * Every failure answers an empty list, which is also the correct default: the tree
+ * starts fully collapsed, so a missing file, an unreadable file, a truncated file,
+ * and a file holding something other than an array all resolve to the state a
+ * first visit has. Never throws -- the tree must render even when this file is
+ * missing or corrupt, and a preference is never worth failing a page for.
+ * @param viewDir - the user's view directory.
+ * @returns The stored expanded paths, deduplicated, junk entries dropped.
+ */
+export declare function readTreeState(viewDir: string): Promise<string[]>;
+/**
+ * Replace one user's expanded folders.
+ *
+ * Atomic by rename for the same reason the pins and the view mode are: a reader
+ * must never observe a half-written file, and the file lives on a share where a
+ * crash mid-write would otherwise leave a truncated document that reads as "all
+ * collapsed". The view directory is created because the preference can be
+ * recorded before the first sync has built one.
+ *
+ * Junk is dropped rather than refused: unlike a pin, which names a document the
+ * reader explicitly asked to keep, this is a volume knob whose worst failure mode
+ * is a folder that comes back closed. Answering 400 here would make a broken
+ * client's save look like a page error for no reader-visible gain.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param expanded - the absolute paths to store.
+ * @returns The paths actually written.
+ */
+export declare function writeTreeState(viewDir: string, expanded: readonly string[]): Promise<string[]>;
+/**
+ * The dotfile holding one user's favourite paths.
+ *
+ * A fourth sibling of `.pinned.json`, `.view-mode.json` and `.kb-tree-state.json`,
+ * and for the same reason: a favourite is a view preference about the reader, not a
+ * property of the document, so the caller's own view directory is already the right
+ * owner and no backend table is involved. It MUST stay listed in the sync walk's
+ * metadata set or the next sync unlinks it, which shows up as a star that will not
+ * stick rather than as a bug in that walk.
+ *
+ * Kept separate from `pins` on purpose. A pin promotes a path into the rail's band
+ * and is addressed by the reader looking for a shortcut; a favourite only marks the
+ * row where it already sits, and the two are expected to differ -- pinning a folder
+ * you work in every day while still starring the report you are drafting.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the favourites file.
+ */
+export declare function favoritesPathFor(viewDir: string): string;
+/**
+ * Read one user's favourites.
+ *
+ * A missing or unparsable file is the empty list, exactly as {@link readPins}
+ * reports it: no favourites is the ordinary first state, and a corrupt preference
+ * should cost the reader their stars rather than the page.
+ * @param viewDir - the user's view directory.
+ * @returns The favourited paths, in the order they were written.
+ */
+export declare function readFavorites(viewDir: string): Promise<string[]>;
+/**
+ * Replace one user's favourites.
+ *
+ * Normalised and written by atomic rename, like every other preference file here:
+ * a reader must never observe a half-written list, and the temporary is a sibling
+ * because a rename cannot cross a filesystem.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param relPaths - the paths to store.
+ * @returns The paths actually written, after normalisation.
+ */
+export declare function writeFavorites(viewDir: string, relPaths: readonly string[]): Promise<string[]>;
+/**
+ * Move or rename one entry inside the authoritative tree.
+ *
+ * `rename(2)` rather than a copy followed by an unlink, and that choice is the
+ * whole point of this function: the authoritative tree is an NFS export, so a
+ * copy-and-delete would read and rewrite the entire file across the network for
+ * what the kernel can do as a single atomic directory operation. It also keeps
+ * the inode, which matters because every user's view holds HARDLINKS to these
+ * files: a copy would give the moved file a new inode and leave every hardlink in
+ * every view pointing at the old one. Callers must resynchronize the affected
+ * views afterwards ({@link syncView} relinks the new path and drops the old), and
+ * that is not optional -- without it the reader sees a dead entry.
+ *
+ * Both paths are required to be contained relative paths; the caller is
+ * responsible for having asked the authority whether the caller may write them.
+ * The destination's parent is created when it does not exist, and a destination
+ * that already holds an entry is refused rather than overwritten, because a move
+ * that silently replaces a document is data loss and no prompt can undo it.
+ * @param options - the roots; only `actualRoot` is used.
+ * @param fromRelPath - the entry's current path, relative to the root.
+ * @param toRelPath - the entry's new path, relative to the root.
+ * @returns The moved entry's new relative path.
+ */
+export declare function moveEntry(options: ViewOptions, fromRelPath: string, toRelPath: string): Promise<{
+    from: string;
+    to: string;
+}>;
+/**
+ * Copy one entry, with its subtree, to a new path inside the authoritative tree.
+ *
+ * Three rules that the caller cannot waive:
+ *
+ * - **No overwrite.** An existing destination is refused by name rather than replaced
+ *   or auto-renamed: a silent overwrite destroys something the reader did not name, and
+ *   an auto-rename produces a file under a name they never typed while the surface says
+ *   the copy succeeded.
+ * - **Symlinks are copied, not followed.** See {@link planCopy}.
+ * - **All-or-nothing.** Everything is resolved and size-checked first; if the write
+ *   phase still fails, the paths written so far are removed, so the tree never keeps a
+ *   half-copied directory.
+ *
+ * `copyFile` + `mkdir` rather than a recursive helper: the plan already knows every
+ * path, and doing them one at a time is what makes rollback a list of paths to unlink
+ * instead of a second tree walk over an unknown half-written state.
+ * @param options - the caller's view options (only `actualRoot` is used).
+ * @param fromRelPath - the source, relative to the authoritative root.
+ * @param toRelPath - the destination, relative to the authoritative root.
+ * @returns The source and destination paths, on success.
+ */
+export declare function copyEntry(options: ViewOptions, fromRelPath: string, toRelPath: string): Promise<{
+    from: string;
+    to: string;
+    entries: number;
+    bytes: number;
+}>;
+/**
+ * The dotfile holding one user's pins.
+ *
+ * A dotfile inside the caller's own view directory, rather than a backend table:
+ * the view directory is already per-user, already on the shared export, and
+ * already rebuilt in place by {@link syncView}. Pins are therefore durable across
+ * a restart and need no new authority to store. The name is dotted to keep it out
+ * of the way of a reader scanning the tree, and the walk skips this exact path so
+ * a sync cannot delete it.
+ * @param viewDir - the user's view directory.
+ * @returns The absolute path of the pin file.
+ */
+export declare function pinsPathFor(viewDir: string): string;
+/**
+ * Read one user's pins.
+ *
+ * A missing file is the empty list rather than an error: every user has no pins
+ * until they make one, so that is the ordinary first read. A file that exists but
+ * cannot be parsed is also reported empty, because a corrupt preference should
+ * cost the reader their pins rather than the whole page.
+ * @param viewDir - the user's view directory.
+ * @returns The pinned paths, in the order they were written.
+ */
+export declare function readPins(viewDir: string): Promise<string[]>;
+/**
+ * Replace one user's pins.
+ *
+ * The list is normalized before it is written: every entry must be a contained
+ * relative path, duplicates collapse, and the order is the caller's. Writing is
+ * atomic by rename, so a reader never observes a half-written file, and the
+ * temporary name is a sibling because a rename cannot cross a filesystem.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param relPaths - the paths to store, already filtered for readability.
+ * @returns The paths actually written, after normalization.
+ */
+export declare function writePins(viewDir: string, relPaths: readonly string[]): Promise<string[]>;
+/** One recorded change to the knowledge base. */
+export interface KnowledgeAuditEntry {
+    /** ISO timestamp of the action. */
+    at: string;
+    /** Who performed it: the DataOps user id the Host resolved. */
+    actor: string;
+    /**
+     * That user's display name at the time of the action, when the Host resolved one.
+     *
+     * Kept beside the id rather than replacing it: the id is the identity an audit is
+     * checked against, while this is only what the trail is read as. Optional because
+     * logs written before it existed carry no label, and a reader must show such an
+     * entry by its id rather than drop it.
+     */
+    actorLabel?: string;
+    /** What they did. */
+    /**
+     * What they did.
+     *
+     * `edit` is a save of an existing document's bytes, kept distinct from `create`
+     * because the two answer different questions in a review: "who first put this
+     * here" and "who changed it last". A save through the host's own file editor
+     * reports here through a side channel (see the `audit.appended` route), which is
+     * what keeps the host's write path untouched.
+     */
+    action: 'create' | 'upload' | 'move' | 'approve' | 'reject' | 'edit';
+    /** The path the action concerned, relative to the knowledge root. */
+    relPath: string;
+    /** For a move, the destination path. */
+    toRelPath?: string;
+    /**
+     * What became of it.
+     *
+     * `pending` means it was parked for review, `applied` means it took effect,
+     * `rejected` means a reviewer refused it. The three are kept distinct because
+     * "nothing happened yet" and "somebody said no" are different facts, and an audit
+     * trail that collapsed them would misreport why a document is missing.
+     */
+    outcome: 'applied' | 'pending' | 'rejected';
+}
+/**
+ * Append one audit entry.
+ *
+ * Deliberately append-only: no update and no delete path exists in this module, because
+ * an audit trail a caller can rewrite is not an audit trail. The file is opened with
+ * `'a'`, so the write is a single append at the end and can never overwrite an earlier
+ * entry, even with two writers racing.
+ *
+ * Failure to record is NOT allowed to fail the action that was recorded. The caller has
+ * already made its change, so throwing here would report a failure that did not happen;
+ * the caller is expected to treat this as best-effort and the reason is logged by the
+ * host. That trade is deliberate: an audit gap is bad, but a reported-but-not-applied
+ * write is worse.
+ * @param viewDir - the user's view directory, created if absent.
+ * @param entry - the entry to record.
+ */
+export declare function appendAuditEntry(viewDir: string, entry: KnowledgeAuditEntry): Promise<void>;
+/**
+ * Read the newest audit entries, newest first.
+ *
+ * The whole file is read because it is a per-user, append-only log that grows by one
+ * short line per write; there is no rotation yet and pretending otherwise would add a
+ * seek that the format does not support. Unparseable lines are skipped rather than
+ * thrown: a half-written last line from a crash must not make the whole trail unreadable.
+ * @param viewDir - the user's view directory.
+ * @param limit - maximum entries to return, newest first.
+ * @returns The entries, newest first.
+ */
+export declare function readAuditEntries(viewDir: string, limit?: number): Promise<KnowledgeAuditEntry[]>;
+/** One stored template, as the index records it. */
+export interface TemplateRecord {
+    /** Derived from the stored document's name. */
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    tags: string[];
+    /** The document's stored file name, including its extension. */
+    fileName: string;
+    /** Last-modified instant, ISO-8601. */
+    updatedAt: string;
+}
+/**
+ * The template directory's absolute path.
+ * @param actualRoot - the authoritative tree's root.
+ * @returns The absolute directory.
+ */
+export declare function templateDirFor(actualRoot: string): string;
+/**
+ * Read the template index.
+ *
+ * Every failure answers an empty library, which is also the correct first-run state:
+ * a missing directory, a truncated index, and an index holding the wrong shape all
+ * resolve to "no templates yet". Never throws -- the library must render.
+ * @param actualRoot - the authoritative tree's root.
+ * @returns The template records, newest first.
+ */
+export declare function readTemplates(actualRoot: string): Promise<TemplateRecord[]>;
+/**
+ * Store one template: its document and its metadata.
+ *
+ * Replacing is keyed on the FILE NAME, not on a separate id, because the file name is
+ * the identity. A save that changes the name therefore writes a new document and
+ * removes the old one, which is what "rename this template" means; a save that keeps
+ * the name overwrites in place.
+ * @param actualRoot - the authoritative tree's root.
+ * @param input - the document text and metadata.
+ * @returns The stored record.
+ */
+export declare function saveTemplate(actualRoot: string, input: {
+    title: string;
+    description: string;
+    category: string;
+    tags: readonly string[];
+    fileName: string;
+    content?: string;
+    /** The template being edited, so its previous document is removed on a rename. */
+    id?: string;
+}): Promise<TemplateRecord>;
+/**
+ * Remove one template: its document and its record.
+ *
+ * Both halves go together, because a record without a document is a card that cannot
+ * be used and a document without a record is an invisible file. A missing document is
+ * not an error -- the record is what says the template exists, and removing it is the
+ * operation asked for.
+ * @param actualRoot - the authoritative tree's root.
+ * @param id - the template to remove.
+ * @returns Whether a template was removed.
+ */
+export declare function removeTemplate(actualRoot: string, id: string): Promise<boolean>;
+/**
+ * Stat one stored template's document, so the card can report its real size.
+ * @param actualRoot - the authoritative tree's root.
+ * @param fileName - the record's stored name.
+ * @returns Byte size, or 0 when the document is gone.
+ */
+export declare function templateBytes(actualRoot: string, fileName: string): Promise<number>;