@oscharko-dev/keiko 0.2.0-beta.3 → 0.2.0-beta.4

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/extract.js

@@ -14,9 +14,12 @@
 //   6. Inside a single transaction: REPLACEs the documents row, deletes prior dependent
 //      rows, then inserts the new pages/sections/parsed_units/diagnostics.
 import { createHash } from "node:crypto";
+import { isSafeScopePath } from "@oscharko-dev/keiko-contracts";
+import { isDenied } from "@oscharko-dev/keiko-workspace";
 import { buildParserOptions, unsupportedParser } from "../parsers/index.js";
 import { redactDiagnosticMessage } from "../privacy/diagnostic-redactor.js";
 import { basenameOf, extensionOf, mediaTypeFor } from "./media-type.js";
+import { compileGlobList, matchesAny } from "./glob.js";
 import { deleteDependentRows, insertDiagnosticRow, insertDocumentRow, insertDocumentTextRow, insertPageRow, insertParsedUnitRow, insertSectionRow, readExistingDocumentRow, } from "./persist.js";
 import { documentIdFor, } from "./types.js";
 // ─── Path helpers (re-derived to keep extract.ts self-contained for the realpath gate) ──
@@ -39,6 +42,14 @@ function joinAbs(root, rel) {
         return `${root}${rel}`;
     return `${root}/${rel}`;
 }
+function toPosixRelative(absoluteRoot, absolutePath) {
+    const normRoot = normaliseSep(absoluteRoot);
+    const normPath = normaliseSep(absolutePath);
+    if (normPath === normRoot)
+        return "";
+    const prefix = normRoot.endsWith("/") ? normRoot : `${normRoot}/`;
+    return normPath.startsWith(prefix) ? normPath.slice(prefix.length) : normPath;
+}
 function scopeRoot(source) {
     const { scope } = source;
     if (scope.kind === "folder")
@@ -54,6 +65,24 @@ function safeDisplay(relativePath) {
     const base = basenameOf(relativePath);
     return base.length === 0 ? relativePath : base;
 }
+function safeRelativePath(relativePath) {
+    const normalised = normaliseSep(relativePath);
+    if (normalised.startsWith("/")) {
+        return {
+            code: "INVALID_SCOPE",
+            message: "file path failed the selected-scope policy",
+            relativePath,
+        };
+    }
+    if (!isSafeScopePath(normalised)) {
+        return {
+            code: "INVALID_SCOPE",
+            message: "file path failed the selected-scope policy",
+            relativePath,
+        };
+    }
+    return normalised;
+}
 function redactionPrefixFor(source) {
     return scopeRoot(source);
 }
@@ -76,7 +105,40 @@ function redactParserResult(parserResult, source) {
     };
 }
 // ─── Failure / unsupported helpers ───────────────────────────────────────────
-function buildFailureResult(params, documentId, error) {
+function persistFailureRow(deps, params, documentId, document, diagnostic, now) {
+    const db = deps.store._internal.db;
+    db.exec("BEGIN");
+    try {
+        insertDocumentRow(db, {
+            id: documentId,
+            capsuleId: params.capsuleId,
+            sourceId: String(params.source.id),
+            documentPath: document.documentPath,
+            sizeBytes: document.sizeBytes,
+            mediaType: document.mediaType,
+            contentHash: document.contentHash,
+            parserId: document.parser.parserId,
+            parserVersion: document.parser.parserVersion,
+            lastExtractedAt: document.lastExtractedAt,
+            status: document.status,
+            safeDisplayName: document.safeDisplayName,
+        });
+        deleteDependentRows(db, params.capsuleId, documentId);
+        insertDiagnosticRow(db, {
+            id: `${String(documentId)}#d0`,
+            capsuleId: params.capsuleId,
+            diagnostic,
+            createdAt: now(),
+        });
+        db.exec("COMMIT");
+    }
+    catch (cause) {
+        db.exec("ROLLBACK");
+        throw cause;
+    }
+}
+function buildFailureResult(deps, params, documentId, error, options = { persist: true }) {
+    const now = deps.store._internal.now;
     const redactedMessage = redactMessage(error.message, params.source);
     const diagnostic = {
         severity: "error",
@@ -93,14 +155,17 @@ function buildFailureResult(params, documentId, error) {
         mediaType: mediaTypeFor(extensionOf(params.file.relativePath)),
         contentHash: "",
         parser: { parserId: "none", parserVersion: "0" },
-        lastExtractedAt: 0,
+        lastExtractedAt: now(),
         status: "failed",
         safeDisplayName: safeDisplay(params.file.relativePath),
     };
+    if (options.persist) {
+        persistFailureRow(deps, params, documentId, document, diagnostic, now);
+    }
     const outcome = {
         kind: "failed",
         document,
-        error: { ...error, message: redactedMessage },
+        error: { ...error, message: redactedMessage, relativePath: params.file.relativePath },
     };
     return {
         capsuleId: params.capsuleId,
@@ -174,43 +239,207 @@ function persistDocumentAndDependents(deps, params, documentId, document, parser
         throw cause;
     }
 }
+const HIDDEN_OR_GENERATED_DIRS = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".next",
+    ".turbo",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "out",
+]);
+function deriveScopePolicy(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" };
+    }
+    const explicitFiles = new Set();
+    for (const entry of scope.files) {
+        const safeEntry = safeRelativePath(entry);
+        if (typeof safeEntry !== "string") {
+            return {
+                code: "INVALID_SCOPE",
+                message: `scope.files entry failed the safe-path gate: ${entry}`,
+            };
+        }
+        explicitFiles.add(safeEntry);
+    }
+    return {
+        rootPath: scope.rootPath,
+        recursive: false,
+        includeGlobs: [],
+        excludeGlobs: [],
+        explicitFiles,
+    };
+}
+function matchesSourceGlobs(policy, relativePath) {
+    if (matchesAny(policy.excludeGlobs, relativePath, false))
+        return false;
+    return matchesAny(policy.includeGlobs, relativePath, true);
+}
+function hasHiddenOrGeneratedParent(relativePath) {
+    const segments = relativePath.split("/").filter((segment) => segment.length > 0);
+    for (const segment of segments.slice(0, -1)) {
+        if (segment.startsWith(".") || HIDDEN_OR_GENERATED_DIRS.has(segment))
+            return true;
+    }
+    return false;
+}
+function isSelectedByScope(policy, relativePath) {
+    if (isDenied(relativePath))
+        return false;
+    if (policy.explicitFiles !== undefined)
+        return policy.explicitFiles.has(relativePath);
+    if (!policy.recursive && relativePath.includes("/"))
+        return false;
+    if (hasHiddenOrGeneratedParent(relativePath))
+        return false;
+    return matchesSourceGlobs(policy, relativePath);
+}
+function targetError(error, persistFailure) {
+    return { error, persistFailure };
+}
+function selectedRelativePath(policy, rawRelativePath) {
+    const relativePath = safeRelativePath(rawRelativePath);
+    if (typeof relativePath !== "string") {
+        return targetError(relativePath, false);
+    }
+    if (!isSelectedByScope(policy, relativePath)) {
+        return targetError({
+            code: "INVALID_SCOPE",
+            message: "file is outside the selected source scope",
+            relativePath,
+        }, false);
+    }
+    return relativePath;
+}
 function resolveTargetPath(deps, params) {
-    const root = scopeRoot(params.source);
-    const absolute = joinAbs(root, params.file.relativePath);
+    const policy = deriveScopePolicy(params.source.scope);
+    if ("code" in policy) {
+        return targetError(policy, false);
+    }
+    const relativePath = selectedRelativePath(policy, params.file.relativePath);
+    if (typeof relativePath !== "string") {
+        return relativePath;
+    }
+    const root = policy.rootPath;
+    const absolute = joinAbs(root, relativePath);
     let real;
     try {
         real = deps.fs.realPath(absolute);
     }
-    catch (cause) {
+    catch {
+        return targetError({
+            code: "READ_FAILED",
+            message: "realPath failed for selected file",
+            relativePath,
+        }, true);
+    }
+    if (!isContained(root, real)) {
+        return targetError({
+            code: "PATH_ESCAPE",
+            message: `realpath escapes scope root: ${relativePath}`,
+            relativePath,
+        }, true);
+    }
+    const realRelativePath = toPosixRelative(root, real);
+    if (isDenied(realRelativePath)) {
+        return targetError({
+            code: "READ_FAILED",
+            message: "resolved file is denied by workspace policy",
+            relativePath,
+        }, true);
+    }
+    // Normalise to forward slashes so subsequent IO calls (readFileBytes, stat) receive
+    // a consistent path even when realPath returned a Windows backslash path.
+    return { absolutePath: normaliseSep(real), requestedAbsolutePath: absolute, relativePath };
+}
+function validateRequestedTarget(deps, params, target) {
+    try {
+        deps.fs.stat(target.requestedAbsolutePath);
+        return undefined;
+    }
+    catch {
+        return {
+            code: "STAT_FAILED",
+            message: "stat failed for selected file",
+            relativePath: params.file.relativePath,
+        };
+    }
+}
+function validateResolvedTarget(deps, params, target) {
+    try {
+        const realStat = deps.fs.stat(target.absolutePath);
+        if (!realStat.isFile) {
+            return {
+                code: "READ_FAILED",
+                message: "selected path is not a file",
+                relativePath: params.file.relativePath,
+            };
+        }
+        if (realStat.hardLinkCount === undefined || realStat.hardLinkCount <= 1)
+            return undefined;
         return {
             code: "READ_FAILED",
-            message: `realPath failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+            message: "selected file is not eligible for extraction",
             relativePath: params.file.relativePath,
         };
     }
-    if (!isContained(root, real)) {
+    catch {
         return {
-            code: "PATH_ESCAPE",
-            message: `realpath escapes scope root: ${params.file.relativePath}`,
+            code: "STAT_FAILED",
+            message: "stat failed for selected file",
             relativePath: params.file.relativePath,
         };
     }
-    // Normalise to forward slashes so subsequent IO calls (readFileBytes, stat) receive
-    // a consistent path even when realPath returned a Windows backslash path.
-    return { absolutePath: normaliseSep(real) };
 }
-async function readBytes(deps, absolutePath, maxBytes) {
+async function readBytes(deps, params, target, maxBytes) {
     const reader = deps.fs.readFileBytes;
     if (reader === undefined) {
-        return { code: "READ_FAILED", message: "WorkspaceFs.readFileBytes is unavailable" };
+        return {
+            code: "READ_FAILED",
+            message: "WorkspaceFs.readFileBytes is unavailable",
+            relativePath: params.file.relativePath,
+        };
     }
+    const requestedError = validateRequestedTarget(deps, params, target);
+    if (requestedError !== undefined)
+        return requestedError;
+    const resolvedError = validateResolvedTarget(deps, params, target);
+    if (resolvedError !== undefined)
+        return resolvedError;
     try {
-        return await reader(absolutePath, maxBytes);
+        return await reader(target.absolutePath, maxBytes);
     }
-    catch (cause) {
+    catch {
         return {
             code: "READ_FAILED",
-            message: `readFileBytes failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+            message: "readFileBytes failed for selected file",
+            relativePath: params.file.relativePath,
         };
     }
 }
@@ -261,8 +490,44 @@ function isUnsupportedResult(result) {
     return (result.parser.parserId === "unsupported" ||
         (result.units.length > 0 && result.units.every((unit) => unit.kind === "unsupported-media")));
 }
+const FAILED_PARSER_DIAGNOSTIC_CODES = new Set([
+    "OVERSIZED_FILE",
+    "PARSER_TIMEOUT",
+    "PARSER_CANCELLED",
+    "MALFORMED_INPUT",
+    "OBJECT_LIMIT_REACHED",
+]);
+function firstParserFailureDiagnostic(result) {
+    return result.diagnostics.find((diagnostic) => diagnostic.severity === "error" || FAILED_PARSER_DIAGNOSTIC_CODES.has(diagnostic.code));
+}
 function statusForResult(result) {
-    return isUnsupportedResult(result) ? "unsupported" : "extracted";
+    if (isUnsupportedResult(result))
+        return "unsupported";
+    if (firstParserFailureDiagnostic(result) !== undefined)
+        return "failed";
+    return "extracted";
+}
+function discoveryErrorCodeForParserDiagnostic(diagnostic) {
+    if (diagnostic.code === "OVERSIZED_FILE")
+        return "OVERSIZED_FILE";
+    if (diagnostic.code === "PARSER_CANCELLED")
+        return "CANCELLED";
+    if (diagnostic.code === "MALFORMED_INPUT")
+        return "MALFORMED_INPUT";
+    if (diagnostic.code === "PARSER_TIMEOUT")
+        return "PARSER_TIMEOUT";
+    return "PARSER_FAILED";
+}
+function parserFailureOutcome(document, diagnostic, relativePath) {
+    return {
+        kind: "failed",
+        document,
+        error: {
+            code: discoveryErrorCodeForParserDiagnostic(diagnostic),
+            message: diagnostic.message,
+            relativePath,
+        },
+    };
 }
 const SOURCE_TEXT_PARSER_IDS = new Set(["text", "json", "csv", "html"]);
 function decodeUtf8ForStorage(bytes) {
@@ -304,29 +569,60 @@ async function runParserForPersistence(deps, documentId, params, bytes, options)
 function persistExtractedDocument(deps, params, documentId, document, parserResult) {
     persistDocumentAndDependents(deps, params, documentId, document, parserResult, deps.store._internal.now);
 }
-export async function extractDocument(deps, params) {
-    const documentId = documentIdFor({
+async function readBoundedDocumentBytes(deps, params, documentId, target, options) {
+    const bytes = await readBytes(deps, params, target, options.maxBytes + 1);
+    if (!(bytes instanceof Uint8Array)) {
+        return buildFailureResult(deps, params, documentId, bytes);
+    }
+    if (bytes.byteLength > options.maxBytes) {
+        return buildOversizedFailure(deps, params, documentId, options, bytes.byteLength);
+    }
+    return bytes;
+}
+function parserExtractionResult(params, document, parserResult, status) {
+    const failureDiagnostic = firstParserFailureDiagnostic(parserResult);
+    return {
+        capsuleId: params.capsuleId,
+        sourceId: params.source.id,
+        relativePath: params.file.relativePath,
+        outcome: status === "failed" && failureDiagnostic !== undefined
+            ? parserFailureOutcome(document, failureDiagnostic, params.file.relativePath)
+            : { kind: "persisted", document },
+        diagnostics: parserResult.diagnostics,
+    };
+}
+function paramsWithRelativePath(params, relativePath) {
+    if (params.file.relativePath === relativePath)
+        return params;
+    return { ...params, file: { ...params.file, relativePath } };
+}
+function extractionDocumentId(params) {
+    return documentIdFor({
         capsuleId: params.capsuleId,
         sourceId: params.source.id,
         relativePath: params.file.relativePath,
     });
-    const resolved = resolveTargetPath(deps, params);
-    if ("code" in resolved) {
-        return buildFailureResult(params, documentId, resolved);
-    }
-    const options = params.parserOptions ?? buildParserOptions();
-    if (params.file.sizeBytes > options.maxBytes) {
-        return buildOversizedFailure(deps, params, documentId, options);
+}
+function targetResolutionFailure(deps, params, resolved) {
+    const failureParams = resolved.error.relativePath === undefined
+        ? params
+        : paramsWithRelativePath(params, resolved.error.relativePath);
+    return buildFailureResult(deps, failureParams, extractionDocumentId(failureParams), resolved.error, {
+        persist: resolved.persistFailure,
+    });
+}
+async function parseAndPersistDocument(deps, params, documentId, bytes, contentHash, options) {
+    let parserResult;
+    try {
+        parserResult = await runParserForPersistence(deps, documentId, params, bytes, options);
     }
-    const bytes = await readBytes(deps, resolved.absolutePath, options.maxBytes);
-    if (!(bytes instanceof Uint8Array)) {
-        return buildFailureResult(params, documentId, bytes);
+    catch {
+        return buildFailureResult(deps, params, documentId, {
+            code: "PARSER_FAILED",
+            message: "parser adapter failed while extracting document",
+            relativePath: params.file.relativePath,
+        });
     }
-    const contentHash = hashBytes(bytes);
-    const fast = readUnchangedFastPath(deps, params, documentId, contentHash);
-    if (fast !== undefined)
-        return fast;
-    const parserResult = await runParserForPersistence(deps, documentId, params, bytes, options);
     const redactedParserResult = redactParserResult(parserResult, params.source);
     const status = statusForResult(redactedParserResult);
     const document = buildDocumentRecord({
@@ -338,21 +634,47 @@ export async function extractDocument(deps, params) {
         status,
     });
     persistExtractedDocument(deps, params, documentId, document, redactedParserResult);
-    return {
+    return parserExtractionResult(params, document, redactedParserResult, status);
+}
+export async function extractDocument(deps, params) {
+    const resolved = resolveTargetPath(deps, params);
+    if ("error" in resolved) {
+        return targetResolutionFailure(deps, params, resolved);
+    }
+    const canonicalParams = paramsWithRelativePath(params, resolved.relativePath);
+    const documentId = extractionDocumentId(canonicalParams);
+    const options = canonicalParams.parserOptions ?? buildParserOptions();
+    if (canonicalParams.file.sizeBytes > options.maxBytes) {
+        return buildOversizedFailure(deps, canonicalParams, documentId, options);
+    }
+    const bytes = await readBoundedDocumentBytes(deps, canonicalParams, documentId, resolved, options);
+    if (!(bytes instanceof Uint8Array)) {
+        return bytes;
+    }
+    const contentHash = hashBytes(bytes);
+    const fast = readUnchangedFastPath(deps, canonicalParams, documentId, contentHash);
+    if (fast !== undefined)
+        return fast;
+    return parseAndPersistDocument(deps, canonicalParams, documentId, bytes, contentHash, options);
+}
+export function recordExtractionFailure(deps, params) {
+    const documentId = documentIdFor({
         capsuleId: params.capsuleId,
         sourceId: params.source.id,
         relativePath: params.file.relativePath,
-        outcome: { kind: "persisted", document },
-        diagnostics: redactedParserResult.diagnostics,
-    };
+    });
+    return buildFailureResult(deps, params, documentId, params.error);
 }
-function oversizedDocumentRecord(params, documentId, lastExtractedAt) {
+function oversizedDocumentRecord(params, documentId, lastExtractedAt, observedSizeBytes) {
+    const sizeBytes = observedSizeBytes === undefined
+        ? params.file.sizeBytes
+        : Math.max(params.file.sizeBytes, observedSizeBytes);
     return {
         id: documentId,
         capsuleId: params.capsuleId,
         sourceId: params.source.id,
         documentPath: params.file.relativePath,
-        sizeBytes: params.file.sizeBytes,
+        sizeBytes,
         mediaType: mediaTypeFor(extensionOf(params.file.relativePath)),
         contentHash: "",
         parser: { parserId: "none", parserVersion: "0" },
@@ -393,16 +715,19 @@ function persistOversizedRow(deps, params, documentId, document, diagnostic, now
         throw cause;
     }
 }
-function buildOversizedFailure(deps, params, documentId, options) {
+function buildOversizedFailure(deps, params, documentId, options, observedSizeBytes) {
     const now = deps.store._internal.now;
-    const message = redactMessage(`file size ${String(params.file.sizeBytes)} exceeds maxBytes=${String(options.maxBytes)}`, params.source);
+    const sizeBytes = observedSizeBytes === undefined
+        ? params.file.sizeBytes
+        : Math.max(params.file.sizeBytes, observedSizeBytes);
+    const message = redactMessage(`file size ${String(sizeBytes)} exceeds maxBytes=${String(options.maxBytes)}`, params.source);
     const diagnostic = {
         severity: "error",
         code: "OVERSIZED_FILE",
         message,
         documentId,
     };
-    const document = oversizedDocumentRecord(params, documentId, now());
+    const document = oversizedDocumentRecord(params, documentId, now(), observedSizeBytes);
     persistOversizedRow(deps, params, documentId, document, diagnostic, now);
     return {
         capsuleId: params.capsuleId,

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/test-support.d.ts

@@ -4,6 +4,8 @@ export interface MemoryFsFile {
     readonly relativePath: string;
     readonly content: string | Uint8Array;
     readonly realPathOverride?: string;
+    readonly hardLinkCount?: number;
+    readonly isSymbolicLink?: boolean;
 }
 export declare function memoryFs(root: string, files: readonly MemoryFsFile[]): WorkspaceFs;
 export declare function folderScope(rootPath: string, options?: {

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/test-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../src/discovery/test-support.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAqB,WAAW,EAAiB,MAAM,+BAA+B,CAAC;AAiDnG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAyCD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CAgClF;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,GACL,oBAAoB,CAWtB"}
+{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../src/discovery/test-support.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAqB,WAAW,EAAiB,MAAM,+BAA+B,CAAC;AAmDnG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CACnC;AA4CD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CAgClF;AAED,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,GACL,oBAAoB,CAWtB"}

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/test-support.js

@@ -41,9 +41,12 @@ function buildMap(files) {
     const map = new Map();
     for (const f of files) {
         const bytes = typeof f.content === "string" ? encoder.encode(f.content) : f.content;
-        const entry = f.realPathOverride !== undefined
-            ? { content: bytes, realPathOverride: f.realPathOverride }
-            : { content: bytes };
+        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;
@@ -62,7 +65,8 @@ function memoryStat(root, map, findKey) {
             size: map.get(key)?.content.byteLength ?? 0,
             isFile: true,
             isDirectory: false,
-            isSymbolicLink: false,
+            isSymbolicLink: map.get(key)?.isSymbolicLink ?? false,
+            hardLinkCount: map.get(key)?.hardLinkCount,
         };
     };
 }

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/types.d.ts

@@ -9,7 +9,7 @@ export interface DiscoveryOptions {
     readonly signal?: AbortSignal;
 }
 export declare const DEFAULT_DISCOVERY_OPTIONS: DiscoveryOptions;
-export type DiscoveryErrorCode = "PATH_ESCAPE" | "READ_FAILED" | "OVERSIZED_FILE" | "UNSUPPORTED_FORMAT" | "CANCELLED" | "STAT_FAILED" | "INVALID_SCOPE";
+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;

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,cAAc;IAE7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,gBAAgB;IAG/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAG1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAG9B,CAAC;AAMX,MAAM,MAAM,kBAAkB,GAC1B,aAAa,GACb,aAAa,GACb,gBAAgB,GAChB,oBAAoB,GACpB,WAAW,GACX,aAAa,GACb,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAGD,MAAM,MAAM,iBAAiB,GAIzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAA;CAAE,GAEjE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAE7F;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAEnG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACnD;AAGD,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,CAAC;AAIN,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AASD,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAGjE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/discovery/types.ts"],"names":[],"mappings":"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"}

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/types.js

@@ -14,10 +14,15 @@ export const DEFAULT_DISCOVERY_OPTIONS = {
 // 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.
 //
-// The `#` character is encoded as `%23` before embedding so that a file literally named
-// `a#u0.md` cannot produce an id that collides with a parsed_unit suffix (`#u0`) or a
-// diagnostic suffix (`#d0`) derived from a different document.
+// 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 encodedPath = input.relativePath.replace(/#/g, "%23");
-    return `doc:${String(input.capsuleId)}:${String(input.sourceId)}:${encodedPath}`;
+    const encodedCapsuleId = encodeDocumentIdComponent(String(input.capsuleId));
+    const encodedSourceId = encodeDocumentIdComponent(String(input.sourceId));
+    const encodedPath = encodeDocumentIdComponent(input.relativePath);
+    return `doc:${encodedCapsuleId}:${encodedSourceId}:${encodedPath}`;
 }

package/node_modules/@oscharko-dev/keiko-local-knowledge/dist/discovery/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../src/discovery/walk.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAGjE,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;AA6P/D,wBAAiB,UAAU,CACzB,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE,gBAA4C,GACpD,SAAS,CAAC,SAAS,CAAC,CAYtB"}
+{"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;AAoT/D,wBAAiB,UAAU,CACzB,EAAE,EAAE,WAAW,EACf,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE,gBAA4C,GACpD,SAAS,CAAC,SAAS,CAAC,CAYtB"}