@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/discovery/test-support.js

@@ -0,0 +1,127 @@
+// Test-only helpers for the discovery layer. Not exported from the package barrel —
+// trust-8 (test-support naming) keeps production code from importing this module.
+function toAbs(root, rel) {
+    if (rel === "")
+        return root;
+    return root.endsWith("/") ? `${root}${rel}` : `${root}/${rel}`;
+}
+function entriesByPrefix(root, files, dirAbs) {
+    const prefix = dirAbs === root ? `${root}/` : `${dirAbs}/`;
+    const dirNames = new Set();
+    const fileNames = new Set();
+    for (const relPath of files.keys()) {
+        const full = toAbs(root, relPath);
+        if (!full.startsWith(prefix))
+            continue;
+        const rest = full.slice(prefix.length);
+        const slash = rest.indexOf("/");
+        if (slash === -1) {
+            fileNames.add(rest);
+        }
+        else {
+            dirNames.add(rest.slice(0, slash));
+        }
+    }
+    const dirs = [...dirNames].map((name) => ({
+        name,
+        isDirectory: true,
+        isFile: false,
+        isSymbolicLink: false,
+    }));
+    const filesArr = [...fileNames].map((name) => ({
+        name,
+        isDirectory: false,
+        isFile: true,
+        isSymbolicLink: false,
+    }));
+    return [...dirs, ...filesArr];
+}
+function buildMap(files) {
+    const encoder = new TextEncoder();
+    const map = new Map();
+    for (const f of files) {
+        const bytes = typeof f.content === "string" ? encoder.encode(f.content) : f.content;
+        const entry = {
+            content: bytes,
+            ...(f.realPathOverride !== undefined ? { realPathOverride: f.realPathOverride } : {}),
+            ...(f.hardLinkCount !== undefined ? { hardLinkCount: f.hardLinkCount } : {}),
+            ...(f.isSymbolicLink !== undefined ? { isSymbolicLink: f.isSymbolicLink } : {}),
+        };
+        map.set(f.relativePath, entry);
+    }
+    return map;
+}
+function memoryStat(root, map, findKey) {
+    return (absolutePath) => {
+        const key = findKey(absolutePath);
+        if (key === undefined) {
+            const hasChildren = [...map.keys()].some((k) => toAbs(root, k).startsWith(`${absolutePath}/`));
+            if (hasChildren || absolutePath === root) {
+                return { size: 0, isFile: false, isDirectory: true, isSymbolicLink: false };
+            }
+            throw new Error(`ENOENT: ${absolutePath}`);
+        }
+        return {
+            size: map.get(key)?.content.byteLength ?? 0,
+            isFile: true,
+            isDirectory: false,
+            isSymbolicLink: map.get(key)?.isSymbolicLink ?? false,
+            hardLinkCount: map.get(key)?.hardLinkCount,
+        };
+    };
+}
+export function memoryFs(root, files) {
+    const map = buildMap(files);
+    const findKey = (absolutePath) => {
+        for (const key of map.keys()) {
+            if (toAbs(root, key) === absolutePath)
+                return key;
+        }
+        return undefined;
+    };
+    return {
+        readFileUtf8: (absolutePath) => {
+            const key = findKey(absolutePath);
+            if (key === undefined)
+                throw new Error(`ENOENT: ${absolutePath}`);
+            return new TextDecoder("utf-8").decode(map.get(key)?.content ?? new Uint8Array());
+        },
+        stat: memoryStat(root, map, findKey),
+        readDir: (absolutePath) => entriesByPrefix(root, map, absolutePath),
+        realPath: (absolutePath) => {
+            const key = findKey(absolutePath);
+            const override = key === undefined ? undefined : map.get(key)?.realPathOverride;
+            return override ?? absolutePath;
+        },
+        exists: (absolutePath) => findKey(absolutePath) !== undefined || absolutePath === root,
+        readFileBytes: (absolutePath, maxBytes) => {
+            const key = findKey(absolutePath);
+            if (key === undefined)
+                return Promise.reject(new Error(`ENOENT: ${absolutePath}`));
+            const buf = map.get(key)?.content ?? new Uint8Array();
+            const cap = Math.max(0, Math.floor(maxBytes));
+            return Promise.resolve(buf.subarray(0, Math.min(buf.length, cap)));
+        },
+        readFileRange: (absolutePath, startByte, length) => {
+            const key = findKey(absolutePath);
+            if (key === undefined)
+                return Promise.reject(new Error(`ENOENT: ${absolutePath}`));
+            const buf = map.get(key)?.content ?? new Uint8Array();
+            const start = Math.max(0, Math.floor(startByte));
+            const cap = Math.max(0, Math.floor(length));
+            return Promise.resolve(buf.subarray(start, Math.min(buf.length, start + cap)));
+        },
+    };
+}
+export function folderScope(rootPath, options = {}) {
+    const base = {
+        kind: "folder",
+        rootPath,
+        recursive: options.recursive ?? true,
+    };
+    return {
+        ...base,
+        ...(options.includeGlobs !== undefined ? { includeGlobs: options.includeGlobs } : {}),
+        ...(options.excludeGlobs !== undefined ? { excludeGlobs: options.excludeGlobs } : {}),
+    };
+}

package/dist/discovery/types.d.ts

@@ -0,0 +1,63 @@
+import type { DocumentId, DocumentRecord, KnowledgeCapsuleId, KnowledgeSourceId, ParserDiagnostic } from "@oscharko-dev/keiko-contracts";
+export interface DiscoveredFile {
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+}
+export interface DiscoveryOptions {
+    readonly maxDepth: number;
+    readonly maxFiles: number;
+    readonly signal?: AbortSignal;
+}
+export declare const DEFAULT_DISCOVERY_OPTIONS: DiscoveryOptions;
+export type DiscoveryErrorCode = "PATH_ESCAPE" | "READ_FAILED" | "OVERSIZED_FILE" | "UNSUPPORTED_FORMAT" | "CANCELLED" | "MALFORMED_INPUT" | "PARSER_TIMEOUT" | "PARSER_FAILED" | "STAT_FAILED" | "INVALID_SCOPE";
+export interface DiscoveryError {
+    readonly code: DiscoveryErrorCode;
+    readonly message: string;
+    readonly relativePath?: string;
+}
+export type ExtractionOutcome = {
+    readonly kind: "persisted";
+    readonly document: DocumentRecord;
+} | {
+    readonly kind: "skipped";
+    readonly document: DocumentRecord;
+    readonly reason: "unchanged";
+} | {
+    readonly kind: "failed";
+    readonly document: DocumentRecord;
+    readonly error: DiscoveryError;
+};
+export interface ExtractionResult {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly relativePath: string;
+    readonly outcome: ExtractionOutcome;
+    readonly diagnostics: readonly ParserDiagnostic[];
+}
+export type ExtractionEvent = {
+    readonly kind: "file-discovered";
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+} | {
+    readonly kind: "file-extracted";
+    readonly result: ExtractionResult;
+} | {
+    readonly kind: "scope-error";
+    readonly error: DiscoveryError;
+} | {
+    readonly kind: "cancelled";
+    readonly reason: string;
+} | {
+    readonly kind: "completed";
+    readonly totalDiscovered: number;
+    readonly totalExtracted: number;
+    readonly totalSkipped: number;
+    readonly totalFailed: number;
+};
+export interface DocumentIdSource {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly relativePath: string;
+}
+export declare function documentIdFor(input: DocumentIdSource): DocumentId;
+//# sourceMappingURL=types.d.ts.map

package/dist/discovery/types.d.ts.map

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

package/dist/discovery/types.js

@@ -0,0 +1,28 @@
+// Discovery + extraction types for the Local Knowledge Connector (Epic #189, Issue #194).
+// The discovery layer is the bridge between a `KnowledgeSource` and a `KnowledgeStore`:
+// it walks files in scope via the workspace `WorkspaceFs` port, hands each file to the
+// parser registry, and persists the document/page/section/parsed-unit/diagnostic rows.
+// Chunks and vectors are NOT written here — those are #195 (chunking) and #196 (indexing).
+//
+// `DiscoveryError.code` is a closed string union so downstream UI surfaces and the eventual
+// audit ledger entries can branch on stable identifiers rather than free-form messages.
+export const DEFAULT_DISCOVERY_OPTIONS = {
+    maxDepth: 12,
+    maxFiles: 5_000,
+};
+// Branded helper so callers (extract.ts) don't need to repeat the cast. The returned id is
+// deterministic in `(capsuleId, sourceId, relativePath)` so a re-walk of the same scope
+// targets the SAME `documents` row — that's the lineage anchor for incremental updates.
+//
+// Delimiter characters are percent-escaped before embedding so that the three tuple members
+// stay injective even when source ids or paths contain `:`, `%`, or `#`. Ordinary paths keep
+// their historical ids; only collision-capable characters are escaped.
+function encodeDocumentIdComponent(value) {
+    return value.replace(/%/g, "%25").replace(/#/g, "%23").replace(/:/g, "%3A");
+}
+export function documentIdFor(input) {
+    const encodedCapsuleId = encodeDocumentIdComponent(String(input.capsuleId));
+    const encodedSourceId = encodeDocumentIdComponent(String(input.sourceId));
+    const encodedPath = encodeDocumentIdComponent(input.relativePath);
+    return `doc:${encodedCapsuleId}:${encodedSourceId}:${encodedPath}`;
+}

package/dist/discovery/walk.d.ts

@@ -0,0 +1,12 @@
+import type { KnowledgeSourceScope } from "@oscharko-dev/keiko-contracts";
+import type { WorkspaceFs } from "@oscharko-dev/keiko-workspace";
+import { type DiscoveredFile, type DiscoveryError, type DiscoveryOptions } from "./types.js";
+export type WalkYield = {
+    readonly kind: "file";
+    readonly file: DiscoveredFile;
+} | {
+    readonly kind: "error";
+    readonly error: DiscoveryError;
+};
+export declare function walkSource(fs: WorkspaceFs, scope: KnowledgeSourceScope, options?: DiscoveryOptions): Generator<WalkYield>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/discovery/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../src/discovery/walk.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,+BAA+B,CAAC;AAIhF,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AAMpB,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAqT/D,wBAAiB,UAAU,CACzB,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE,gBAA4C,GACpD,SAAS,CAAC,SAAS,CAAC,CAoBtB"}

package/dist/discovery/walk.js

@@ -0,0 +1,302 @@
+// Scope walker (Epic #189, Issue #194). Given a KnowledgeSourceScope and a WorkspaceFs port,
+// yields each in-scope file as a `DiscoveredFile`. Boundary guarantees, in order of check:
+//
+//   1. The scope's rootPath is rejected when it fails the contract validator's safe-path
+//      gate (NUL, `..`, root markers, tilde, Windows drive prefix).
+//   2. Every yielded file's `relativePath` joined to the scope root resolves via
+//      `WorkspaceFs.realPath` to a path STILL UNDER the scope root. A symlink whose
+//      realpath escapes the root is dropped and reported via `walkSource`'s second yield
+//      channel (an InvalidEntry record) rather than thrown — that lets the caller log a
+//      `PATH_ESCAPE` diagnostic against the file instead of aborting the whole walk.
+//   3. The workspace deny list is enforced on every discovered descendant, including explicit
+//      `files` scopes. Hidden/generated-directory opt-in never relaxes the security deny list.
+//   4. Include/exclude globs are applied on the workspace-relative POSIX path; exclude
+//      wins on overlap.
+//   5. AbortSignal is checked at every directory boundary.
+//
+// Returns an async iterable of `WalkYield` values. The walker is otherwise PURE — no
+// clock reads, no randomness — and the WorkspaceFs port is the only IO surface.
+import { isSafeScopePath } from "@oscharko-dev/keiko-contracts";
+import { isDenied } from "@oscharko-dev/keiko-workspace";
+import { compileGlobList, matchesAny } from "./glob.js";
+import { DEFAULT_DISCOVERY_OPTIONS, } from "./types.js";
+// On Windows, WorkspaceFs.realPath() may return backslash-separated paths
+// (e.g. C:\Users\workspace\file). Normalise both sides to forward slashes so
+// containment checks and relative-path derivation work cross-platform.
+function normaliseSep(p) {
+    return p.replace(/\\/g, "/");
+}
+function toPosixRelative(absoluteRoot, absolutePath) {
+    const normRoot = normaliseSep(absoluteRoot);
+    const normPath = normaliseSep(absolutePath);
+    if (normPath === normRoot) {
+        return "";
+    }
+    const prefix = normRoot.endsWith("/") ? normRoot : `${normRoot}/`;
+    if (normPath.startsWith(prefix)) {
+        return normPath.slice(prefix.length);
+    }
+    return normPath;
+}
+function isContained(absoluteRoot, absolutePath) {
+    const normRoot = normaliseSep(absoluteRoot);
+    const normPath = normaliseSep(absolutePath);
+    if (normPath === normRoot) {
+        return true;
+    }
+    const prefix = normRoot.endsWith("/") ? normRoot : `${normRoot}/`;
+    return normPath.startsWith(prefix);
+}
+function joinAbs(root, name) {
+    if (root.endsWith("/")) {
+        return `${root}${name}`;
+    }
+    return `${root}/${name}`;
+}
+function deriveScopeBounds(scope) {
+    if (scope.kind === "folder") {
+        if (!isSafeScopePath(scope.rootPath)) {
+            return { code: "INVALID_SCOPE", message: "scope.rootPath failed the safe-path gate" };
+        }
+        return {
+            rootPath: scope.rootPath,
+            recursive: scope.recursive,
+            includeGlobs: compileGlobList(scope.includeGlobs),
+            excludeGlobs: compileGlobList(scope.excludeGlobs),
+        };
+    }
+    if (scope.kind === "repository") {
+        if (!isSafeScopePath(scope.repositoryRoot)) {
+            return {
+                code: "INVALID_SCOPE",
+                message: "scope.repositoryRoot failed the safe-path gate",
+            };
+        }
+        return {
+            rootPath: scope.repositoryRoot,
+            recursive: true,
+            includeGlobs: compileGlobList(scope.includeGlobs),
+            excludeGlobs: compileGlobList(scope.excludeGlobs),
+        };
+    }
+    if (!isSafeScopePath(scope.rootPath)) {
+        return { code: "INVALID_SCOPE", message: "scope.rootPath failed the safe-path gate" };
+    }
+    for (const entry of scope.files) {
+        if (!isSafeScopePath(entry)) {
+            return {
+                code: "INVALID_SCOPE",
+                message: `scope.files entry failed the safe-path gate: ${entry}`,
+            };
+        }
+    }
+    // `files` scope has no glob support — every entry is explicit. We still respect the
+    // realpath containment gate inside walkSource so a malicious symlink is rejected.
+    return {
+        rootPath: scope.rootPath,
+        recursive: false,
+        includeGlobs: [],
+        excludeGlobs: [],
+    };
+}
+function abortYield() {
+    return {
+        kind: "error",
+        error: { code: "CANCELLED", message: "walk cancelled by caller" },
+    };
+}
+function safeStatFile(fs, absolutePath, realPath, relativePath) {
+    try {
+        const requestedStats = fs.stat(absolutePath);
+        if (requestedStats.hardLinkCount !== undefined && requestedStats.hardLinkCount > 1) {
+            return {
+                code: "READ_FAILED",
+                message: "selected file is not eligible for extraction",
+                relativePath,
+            };
+        }
+    }
+    catch {
+        // Some WorkspaceFs fakes only stat the canonical realPath shape (not the mixed-separator
+        // requested path). Fall through to stat the resolved path below.
+    }
+    try {
+        const realStats = fs.stat(realPath);
+        if (!realStats.isFile) {
+            return undefined;
+        }
+        if (realStats.hardLinkCount !== undefined && realStats.hardLinkCount > 1) {
+            return {
+                code: "READ_FAILED",
+                message: "selected file is not eligible for extraction",
+                relativePath,
+            };
+        }
+        return realStats;
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeRealPath(fs, absolutePath) {
+    try {
+        return fs.realPath(absolutePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+const HIDDEN_OR_GENERATED_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".next",
+    ".turbo",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "out",
+]);
+function isGlobMatched(bounds, relativePath) {
+    // Exclude wins over include. An empty includeGlobs means "include everything"; an empty
+    // excludeGlobs means "exclude nothing".
+    if (matchesAny(bounds.excludeGlobs, relativePath, false)) {
+        return false;
+    }
+    return matchesAny(bounds.includeGlobs, relativePath, true);
+}
+function shouldDescendIntoDirectory(entryName) {
+    return !entryName.startsWith(".") && !HIDDEN_OR_GENERATED_DIRS.has(entryName);
+}
+function shouldSkipDirectoryEntry(ctx, entryName) {
+    return !ctx.bounds.recursive || !shouldDescendIntoDirectory(entryName);
+}
+function isDeniedRelativePath(relativePath) {
+    return isDenied(relativePath);
+}
+function* yieldFileIfAllowed(ctx, absolutePath, relativePath) {
+    if (isDeniedRelativePath(relativePath)) {
+        return;
+    }
+    // realpath containment gate (boundary). Skip the entry entirely on failure rather than
+    // yielding a misleading diagnostic — the entry might be a transient broken symlink.
+    const real = safeRealPath(ctx.fs, absolutePath);
+    if (real === undefined) {
+        return;
+    }
+    if (!isContained(ctx.realRootPath, real)) {
+        yield {
+            kind: "error",
+            error: {
+                code: "PATH_ESCAPE",
+                message: `entry escapes the scope root via realpath: ${relativePath}`,
+                relativePath,
+            },
+        };
+        return;
+    }
+    const realRel = toPosixRelative(ctx.realRootPath, real);
+    if (isDeniedRelativePath(realRel)) {
+        return;
+    }
+    if (!isGlobMatched(ctx.bounds, relativePath)) {
+        return;
+    }
+    const stat = safeStatFile(ctx.fs, absolutePath, real, relativePath);
+    if (stat === undefined) {
+        return;
+    }
+    if ("code" in stat) {
+        yield { kind: "error", error: stat };
+        return;
+    }
+    ctx.filesYielded += 1;
+    yield { kind: "file", file: { relativePath, sizeBytes: stat.size } };
+}
+function safeReadDir(fs, absolutePath) {
+    try {
+        return fs.readDir(absolutePath);
+    }
+    catch {
+        return [];
+    }
+}
+// Read `signal?.aborted` through a function call so TypeScript control-flow analysis
+// does NOT narrow the optional chain after the first false branch — a long iteration may
+// observe abort between any two checks.
+function isAborted(ctx) {
+    return ctx.options.signal?.aborted === true;
+}
+function* yieldDirectoryEntry(ctx, absoluteDir, entry, depth) {
+    const childAbs = joinAbs(absoluteDir, entry.name);
+    const childRel = toPosixRelative(ctx.bounds.rootPath, childAbs);
+    if (entry.isDirectory) {
+        if (isDeniedRelativePath(childRel))
+            return;
+        if (shouldSkipDirectoryEntry(ctx, entry.name))
+            return;
+        yield* descend(ctx, childAbs, depth + 1);
+        return;
+    }
+    if (entry.isFile) {
+        yield* yieldFileIfAllowed(ctx, childAbs, childRel);
+    }
+}
+function* descend(ctx, absoluteDir, depth) {
+    if (isAborted(ctx)) {
+        yield abortYield();
+        return;
+    }
+    if (ctx.filesYielded >= ctx.options.maxFiles) {
+        return;
+    }
+    if (depth > ctx.options.maxDepth) {
+        return;
+    }
+    const entries = [...safeReadDir(ctx.fs, absoluteDir)].sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        if (ctx.filesYielded >= ctx.options.maxFiles) {
+            return;
+        }
+        if (isAborted(ctx)) {
+            yield abortYield();
+            return;
+        }
+        yield* yieldDirectoryEntry(ctx, absoluteDir, entry, depth);
+    }
+}
+function* walkFilesScope(ctx, files) {
+    for (const rel of files) {
+        if (isAborted(ctx)) {
+            yield abortYield();
+            return;
+        }
+        if (ctx.filesYielded >= ctx.options.maxFiles) {
+            return;
+        }
+        const abs = joinAbs(ctx.bounds.rootPath, rel);
+        yield* yieldFileIfAllowed(ctx, abs, rel);
+    }
+}
+export function* walkSource(fs, scope, options = DEFAULT_DISCOVERY_OPTIONS) {
+    const bounds = deriveScopeBounds(scope);
+    if ("code" in bounds) {
+        yield { kind: "error", error: bounds };
+        return;
+    }
+    const realRootPath = safeRealPath(fs, bounds.rootPath);
+    if (realRootPath === undefined) {
+        yield {
+            kind: "error",
+            error: { code: "READ_FAILED", message: "realPath failed for selected source root" },
+        };
+        return;
+    }
+    const ctx = { fs, bounds, realRootPath, options, filesYielded: 0 };
+    if (scope.kind === "files") {
+        yield* walkFilesScope(ctx, scope.files);
+        return;
+    }
+    yield* descend(ctx, bounds.rootPath, 0);
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class KnowledgeStoreError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export declare class KnowledgePathError extends KnowledgeStoreError {
+    readonly name: string;
+}
+export declare class KnowledgeNotFoundError extends KnowledgeStoreError {
+    readonly name: string;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAyB,IAAI,EAAE,MAAM,CAAyB;gBAC3C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAK3E;AAKD,qBAAa,kBAAmB,SAAQ,mBAAmB;IACzD,SAAyB,IAAI,EAAE,MAAM,CAAwB;CAC9D;AAID,qBAAa,sBAAuB,SAAQ,mBAAmB;IAC7D,SAAyB,IAAI,EAAE,MAAM,CAA4B;CAClE"}

package/dist/errors.js

@@ -0,0 +1,22 @@
+// Typed errors for the local-knowledge runtime. All store APIs raise these so callers can
+// distinguish path violations (caller bug) from missing rows (expected miss) from internal
+// SQLite failures (corrupted state) without string-sniffing the message.
+export class KnowledgeStoreError extends Error {
+    name = "KnowledgeStoreError";
+    constructor(message, options) {
+        // Forward `cause` only when present so we preserve the original stack from a wrapped
+        // SQLite/IO error without polluting the message of the higher-level error.
+        super(message, options);
+    }
+}
+// Raised by store-paths.ts for any input that would let the resolved on-disk path escape the
+// caller-provided runtime-state directory. Distinct from KnowledgeStoreError so a test for
+// "path containment fail-closed" cannot accidentally accept any other error class.
+export class KnowledgePathError extends KnowledgeStoreError {
+    name = "KnowledgePathError";
+}
+// Raised when a CRUD API targets a row that does not exist. Distinct so that retry/idempotency
+// logic can branch on missing-row without catching unrelated failures.
+export class KnowledgeNotFoundError extends KnowledgeStoreError {
+    name = "KnowledgeNotFoundError";
+}

package/dist/evaluations/dimensions.d.ts

@@ -0,0 +1,14 @@
+import type { ChunkId, KnowledgeCapsuleId, RetrievalReference } from "@oscharko-dev/keiko-contracts";
+import type { ParsedUnit } from "@oscharko-dev/keiko-contracts";
+export declare function scoreRecall(returned: readonly RetrievalReference[], expected: readonly ChunkId[]): number;
+export declare function scorePrecision(returned: readonly RetrievalReference[], expected: readonly ChunkId[]): number;
+export declare function scoreMeanReciprocalRank(returned: readonly RetrievalReference[], expected: readonly ChunkId[]): number;
+export declare function scoreNdcg(returned: readonly RetrievalReference[], expected: readonly ChunkId[]): number;
+export declare function scoreSourceIsolation(returned: readonly RetrievalReference[], scopeCapsuleIds: readonly KnowledgeCapsuleId[]): number;
+type CitationRequirementKey = "page" | "section" | "json-path" | "csv-row" | "html-block" | "unsupported-media";
+export declare function scoreCitationQuality(references: readonly RetrievalReference[], chunkUnitKinds: ReadonlyMap<string, CitationRequirementKey>): number;
+export declare function citationRequirementForUnit(unit: ParsedUnit): CitationRequirementKey;
+export type { CitationRequirementKey };
+export declare function scoreNoEvidenceAccuracy(actualNoEvidence: boolean, expectedNoEvidence: boolean, actualReason?: string, expectedReason?: string): 0 | 1;
+export declare function scoreContextBudgetFit(references: readonly RetrievalReference[], chunkTokenCounts: ReadonlyMap<string, number>, budgetTokens: number | undefined): number;
+//# sourceMappingURL=dimensions.d.ts.map

package/dist/evaluations/dimensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dimensions.d.ts","sourceRoot":"","sources":["../../src/evaluations/dimensions.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAMhE,wBAAgB,WAAW,CACzB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,MAAM,CASR;AAKD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,MAAM,CASR;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,MAAM,CAUR;AAQD,wBAAgB,SAAS,CACvB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,MAAM,CAiBR;AASD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,eAAe,EAAE,SAAS,kBAAkB,EAAE,GAC7C,MAAM,CAQR;AAcD,KAAK,sBAAsB,GACvB,MAAM,GACN,SAAS,GACT,WAAW,GACX,SAAS,GACT,YAAY,GACZ,mBAAmB,CAAC;AAyCxB,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,GAC1D,MAAM,CAeR;AAID,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,UAAU,GAAG,sBAAsB,CAEnF;AAED,YAAY,EAAE,sBAAsB,EAAE,CAAC;AAOvC,wBAAgB,uBAAuB,CACrC,gBAAgB,EAAE,OAAO,EACzB,kBAAkB,EAAE,OAAO,EAC3B,YAAY,CAAC,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,GACtB,CAAC,GAAG,CAAC,CAMP;AAQD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,CAWR"}