@sparkelf/dsh-knowledge-base 0.1.4 → 0.1.20

package/lib/types/knowledgeTools.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Model-facing knowledge-base file tools (`kb_file_*`).
+ *
+ * The mounted tree is the one retrieval reads, but the plugin's write path is not
+ * "put bytes on disk": it decides permissions through DataOps, records an audit entry,
+ * keeps the caller's view in sync and records removals as tombstones. A shell write
+ * bypasses all of that, so the model gets tools that go through the same host
+ * operations as the HTTP routes.
+ *
+ * This module owns argument validation, the permission calls and the tool result
+ * shape. The host object is supplied by `index.ts`; it is the seam that reuses the
+ * existing `canReadPath` / `canWritePath` / `listDirectoryWithPermissions` /
+ * `readKnowledgeFile` / `createKnowledgeEntry` / `moveEntry` implementations, and it
+ * is what tests replace without importing the whole plugin.
+ *
+ * @module @sparkelf/dsh-knowledge-base/knowledgeTools
+ */
+import type { FtsIndexStats, FtsSearchResult } from './ftsIndex.ts';
+import type { OutlineKeyFact, OutlineTocEntry } from './outlineText.ts';
+import type { OutlineSectionSubmission, OutlineSummaryKind } from './outlineGuard.ts';
+import type { OutlineSaveResult } from './ftsIndex.ts';
+import type { KnowledgeAuditEntry } from './views.ts';
+/** Error codes a tool may report to the model. */
+export type KnowledgeToolErrorCode = 'empty-path' | 'nul-byte' | 'absolute-path' | 'escapes-knowledge-root' | 'forbidden' | 'not-found' | 'exists' | 'too-large' | 'binary' | 'not-a-directory' | 'not-a-file' | 'not-configured' | 'unauthorized' | 'unreachable' | 'bad-response' | 'write-failed' | 'invalid-regex' | 'invalid-citation' | 'invalid-summary' | 'invalid';
+/** Structured, model-readable failure. Thrown; never returned as a silent `false`. */
+export declare class KnowledgeToolError extends Error {
+    readonly code: KnowledgeToolErrorCode;
+    readonly path?: string;
+    constructor(code: KnowledgeToolErrorCode, message: string, path?: string);
+}
+/** The identity a tool call acts as. */
+export interface KnowledgeToolCaller {
+    userId: string;
+    label?: string;
+}
+/** One directory row, in view-relative coordinates. */
+export interface KnowledgeFileEntry {
+    relPath: string;
+    name: string;
+    isDir: boolean;
+    size?: number;
+    mtimeMs?: number;
+    canExtract?: boolean;
+    hasMarkdown?: boolean;
+}
+/** One search hit, in view-relative coordinates. */
+export interface KnowledgeFileHit {
+    relPath: string;
+    name: string;
+    inContent: boolean;
+    line?: string;
+    lineNumber?: number;
+    mtimeMs?: number;
+}
+/** One outline section as `kb_outline` returns it: navigation, never evidence. */
+export interface KnowledgeOutlineSection {
+    sectionId: string;
+    /** Full heading path (`第三章 > 第二十二条`). */
+    sectionPath: string;
+    /** 1-based depth; 1 is a chapter/top-level heading. */
+    level: number;
+    summary: string;
+    keyFacts: OutlineKeyFact[];
+    /** Chunks whose own heading is this section. */
+    chunkIds: number[];
+    /** Every chunk under this section, including descendants. */
+    sourceChunkIds: number[];
+}
+/** A document's INDEX.md outline. No chapter body is included. */
+export interface KnowledgeOutline {
+    docId: number;
+    /** Original source path (citable document). */
+    path: string;
+    displayPath?: string;
+    summary: string;
+    /** How the current summary was produced. */
+    summaryKind?: OutlineSummaryKind;
+    /** `missing` until `kb-summarize` saves a model-authored summary. */
+    summaryStatus?: 'ready' | 'missing';
+    /** Actionable next step when the summary is missing. */
+    hint?: string;
+    summaryVersion?: string;
+    /** Source chunk ids behind the document summary. */
+    sourceChunkIds?: number[];
+    toc: OutlineTocEntry[];
+    sections: KnowledgeOutlineSection[];
+    /** Absolute path of the generated `/nas/kb/index/md/<docId>.INDEX.md`. */
+    indexPath: string;
+}
+/** What reading a file produced. */
+export type KnowledgeFileRead = {
+    kind: 'text';
+    content: string;
+    truncated: boolean;
+    mtimeMs?: number;
+} | {
+    kind: 'binary';
+    size: number;
+};
+/** Audit outcome for a completed write: never turns a successful write into a failure. */
+export type KnowledgeAuditOutcome = {
+    written: true;
+} | {
+    written: false;
+    reason: string;
+};
+/** A view refresh that failed after the write itself succeeded. */
+export type KnowledgeViewSync = {
+    failure?: string;
+};
+/**
+ * The host operations the tools compose.
+ *
+ * Every method is the SAME implementation an HTTP route uses. The host owns permission
+ * policy and filesystem layout; this module never derives a root or a grant itself.
+ */
+export interface KnowledgeFileToolHost {
+    /** Resolve the caller (team: DataOps `/auth/me`; personal: the local operator). */
+    resolveCaller(): Promise<KnowledgeToolCaller>;
+    /** Backend DSH permission for this operation, when the host has a permission context. */
+    hasPermission?(permission: string): Promise<boolean>;
+    /** FTS5 search over the sidecar index, already scoped to the caller. */
+    searchIndex?(input: {
+        query: string;
+        scope?: string;
+        topK: number;
+    }): Promise<FtsSearchResult>;
+    /** Incremental index sync. */
+    syncIndex?(): Promise<FtsIndexStats>;
+    /** Explicitly vectorize one document, a directory subtree, or all targets. */
+    vectorize?(input: {
+        docId?: number;
+        path?: string;
+        scope?: string;
+        rebuild?: boolean;
+        dryRun?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Resolve a citation token to its original source + anchors. */
+    chunkGet?(input: {
+        docId: number;
+        chunkId: number | string;
+    }): Promise<{
+        docId: number;
+        chunkId: number;
+        chunkKey?: string;
+        citation?: string;
+        path: string;
+        quote?: string;
+        heading?: string;
+        paragraph?: number;
+        chunkOrdinal?: number;
+        paragraphText?: string;
+        sheet?: string;
+        cell?: string;
+        page?: number;
+        boxes: import('./ftsIndex.ts').FtsChunkBox[];
+        snippet: string;
+    }>;
+    /** Read/build one document outline, already permission-checked by the host. */
+    outline?(input: {
+        docId: number;
+    }): Promise<KnowledgeOutline>;
+    /** Re-render INDEX.md from stored summaries; never regenerates summary text. */
+    outlineRewrite?(input: {
+        docId: number;
+    }): Promise<{
+        indexPath: string;
+    }>;
+    /** Persist one model-authored outline after the host checked read+write permission. */
+    outlineSave?(input: {
+        docId: number;
+        summary: string;
+        sections: readonly OutlineSectionSubmission[];
+        summaryVersion?: string;
+    }): Promise<OutlineSaveResult | undefined>;
+    canRead(relPath: string): Promise<boolean>;
+    canWrite(relPath: string): Promise<boolean>;
+    /** One view directory level, already filtered by `canReadPath`. */
+    list(relPath: string, caller: KnowledgeToolCaller): Promise<KnowledgeFileEntry[]>;
+    /** Search under one view-relative scope. */
+    search(scope: string, query: string, limit: number): Promise<KnowledgeFileHit[]>;
+    /** Path boundary + `canReadPath` + `readKnowledgeFile`, shared with the read route. */
+    readAuthorized(relPath: string): Promise<KnowledgeFileRead>;
+    statEntry(relPath: string): Promise<{
+        kind: 'file' | 'directory';
+        size?: number;
+    } | undefined>;
+    createEntry(relPath: string, options: {
+        directory: boolean;
+        content?: string;
+    }): Promise<{
+        relPath: string;
+        kind: 'file' | 'directory';
+    }>;
+    /** Overwrite an existing file in place, preserving its inode/view hardlink. */
+    overwriteFile(relPath: string, content: string): Promise<void>;
+    moveEntry(from: string, to: string, caller: KnowledgeToolCaller): Promise<{
+        from: string;
+        to: string;
+    }>;
+    /** Record a tombstone in the caller's trash; never unlinks bytes. */
+    deleteToTrash(caller: KnowledgeToolCaller, relPath: string, kind: 'file' | 'directory'): Promise<void>;
+    refreshView(expectVisible?: string): Promise<KnowledgeViewSync>;
+    readSettings(caller: KnowledgeToolCaller): Promise<{
+        reviewRequired?: boolean;
+        mineruBaseUrl?: string;
+    }>;
+    parkWrite(caller: KnowledgeToolCaller, relPath: string, content: string): Promise<void>;
+    /** Enqueue one document; mirrors the manual extraction route's outcomes. */
+    enqueueExtraction(relPath: string, caller: KnowledgeToolCaller): Promise<{
+        outcome: 'already-markdown' | 'unsupported' | 'exists' | 'queued';
+        markdown?: string;
+        task?: unknown;
+    }>;
+    /** Extractable files under the authoritative root that have no `.md` sibling yet. */
+    listExtractCandidates(limit: number): Promise<string[]>;
+    viewDir(userId: string): string;
+    appendAudit(viewDir: string, entry: KnowledgeAuditEntry): Promise<void>;
+    isExtractable(relPath: string): boolean;
+    now?(): Date;
+}
+/** The sentence every tool carries: use these tools, not the shell. */
+export declare const KB_FILE_TOOL_GUIDANCE: string;
+/** Map a host failure to a structured tool error without losing its code. */
+export declare const asKnowledgeToolError: (error: unknown, path?: string) => KnowledgeToolError;
+/**
+ * Validate one model-supplied path in view coordinates.
+ *
+ * Empty is allowed only where the root itself is the argument (list/search/extract-all);
+ * everything else is refused with the same four codes `checkLocalPath` uses.
+ */
+export declare const assertToolPath: (value: unknown, allowRoot?: boolean) => string;
+/**
+ * Build the five file model-facing tools.
+ *
+ * Returned definitions are registered by `apply`; tests call the same definitions with
+ * a fake host to assert permission, path and audit behaviour without a live backend.
+ */
+export declare const createKnowledgeFileTools: (host: KnowledgeFileToolHost) => import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/types/localStoragePath.d.ts

@@ -0,0 +1,6 @@
+/** Directory holding the authoritative files under the storage root. */
+export declare const STORAGE_ACTUAL_DIR = "actual";
+/** Expand the UI's storage path into an absolute storage base. */
+export declare function resolveStorageRoot(raw: string, home?: string): string;
+/** The authoritative `actual/` directory for a storage base. */
+export declare function storageActualRoot(storageRoot: string): string;

package/lib/types/localStorageSettings.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Deployment-level settings for a LOCAL knowledge deployment.
+ *
+ * These values cannot live under `mountPoint`: the local mount point IS the
+ * configured storage root, so reading the setting from there would make the
+ * default impossible to discover after the operator points it somewhere else.
+ * A small file under `$DSH_HOME` breaks that cycle. It contains no credentials
+ * and no document content, only the one path the Settings page owns.
+ *
+ * @module @sparkelf/dsh-knowledge-base/local-storage-settings
+ */
+/** The local deployment fields the Settings page may change. */
+export interface LocalStorageSettings {
+    /** Authoritative root, absolute or `~/...`. */
+    storageRoot?: string;
+}
+/** Path of the profile-local settings file. */
+export declare function localStorageSettingsPath(home?: string, dshHome?: string | undefined): string;
+/**
+ * Read the local settings file, tolerating absence/corruption.
+ * @returns The stored fields, empty when nothing usable exists.
+ */
+export declare function readLocalStorageSettings(): Promise<LocalStorageSettings>;
+/**
+ * Store one storage-root choice atomically.
+ *
+ * The value is validated by the same resolver the view builder uses, so a
+ * relative path is rejected at write time rather than becoming a process-cwd
+ * surprise on the next restart.
+ * @param storageRoot - new root, absolute or `~/...`.
+ * @returns The normalised value actually written.
+ */
+export declare function writeLocalStorageRoot(storageRoot: string): Promise<string>;

package/lib/types/managementTools.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Model-facing management tools for the knowledge base and the workflow plaza.
+ *
+ * The UI already exposes these operations. This module gives the model the same
+ * operations without re-implementing authorization: every tool reads the backend
+ * review context (roles + department scope) and refuses with a structured 403 before
+ * touching the host. Writes additionally require an explicit human authorization flag,
+ * because a model deciding on its own must never be indistinguishable from an operator
+ * approving a review.
+ *
+ * Secrets are write-only through the UI; these tools deliberately reject secret-shaped
+ * fields and redact them on reads.
+ *
+ * @module @sparkelf/dsh-knowledge-base/managementTools
+ */
+/** A structured refusal the model can act on. */
+export declare class ManagementToolError extends Error {
+    readonly code: 'forbidden' | 'invalid' | 'not-found' | 'backend';
+    readonly name = "ManagementToolError";
+    constructor(code: 'forbidden' | 'invalid' | 'not-found' | 'backend', message: string);
+}
+/** The backend's review context, narrowed to the fields these tools use. */
+export interface ManagementContext {
+    readonly userId: string;
+    readonly username?: string;
+    readonly displayName?: string;
+    readonly primaryRole?: string;
+    readonly roleCodes: readonly string[];
+    /** Backend DSH permission keys resolved for the caller's roles. */
+    readonly permissions: readonly string[];
+    readonly departmentCode?: string | null;
+    readonly departmentPathCodes?: readonly string[];
+    readonly dataScope: {
+        readonly all: boolean;
+        readonly self: boolean;
+        readonly departmentCodes: readonly string[];
+    };
+    readonly review: {
+        readonly canReview: boolean;
+        readonly canReviewGlobal: boolean;
+        readonly canManagePermissions: boolean;
+        readonly departments: readonly string[];
+    };
+}
+/** One grant row as the host reports it. */
+export interface ManagementGrant {
+    readonly id?: string;
+    readonly relPath: string;
+    readonly kind?: string;
+    readonly principalType?: string;
+    readonly principalId?: string;
+    readonly action?: string;
+    readonly grantedBy?: string;
+    readonly grantedAt?: string;
+}
+/** One audit entry. */
+export interface ManagementAudit {
+    readonly at: string;
+    readonly actor: string;
+    readonly actorLabel?: string;
+    readonly action: string;
+    readonly relPath?: string;
+    readonly outcome?: string;
+}
+/** One KB pending submission. */
+export interface ManagementPending {
+    readonly name: string;
+    readonly userId: string;
+    readonly relPath: string;
+    readonly at: string;
+    readonly bytes: number;
+}
+/** One workflow row shared by the public and review lists. */
+export interface ManagementWorkflow {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly instruction?: string;
+    readonly cronHint?: string | null;
+    readonly category?: string | null;
+    readonly reviewStatus?: string;
+    readonly visibility?: string;
+    readonly departmentCode?: string | null;
+    readonly ownerId?: string;
+    readonly ownerName?: string;
+    readonly sourceSessionId?: string | null;
+    readonly builtIn?: boolean;
+}
+/** One visible bucket. */
+export interface ManagementBucket {
+    readonly name: string;
+    readonly visibility: string;
+    readonly departmentCode?: string | null;
+    readonly writable?: boolean;
+}
+/** The host operations tools compose. */
+export interface ManagementToolHost {
+    context(): Promise<ManagementContext>;
+    kbConfigGet(): Promise<Record<string, unknown>>;
+    kbConfigUpdate(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+    kbGrantList(): Promise<readonly ManagementGrant[]>;
+    kbGrantSet(input: {
+        relPath: string;
+        principalType: string;
+        principalId: string;
+        action: string;
+    }): Promise<ManagementGrant>;
+    kbAuditList(filter: {
+        action?: string;
+        actor?: string;
+        path?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+    }): Promise<readonly ManagementAudit[]>;
+    kbReviewList(): Promise<readonly ManagementPending[]>;
+    kbReviewDecide(input: {
+        name: string;
+        decision: 'approve' | 'reject';
+        note?: string;
+    }): Promise<unknown>;
+    kbSync(): Promise<unknown>;
+    kbIndexRebuild(): Promise<unknown>;
+    kbBucketList(): Promise<readonly ManagementBucket[]>;
+    workflowList(query: {
+        scope?: string;
+        status?: string;
+    }): Promise<readonly ManagementWorkflow[]>;
+    workflowUpdate(input: Record<string, unknown>): Promise<unknown>;
+    workflowUnpublish(id: string): Promise<unknown>;
+    workflowReviewList(query: {
+        status?: string;
+        scope?: string;
+        departmentCode?: string;
+    }): Promise<readonly ManagementWorkflow[]>;
+    workflowReviewScan(ids: readonly string[]): Promise<unknown>;
+    workflowReviewDecide(input: {
+        ids: readonly string[];
+        decision: 'approve' | 'reject';
+        note?: string;
+    }): Promise<unknown>;
+}
+type Capability = 'global' | 'reviewer' | 'reader';
+/** Role defaults used only when the permission matrix cannot be read (e.g. APP_USER). */
+export declare const DEFAULT_DSH_PERMISSIONS: Readonly<Record<string, readonly string[]>>;
+/** Union the default permission keys for a set of role system keys. */
+export declare function defaultPermissionsForRoles(roleKeys: readonly string[]): string[];
+/** True when the caller holds one backend permission key. */
+export declare function hasPermission(context: ManagementContext, permission: string): boolean;
+/** Require one backend permission key; a denial is a structured 403. */
+export declare function requirePermission(context: ManagementContext, permission: string, action?: string): void;
+/** Global administrators: all resources and all review queues. */
+export declare function isGlobalAdmin(context: ManagementContext): boolean;
+/** Department reviewers: their department and its descendants. */
+export declare function isDepartmentReviewer(context: ManagementContext): boolean;
+/** Require one capability; throws a structured 403 rather than returning false. */
+export declare function requireCapability(context: ManagementContext, capability: Capability): void;
+/** True when a path belongs to one of the caller's departments. */
+export declare function isPathInDepartmentScope(context: ManagementContext, relPath: string): boolean;
+/** Require department scope for one path; global admins bypass. */
+export declare function requirePathScope(context: ManagementContext, relPath: string): void;
+/** Publishing scope the workflow tool accepts. */
+export type WorkflowPublishVisibility = 'global' | 'department' | 'private';
+/**
+ * Normalize and authorize a publish scope.
+ *
+ * Ordinary users and department admins may only publish inside their own department
+ * (or privately); global visibility is reserved for platform admins. A department
+ * administrator cannot name a child/other department here even though review visibility
+ * can include descendants.
+ */
+export declare function normalizePublishScope(context: ManagementContext, visibility: WorkflowPublishVisibility | undefined, departmentCode: string | undefined): {
+    visibility: WorkflowPublishVisibility;
+    departmentCode: string;
+};
+/** Writes require an explicit human confirmation. */
+export declare function requireConfirmed(value: unknown): void;
+/** Refuse an object carrying a secret-shaped field. */
+export declare function assertNoSecretFields(value: unknown, path?: string): void;
+/** Redact secret-shaped values on reads. */
+export declare function redactSecrets<T>(value: T): T;
+/** Build all management tools. */
+export declare const createManagementTools: (host: ManagementToolHost) => import("@deepseek-ai/dsh-tools").ToolDefinition[];
+export {};

package/lib/types/outlineGuard.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Grounding checks for model-written document summaries.
+ *
+ * Uploading and extraction never create prose. A summary only enters the index when the
+ * `kb-summarize` skill has read the original chunks and the model submits it through
+ * `kb_outline_save`; this module is the gate between that submission and the database.
+ *
+ * The gate is deliberately mechanical. It does not judge whether a sentence is a good
+ * summary, because that is the model's job. It refuses a submission whose numbers,
+ * ratios, clause numbers or responsible bodies cannot be found in the source chunks the
+ * summary claims to describe. Normalization is strict but language-aware: full-width
+ * digits, Chinese numerals, `5万元`/`50000元`, `百分之三十`/`30%` and `第三条`/`第3条`
+ * all collapse to one token before comparison.
+ *
+ * @module @sparkelf/dsh-knowledge-base/outlineGuard
+ */
+import type { OutlineSection } from './outlineText.ts';
+/** How a document's current summary was produced. */
+export type OutlineSummaryKind = 'none' | 'extractive' | 'llm';
+/** One key fact as a model submits it. `value` is the source-grounded claim. */
+export interface OutlineKeyFactSubmission {
+    /** Article heading or label; defaults to the section title. */
+    fact?: string;
+    /** Threshold/ratio/body/exception sentence copied from the source. */
+    value: string;
+    /** Chunk the value came from; must belong to the document and the section. */
+    chunkId?: number;
+}
+/** One section summary as a model submits it. */
+export interface OutlineSectionSubmission {
+    sectionId: string;
+    /** Full heading path from `kb_outline`; a mismatch is refused rather than renamed. */
+    headingPath?: string;
+    summary?: string;
+    keyFacts?: Array<string | OutlineKeyFactSubmission>;
+    /** Chunks the summary was written from; must be a subset of the section's chunks. */
+    sourceChunkIds?: number[];
+}
+/** One refused field. The caller can show this to the model and retry. */
+export interface OutlineSaveRejection {
+    /** Dotted path within the submission, e.g. `sections[2].summary`. */
+    field: string;
+    reason: string;
+    sectionId?: string;
+    /** Bounded copy of the offending value, when one exists. */
+    value?: string;
+    /** Tokens/subjects that could not be found in the source chunks. */
+    missing?: string[];
+}
+/** A named section, as stored in `kb_sections`. */
+export type StoredOutlineSection = Pick<OutlineSection, 'sectionId' | 'headingPath' | 'title' | 'level' | 'summary' | 'keyFacts' | 'chunkIds' | 'sourceChunkIds'>;
+/** One chunk the gate may ground a claim against. */
+export interface GroundingChunk {
+    id: number;
+    content: string;
+}
+/** The complete, validated row set to persist. */
+export interface OutlineSavePlan {
+    summary: string;
+    /** Source chunks behind the document summary. */
+    docSourceChunkIds: number[];
+    /** Every section row, with submitted summaries replacing the stored ones. */
+    sections: StoredOutlineSection[];
+    keyFactCount: number;
+}
+/** Result of planning one save: either a plan, or the fields that were refused. */
+export type OutlineSavePlanResult = {
+    ok: true;
+    plan: OutlineSavePlan;
+} | {
+    ok: false;
+    rejected: OutlineSaveRejection[];
+};
+/** Maximum document summary length accepted from a model. */
+export declare const MAX_DOC_SUMMARY_CHARS = 4000;
+/** Maximum one section summary length accepted from a model. */
+export declare const MAX_SECTION_SUMMARY_CHARS = 2000;
+/** Maximum key facts one section may carry. */
+export declare const MAX_KEY_FACTS_PER_SECTION = 20;
+/** Maximum sections one save may carry. */
+export declare const MAX_SUBMITTED_SECTIONS = 500;
+/**
+ * Collapse presentation differences that do not change a claim.
+ *
+ * Used for source/claim comparison, never for display: the stored summary keeps the
+ * model's original wording (including Chinese numerals and full-width punctuation).
+ */
+export declare function normalizeOutlineGrounding(value: string): string;
+/** Convert a Chinese numeral (or digit string) to a number. */
+export declare function chineseNumberToArabic(raw: string): number | undefined;
+/**
+ * Extract the tokens a claim must share with its source.
+ *
+ * Tokens cover just the auditable classes: Arabic/Chinese numbers, percentages, Chinese
+ * fractions, ratios, clause numbers and common amounts. Ordinary prose is deliberately
+ * not tokenized, because a summary is allowed to paraphrase it.
+ */
+export declare function extractGroundingTokens(value: string): string[];
+/** Extract responsible-body terms from one claim. */
+export declare function extractSubjectTerms(value: string): string[];
+/** One submitted save request, as the planner sees it. */
+export interface OutlineSaveSubmission {
+    docId: number;
+    summary: string;
+    sections: readonly OutlineSectionSubmission[];
+}
+/**
+ * Validate and assemble the complete row set for one save.
+ *
+ * Nothing here touches SQLite or the filesystem. A refusal returns every rejected field
+ * so the model can repair the whole submission in one retry; a success returns the rows
+ * that will be written inside one transaction.
+ */
+export declare function planOutlineSave(input: {
+    docId: number;
+    chunks: readonly GroundingChunk[];
+    storedSections: readonly StoredOutlineSection[];
+    submission: OutlineSaveSubmission;
+}): OutlineSavePlanResult;