dsh-library 0.1.0

package/lib/types/config.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Config schema and resolution for `dsh-library`. Every tunable is a
+ * validated {@link Config} field changeable from cordis.yml (no hardcoded
+ * tunables); `resolveConfig` is the explicit resolution step that fails loud
+ * on out-of-range values and invalid embedder commands.
+ * @module dsh-library/config
+ */
+import z from '@deepseek-ai/schemastery';
+/** Library names: safe as domain keys and shown verbatim to the model. */
+export declare const LIBRARY_NAME: RegExp;
+/** Chunking defaults: window size and overlap, in characters. */
+export declare const DEFAULT_CHUNK_SIZE = 900;
+export declare const DEFAULT_CHUNK_OVERLAP = 120;
+/** Files larger than this are rejected with a clear error instead of being truncated. */
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+/** Absolute safety bound on one stored chunk (chunkSize must stay below it). */
+export declare const MAX_CHUNK_CHARS = 4000;
+/** Hash-embedding dimensionality used by the zero-download local embedder. */
+export declare const DEFAULT_EMBEDDING_DIMS = 256;
+/** Embedder subprocess budget. */
+export declare const DEFAULT_EMBEDDING_TIMEOUT_MS = 30000;
+export declare const DEFAULT_EMBEDDING_GRACE_MS = 1000;
+export declare const DEFAULT_EMBEDDING_MAX_OUTPUT_BYTES: number;
+export declare const DEFAULT_EMBEDDING_MAX_BATCH = 64;
+/** Search defaults. */
+export declare const DEFAULT_SEARCH_TOPK = 8;
+export declare const DEFAULT_SEARCH_HYBRID_WEIGHT = 0.6;
+export declare const DEFAULT_SEARCH_MIN_RELEVANCE = 0.15;
+export declare const DEFAULT_SEARCH_DIVERSITY_LAMBDA = 0.5;
+export declare const DEFAULT_SEARCH_MAX_RESULT_CHARS = 16000;
+/** Lost-in-the-middle avoidance: strongest results pinned to head and tail. */
+export declare const DEFAULT_LOST_MIDDLE_HEAD = 1;
+export declare const DEFAULT_LOST_MIDDLE_TAIL = 1;
+/** Injection defaults. */
+export declare const DEFAULT_INJECT_MAX_CHARS = 12000;
+/** Citation defaults. */
+export declare const DEFAULT_CITATION_WINDOW_CHARS = 150;
+export declare const DEFAULT_CITATION_MIN_SCORE = 40;
+export declare const DEFAULT_CITATION_MIN_SEMANTIC = 0.1;
+/** Purge verification defaults. */
+export declare const DEFAULT_PURGE_SIGNATURE_LENGTH = 4;
+export declare const DEFAULT_PURGE_MAX_PROBES = 24;
+/** Diagnose defaults. */
+export declare const DEFAULT_DIAGNOSE_MAX_DUPLICATE_PAIRS = 24;
+export declare const DEFAULT_DIAGNOSE_SAMPLE_CAP = 200;
+export declare const DEFAULT_DIAGNOSE_POSITION_BINS = 5;
+/** Embedder selection: built-in hash embedding, or an external command through `ctx.subprocess`. */
+export interface EmbeddingConfig {
+    /** Hash-embedding dimensionality (built-in embedder only). Must be ≥ 8. */
+    dims?: number;
+    /**
+     * Optional external embedder command line (space-separated, no shell
+     * interpretation; executed through `ctx.subprocess`). The command must read
+     * one JSON object per text line on stdin (`{"index": <n>, "text": "..."}`)
+     * and write one JSON object per line on stdout
+     * (`{"index": <n>, "vector": [<number>, ...]}`). Indices must cover every
+     * input line exactly once. When unset, the built-in deterministic hash
+     * embedder runs with zero downloads.
+     */
+    command?: string;
+    /** Cooperative timeout for one embedder invocation (ms). */
+    timeoutMs?: number;
+    /** Terminate-escalation grace handed to the subprocess seam (ms). */
+    graceMs?: number;
+    /** Max bytes of one embedder stdout before the batch fails. */
+    maxOutputBytes?: number;
+    /** Max texts embedded per subprocess invocation; larger batches are split. */
+    maxBatchItems?: number;
+}
+/** Search pipeline tuning (hybrid scoring → diversity re-rank → relevance filter → position strategy). */
+export interface SearchConfig {
+    /** How many chunks one search returns after the full pipeline. */
+    topK?: number;
+    /**
+     * Hybrid weight: 0 = keyword-only, 1 = semantic-only. Keyword and semantic
+     * scores are each normalized to 0..1 before combining.
+     */
+    hybridWeight?: number;
+    /** Chunks scoring below this relevance threshold are filtered out (fail closed to fewer, better results). */
+    minRelevance?: number;
+    /** Diversity re-rank weight: 1 = pure relevance order, 0 = pure diversity. */
+    diversityLambda?: number;
+    /** Strongest chunks pinned to the head of the context (lost-in-the-middle avoidance). */
+    lostMiddleHead?: number;
+    /** Strongest chunks pinned to the tail of the context. */
+    lostMiddleTail?: number;
+    /** Character budget for the model-facing result page; longer pages are truncated with a marker. */
+    maxResultChars?: number;
+}
+/** On-demand `agent.inject()` behavior of `library_search`. */
+export interface InjectionConfig {
+    /** Whether `library_search` with `inject: true` injects into the calling agent. */
+    enabled?: boolean;
+    /** Character budget of one injected context message. */
+    maxChars?: number;
+}
+/** Citation checking thresholds for `library_cite_check`. */
+export interface CitationConfig {
+    /** Context window (chars) around each citation marker that forms the claim. */
+    windowChars?: number;
+    /** Minimum fuzzy token-match score (0-100) for a citation to be valid. */
+    minScore?: number;
+    /** Minimum semantic similarity (hash embedding, 0-1) for a citation to be valid. */
+    minSemantic?: number;
+}
+/** Purge verification (RAG-Purge-Verify port) after `library_remove`. */
+export interface PurgeConfig {
+    /** Token n-gram length of the removed-content signatures scanned for residue. */
+    signatureLength?: number;
+    /** How many signatures are probed per removal; longer documents sample deterministically. */
+    maxProbes?: number;
+}
+/** `library_diagnose` budget caps. */
+export interface DiagnoseConfig {
+    /** Cap on reported near-duplicate chunk pairs. */
+    maxDuplicatePairs?: number;
+    /** Chunks sampled into the duplicate scan (the pair check is quadratic). */
+    sampleCap?: number;
+    /** How many position bins the lost-in-the-middle report uses. */
+    positionBins?: number;
+}
+/** Raw plugin config — every field optional; {@link Config} supplies the defaults. */
+export interface Config {
+    /** Sliding-window chunk size in characters. */
+    chunkSize?: number;
+    /** Sliding-window overlap in characters; must be smaller than {@link Config.chunkSize}. */
+    chunkOverlap?: number;
+    /** Max bytes of one imported file; larger files fail with a clear error. */
+    maxFileBytes?: number;
+    /** Embedding options (see {@link EmbeddingConfig}). */
+    embedding?: EmbeddingConfig;
+    /** Search pipeline options (see {@link SearchConfig}). */
+    search?: SearchConfig;
+    /** Injection options (see {@link InjectionConfig}). */
+    injection?: InjectionConfig;
+    /** Citation options (see {@link CitationConfig}). */
+    citation?: CitationConfig;
+    /** Purge options (see {@link PurgeConfig}). */
+    purge?: PurgeConfig;
+    /** Diagnose options (see {@link DiagnoseConfig}). */
+    diagnose?: DiagnoseConfig;
+}
+/** Resolved embedding config: defaults applied, `command` explicitly optional. */
+export interface ResolvedEmbeddingConfig {
+    readonly dims: number;
+    readonly command: string | undefined;
+    readonly timeoutMs: number;
+    readonly graceMs: number;
+    readonly maxOutputBytes: number;
+    readonly maxBatchItems: number;
+}
+/** Resolved search config after defaulting. */
+export interface ResolvedSearchConfig {
+    readonly topK: number;
+    readonly hybridWeight: number;
+    readonly minRelevance: number;
+    readonly diversityLambda: number;
+    readonly lostMiddleHead: number;
+    readonly lostMiddleTail: number;
+    readonly maxResultChars: number;
+}
+/** Resolved injection config after defaulting. */
+export interface ResolvedInjectionConfig {
+    readonly enabled: boolean;
+    readonly maxChars: number;
+}
+/** Resolved citation config after defaulting. */
+export interface ResolvedCitationConfig {
+    readonly windowChars: number;
+    readonly minScore: number;
+    readonly minSemantic: number;
+}
+/** Resolved purge config after defaulting. */
+export interface ResolvedPurgeConfig {
+    readonly signatureLength: number;
+    readonly maxProbes: number;
+}
+/** Resolved diagnose config after defaulting. */
+export interface ResolvedDiagnoseConfig {
+    readonly maxDuplicatePairs: number;
+    readonly sampleCap: number;
+    readonly positionBins: number;
+}
+/** Config after {@link resolveConfig}: every optional field has its explicit default. */
+export interface ResolvedConfig {
+    readonly chunkSize: number;
+    readonly chunkOverlap: number;
+    readonly maxFileBytes: number;
+    readonly embedding: ResolvedEmbeddingConfig;
+    readonly search: ResolvedSearchConfig;
+    readonly injection: ResolvedInjectionConfig;
+    readonly citation: ResolvedCitationConfig;
+    readonly purge: ResolvedPurgeConfig;
+    readonly diagnose: ResolvedDiagnoseConfig;
+}
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export declare const Config: z<Config>;
+/**
+ * Validate raw values and compile the resolved config. Defaults are applied
+ * HERE — the explicit resolution step — so a partially-specified config from
+ * a direct `ctx.plugin` mount behaves like the loader-filled one.
+ * @param config - raw (possibly partial) plugin config.
+ * @returns the fully resolved config.
+ * @throws TypeError on non-positive caps, an oversized chunk window, or an
+ *   embedder command without an executable part (misconfiguration fails loud).
+ */
+export declare function resolveConfig(config?: Config): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/lib/types/embedding.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Embedding pipeline: the built-in deterministic hash embedder (zero
+ * downloads — word tokens plus character tri-grams hashed into a signed
+ * bucket vector, L2-normalized), the optional external embedder command
+ * protocol over `ctx.subprocess`, and the cosine/dot utilities the scoring
+ * modules share.
+ * @module dsh-library/embedding
+ */
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Embed one text with the built-in hash embedder. Each word token and each
+ * character tri-gram hashes (FNV-1a) to a signed bucket: the index is the
+ * hash modulo `dims` and the sign is the hash's high bit. The result is
+ * L2-normalized so cosine similarity is a dot product.
+ * @param text - input text.
+ * @param dims - vector dimensionality (≥ 1).
+ * @returns the normalized embedding as a plain number array.
+ */
+export declare function embedHash(text: string, dims: number): number[];
+/**
+ * Cosine similarity of two equal-length vectors (already-normalized vectors
+ * make this a plain dot product, but the function normalizes anyway).
+ * @param a - first vector.
+ * @param b - second vector.
+ * @returns similarity within 0..1 for non-negative-input vectors.
+ */
+export declare function cosine(a: readonly number[], b: readonly number[]): number;
+/**
+ * Run the configured external embedder command once over a text batch.
+ * The protocol is JSON lines both ways: each stdin line is
+ * `{"index": <n>, "text": "..."}` and each stdout line is
+ * `{"index": <n>, "vector": [<number>, ...]}`. Every requested index must be
+ * answered exactly once or the call fails closed (misconfiguration must
+ * surface, not silently degrade retrieval).
+ * @param subprocess - the mounted `ctx.subprocess` service.
+ * @param argv - the configured command line split into argv (argv[0] = program).
+ * @param cwd - working directory for the child.
+ * @param texts - the texts to embed, in index order.
+ * @param dims - expected vector dimensionality.
+ * @param caps - timeout, grace, and output caps.
+ * @returns embeddings in the same order as {@link texts}.
+ * @throws Error on spawn failure, non-zero exit, or an incomplete/oversized answer.
+ */
+export declare function embedWithCommand(subprocess: SubprocessRuntime, argv: readonly string[], cwd: string, texts: readonly string[], dims: number, caps: {
+    timeoutMs: number;
+    graceMs: number;
+    maxOutputBytes: number;
+}): Promise<number[][]>;
+/**
+ * Split a flat command line into argv without shell interpretation.
+ * Whitespace separates; quotes are NOT processed (documented: no shell).
+ * @param command - the configured command string.
+ * @returns the argv vector; an empty string yields an empty vector.
+ */
+export declare function splitCommandLine(command: string): string[];
+//# sourceMappingURL=embedding.d.ts.map

package/lib/types/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAIpE;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAU9D;AAcD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAYzE;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,iBAAiB,EAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACnE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CA0CrB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1D"}

package/lib/types/ids.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Identity minting for dsh-library records: content-derived document ids,
+ * per-chunk ids, and the unique ids that link injected model-visible text
+ * back to its `library/inject` session event (model-visible ⟺ logged).
+ * @module dsh-library/ids
+ */
+/** Stable document id: first 16 hex chars of the SHA-256 of its content. */
+export declare function documentIdOf(content: string): string;
+/** Chunk id: the owning document id plus the chunk sequence. */
+export declare function chunkIdOf(documentId: string, seq: number): string;
+/** Parse a chunk id back into its document id and sequence; null when malformed. */
+export declare function parseChunkId(chunkId: string): {
+    documentId: string;
+    seq: number;
+} | null;
+/** One purge-verification run's identity, recorded in the purges table. */
+export declare function purgeId(): string;
+/**
+ * One injection's identity: embedded in the injected marker text so the
+ * model-visible message is reconstructable from the `library/inject` event.
+ */
+export declare function injectId(): string;
+/** Domain record key of one document inside the `documents` table. */
+export declare function documentKey(library: string, documentId: string): string;
+/** Domain record key of one chunk inside the `chunks` table. */
+export declare function chunkKey(library: string, chunkId: string): string;
+//# sourceMappingURL=ids.d.ts.map

package/lib/types/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/ids.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMxF;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/lib/types/index.d.ts

@@ -0,0 +1,248 @@
+/**
+ * `dsh-library` — the local-first knowledge base for DeepSeek Harness:
+ * import md/txt documents into a storage-domain index, retrieve with a
+ * hybrid semantic+keyword pipeline (diversity re-rank, relevance filter,
+ * lost-in-the-middle avoidance), verify citations against retrieved chunks,
+ * and diagnose chunk/retrieval quality. Everything model-visible carries a
+ * source marker and is reconstructable from the `library/inject` session
+ * event; document paths and embeddings never reach the log.
+ *
+ * Function plugin — no default export (the Loader unwraps
+ * `exports.default ?? exports`).
+ * @module dsh-library
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type Domain } from '@deepseek-ai/dsh-storage-domain';
+import { z as zod } from 'zod';
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+import { Config, type ResolvedConfig } from './config.ts';
+import { chunkSizeHistogram } from './quality/chunk-visual.ts';
+export declare const name = "dsh-library";
+/** Hard services: the durable index lives in the storage domain; tools and the command register here. */
+export declare const inject: string[];
+export { Config, resolveConfig, LIBRARY_NAME } from './config.ts';
+export type { ResolvedConfig, EmbeddingConfig, SearchConfig, InjectionConfig, CitationConfig, PurgeConfig, DiagnoseConfig } from './config.ts';
+export { embedHash, cosine, splitCommandLine } from './embedding.ts';
+export { CHUNK_SIZE_BUCKETS, chunkSizeHistogram, chunkText, chunkHash, findDuplicateChunks } from './quality/chunk-visual.ts';
+export type { Chunk, ChunkSizeHistogram, ChunkDiagnostics } from './quality/chunk-visual.ts';
+export { checkDiversity, maximalMarginalRelevance } from './quality/diversity.ts';
+export type { DiversityReport, RerankCandidate, DuplicatePair } from './quality/diversity.ts';
+export { successByPosition, makeProbe, insertProbe, buildProbePrompt, avoidLostMiddle, positionBins, middlePenalty, PROBE_PREFIX } from './quality/lost-middle.ts';
+export type { ProbeResult, PositionStats, RankedItem, PositionBin } from './quality/lost-middle.ts';
+export { scoreRelevance, scoreBatch, filterDocuments } from './quality/relevance.ts';
+export type { ScoredDocument } from './quality/relevance.ts';
+export { validateQaPair, selectFewShot, formatFewShotPrompt } from './quality/few-shot.ts';
+export type { QaExample, SelectedExample, FewShotOptions } from './quality/few-shot.ts';
+export { extractCitations, extractContext, verifyReferences } from './quality/reference.ts';
+export type { CitationMarker, ReferenceDocument, ReferenceVerdict, ReferenceReport, ReferenceOptions } from './quality/reference.ts';
+export { extractCitationNumbers, extractSentenceWithCitation, fuzzyPartialRatio, validateCitation, validateCitations } from './quality/citation.ts';
+export type { CitationMatch, ValidationResult } from './quality/citation.ts';
+export { verifyPurge, sampleSignatures } from './quality/purge.ts';
+export type { RemainingChunk, PurgeProbeResult, PurgeReport, PurgeOptions } from './quality/purge.ts';
+/** The dsh-library storage-domain declaration (unit names allow `[a-z][a-z0-9_]*` only). */
+export declare const libraryDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        documents: {
+            valueSchema: zod.ZodObject<{
+                library: zod.ZodString;
+                documentId: zod.ZodString;
+                name: zod.ZodString;
+                contentHash: zod.ZodString;
+                chunks: zod.ZodArray<zod.ZodString>;
+                chars: zod.ZodNumber;
+                createdAt: zod.ZodNumber;
+            }, zod.core.$strip>;
+        };
+        chunks: {
+            valueSchema: zod.ZodObject<{
+                library: zod.ZodString;
+                chunkId: zod.ZodString;
+                documentId: zod.ZodString;
+                seq: zod.ZodNumber;
+                text: zod.ZodString;
+                embedding: zod.ZodArray<zod.ZodNumber>;
+            }, zod.core.$strip>;
+        };
+        purges: {
+            valueSchema: zod.ZodObject<{
+                purgeId: zod.ZodString;
+                library: zod.ZodString;
+                documentId: zod.ZodString;
+                passed: zod.ZodBoolean;
+                totalFound: zod.ZodNumber;
+                at: zod.ZodNumber;
+            }, zod.core.$strip>;
+        };
+    };
+};
+/** The session audit events (declaration merging; model-visible ⟺ logged). */
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** One `library_search` injection: id links the injected marker text back to this event. */
+        'library/inject': {
+            injectId: string;
+            library: string;
+            query: string;
+            chunks: string[];
+            chars: number;
+        };
+        /** One `library_remove` purge verification outcome. */
+        'library/purge': {
+            purgeId: string;
+            library: string;
+            documentId: string;
+            passed: boolean;
+            totalFound: number;
+        };
+    }
+}
+/** Optional seams read at call time (fail closed when absent). */
+interface StoreDeps {
+    readonly subprocess: SubprocessRuntime | undefined;
+}
+/** One `library_add` outcome. */
+export interface LibraryAddResult {
+    readonly library: string;
+    readonly documentId: string;
+    readonly name: string;
+    readonly chunks: number;
+    readonly chars: number;
+}
+/** One `library_remove` outcome, including the purge verification. */
+export interface LibraryRemoveResult {
+    readonly library: string;
+    readonly documentId: string;
+    readonly removedChunks: number;
+    readonly purgePassed: boolean;
+    readonly purgeTotalFound: number;
+}
+/** One `library_list` entry (no text). */
+export interface LibraryListEntry {
+    readonly library: string;
+    readonly documentId: string;
+    readonly name: string;
+    readonly chunks: number;
+    readonly chars: number;
+    readonly createdAt: number;
+}
+/** One `library_search` hit. */
+export interface LibrarySearchHit {
+    readonly chunkId: string;
+    readonly documentId: string;
+    readonly seq: number;
+    /** Snippet of the chunk text (sanitized, capped). */
+    readonly snippet: string;
+    /** Final combined score (post re-rank order is positional, not this value). */
+    readonly score: number;
+}
+/** The `library_search` canonical result. */
+export interface LibrarySearchResult {
+    readonly library: string;
+    readonly query: string;
+    readonly results: LibrarySearchHit[];
+    /** True when the result page was injected into the calling agent. */
+    readonly injected: boolean;
+}
+/** One `library_cite_check` citation verdict. */
+export interface LibraryCiteVerdict {
+    readonly citation: string;
+    readonly sourceDocumentId: string;
+    readonly sourceSeq: number;
+    readonly valid: boolean;
+    readonly fuzzyScore: number;
+    readonly semanticSimilarity: number;
+    readonly reason: string;
+}
+/** The `library_cite_check` report. */
+export interface LibraryCiteReport {
+    readonly library: string;
+    readonly query: string;
+    readonly total: number;
+    readonly valid: number;
+    readonly details: LibraryCiteVerdict[];
+}
+/** The `library_diagnose` report. */
+export interface LibraryDiagnoseReport {
+    readonly library: string;
+    readonly documents: number;
+    readonly chunks: number;
+    readonly histogram: ReturnType<typeof chunkSizeHistogram>;
+    readonly duplicatePairs: number;
+    readonly selfRetrieval: {
+        probes: number;
+        topKHit: number;
+    };
+    readonly middlePenalty: number;
+}
+/**
+ * The index runtime over one open storage domain: add/remove/list/search/
+ * cite/diagnose. All record shapes are validated by the domain at the
+ * durable boundary; this class never logs text or embeddings.
+ */
+export declare class LibraryStore {
+    private readonly config;
+    private readonly deps;
+    private readonly documents;
+    private readonly chunks;
+    private readonly purges;
+    /**
+     * @param domain - the opened dsh-library domain.
+     * @param config - resolved plugin config.
+     * @param deps - optional subprocess seam for the external embedder.
+     */
+    constructor(domain: Domain<typeof libraryDomainSpec>, config: ResolvedConfig, deps: StoreDeps);
+    /** Embed a text batch with the configured embedder (external command when set). */
+    private embed;
+    /**
+     * Import one document: chunk it, embed the chunks, and store the records.
+     * @param library - target library name.
+     * @param docName - display name.
+     * @param content - full document text.
+     * @returns the add summary.
+     */
+    add(library: string, docName: string, content: string): Promise<LibraryAddResult>;
+    /**
+     * Remove one document and verify the purge: the removed content must leave
+     * no residue in the remaining chunks of the library.
+     * @param library - owning library name.
+     * @param documentId - stable document id.
+     * @returns the removal summary plus the purge verdict.
+     */
+    remove(library: string, documentId: string): Promise<LibraryRemoveResult>;
+    /** List documents (metadata only, never text) of one library or every library. */
+    list(library?: string): LibraryListEntry[];
+    /** All chunk records of one library, in document/seq order. */
+    private chunksOf;
+    /**
+     * The hybrid retrieval pipeline: keyword + semantic scores, diversity
+     * re-rank, relevance filter, lost-in-the-middle reorder, character budget.
+     * @param library - library to search.
+     * @param query - the query text.
+     * @param topK - result cap (default from config).
+     * @returns ranked hits.
+     */
+    search(library: string, query: string, topK?: number): Promise<LibrarySearchHit[]>;
+    /** The citation sources for one query: the search pipeline result in order. */
+    citeCheck(library: string, query: string, answer: string): Promise<LibraryCiteReport>;
+    /** Diagnose one library: chunk stats, duplicates, self-retrieval, middle penalty. */
+    diagnose(library: string): Promise<LibraryDiagnoseReport>;
+}
+/** The store service shared by every tool and the command. */
+interface LibraryServices {
+    readonly ctx: Context;
+    readonly config: ResolvedConfig;
+    readonly store: LibraryStore;
+}
+/**
+ * Mount the plugin: open the storage domain, build the store, register the
+ * tool family and the `/library` command. One effect owns the domain handle;
+ * every registration is its own reversible effect.
+ * @param ctx - the plugin context.
+ * @param config - raw loader config; defaults applied through {@link resolveConfig}.
+ */
+export declare function apply(ctx: Context, config?: Config): Promise<void>;
+/** Every tool definition, in registration order. */
+export declare function allTools(services: LibraryServices): import("@deepseek-ai/dsh-tools").ToolDefinition[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/lib/types/quality/chunk-visual.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Port of RAG-Chunk-Visualizer (upstream/PerryLink, Apache-2.0): the
+ * sliding-window `chunk_text` algorithm plus the structured diagnostics that
+ * power `library_diagnose`. Pure functions — no I/O, no model.
+ * @module dsh-library/quality/chunk-visual
+ */
+/** One sliding-window chunk, mirroring the upstream `Chunk` dataclass. */
+export interface Chunk {
+    readonly text: string;
+    readonly startPos: number;
+    readonly endPos: number;
+    readonly index: number;
+    readonly overlapChars: number;
+}
+/**
+ * Slice one text into sliding-window chunks — the exact algorithm of the
+ * upstream `chunk_text`. Validation matches upstream: `chunkSize` > 0,
+ * `overlap` ≥ 0 and strictly smaller than `chunkSize`.
+ * @param text - the text to slice.
+ * @param chunkSize - window width in characters.
+ * @param overlap - overlap between consecutive windows in characters.
+ * @returns the chunk list (empty for empty input).
+ * @throws TypeError on invalid parameters.
+ */
+export declare function chunkText(text: string, chunkSize: number, overlap: number): Chunk[];
+/** Size-bucket boundary: powers of two from 256 chars up (diagnose histogram). */
+export declare const CHUNK_SIZE_BUCKETS: readonly number[];
+/** Per-bucket character counts of one chunk list. */
+export interface ChunkSizeHistogram {
+    readonly buckets: readonly {
+        label: string;
+        min: number;
+        max: number | null;
+        count: number;
+    }[];
+    readonly minChars: number;
+    readonly maxChars: number;
+    readonly meanChars: number;
+    readonly totalChars: number;
+}
+/**
+ * Bucket one chunk list into size classes and fold the basic size facts.
+ * @param chunks - the chunks to analyze.
+ * @returns the histogram and size summary.
+ */
+export declare function chunkSizeHistogram(chunks: readonly Chunk[]): ChunkSizeHistogram;
+/** Folded structural statistics of one document's chunk list. */
+export interface ChunkDiagnostics {
+    readonly chunkCount: number;
+    readonly totalChars: number;
+    readonly histogram: ChunkSizeHistogram;
+    /** How many of the total chars live in overlapping windows (redundancy signal). */
+    readonly overlapChars: number;
+    /** overlapChars as a percentage of totalChars. */
+    readonly overlapPercent: number;
+    /** True when the last chunk is shorter than the others (a normal, expected tail). */
+    readonly truncatedTail: boolean;
+    /** Maximum single-chunk char count. */
+    readonly maxChunkChars: number;
+}
+/**
+ * Fold the structural diagnostics of one chunk list — the visualization
+ * module's numbers without any rendering.
+ * @param chunks - the chunks to analyze.
+ * @returns the folded diagnostics.
+ */
+export declare function diagnoseChunks(chunks: readonly Chunk[]): ChunkDiagnostics;
+/**
+ * Stable per-chunk content hash (FNV-1a) — the duplicate-detection key.
+ * @param chunk - the chunk to hash.
+ * @returns the hex hash.
+ */
+export declare function chunkHash(chunk: Chunk): string;
+/** One detected near-duplicate pair. */
+export interface DuplicatePair {
+    readonly indexA: number;
+    readonly indexB: number;
+    readonly similarity: number;
+}
+/**
+ * Find exact and near-duplicate chunk pairs by cosine similarity over the
+ * pair's shared token vocabulary (the diversity module's measure). The scan
+ * is quadratic, so callers bound the input.
+ * @param chunks - the chunks to scan.
+ * @param threshold - similarity above which a pair counts as duplicate.
+ * @param maxPairs - cap on reported pairs (the scan still computes the count).
+ * @returns reported pairs and the duplicate count.
+ */
+export declare function findDuplicateChunks(chunks: readonly Chunk[], threshold: number, maxPairs: number): {
+    pairs: DuplicatePair[];
+    duplicateCount: number;
+};
+//# sourceMappingURL=chunk-visual.d.ts.map