@oscharko-dev/keiko-contracts 0.2.0

package/dist/local-knowledge-large-document.js

@@ -0,0 +1,142 @@
+// Bounded large-document ingestion contracts for the Local Knowledge Connector
+// (Epic #1160, Issue #1286). This module is PURE — no node:sqlite, no fs, no clock, no
+// randomness, no crypto — so it stays in the leaf `keiko-contracts` package.
+//
+// The large-document path coexists with the existing full-buffer parser path. Small files
+// keep their current behavior; large supported files are preflight-classified, bounded by an
+// explicit multi-dimensional resource policy, extracted progressively (page-windowed),
+// checkpointed durably so they can resume, and degraded to partial coverage with quality
+// warnings rather than failing the indexing pipeline when an optional capability is missing.
+//
+// Every record carries explicit capsuleId + documentId lineage so a single global pool is
+// unrepresentable (Foundry IQ invariant). The wire surface stays content-free: checkpoints
+// carry hashes, cursors, and counts — never raw extracted text.
+const MIB = 1024 * 1024;
+const GIB = 1024 * MIB;
+export const DEFAULT_LARGE_DOCUMENT_RESOURCE_POLICY = Object.freeze({
+    maxRawFileBytes: GIB,
+    maxExtractedTextBytes: 256 * MIB,
+    maxParserUnits: 200_000,
+    maxParserObjects: 25_000_000,
+    maxChunkCount: 2_000_000,
+    maxEmbeddingBatchCount: 100_000,
+    maxWallClockMs: 60 * 60 * 1000,
+    cancellationDeadlineMs: 15_000,
+    maxRetryCount: 3,
+    maxPersistedStorageGrowthBytes: 512 * MIB,
+    largeFileThresholdBytes: 64 * MIB,
+    extractionWindowPages: 16,
+});
+// Stable, order-fixed fingerprint persisted with each checkpoint. Any policy change yields a
+// different fingerprint, which makes a resumed job refuse a checkpoint produced under
+// different limits.
+export function largeDocumentPolicyFingerprint(policy) {
+    return [
+        "ldp1",
+        policy.maxRawFileBytes,
+        policy.maxExtractedTextBytes,
+        policy.maxParserUnits,
+        policy.maxParserObjects,
+        policy.maxChunkCount,
+        policy.maxEmbeddingBatchCount,
+        policy.maxWallClockMs,
+        policy.cancellationDeadlineMs,
+        policy.maxRetryCount,
+        policy.maxPersistedStorageGrowthBytes,
+        policy.largeFileThresholdBytes,
+        policy.extractionWindowPages,
+    ].join(":");
+}
+export const LARGE_DOCUMENT_EXTRACTION_STRATEGIES = [
+    "standard-buffer",
+    "progressive-pdf",
+    "unsupported",
+    "oversized",
+];
+export const EXTRACTION_PHASES = [
+    "preflight",
+    "extracting",
+    "extracted",
+    "chunking",
+    "chunked",
+    "embedding",
+    "embedded",
+    "complete",
+    "cancelled",
+    "failed",
+];
+// A phase is terminal when no further work will run for the document under the current job.
+export const TERMINAL_EXTRACTION_PHASES = [
+    "complete",
+    "cancelled",
+    "failed",
+];
+export function isTerminalExtractionPhase(phase) {
+    return TERMINAL_EXTRACTION_PHASES.includes(phase);
+}
+export const COVERAGE_QUALITIES = [
+    "complete",
+    "text-only",
+    "partial",
+    "none",
+];
+export const EXTRACTION_CAPABILITY_STATUSES = [
+    "available",
+    "unavailable",
+    "degraded",
+    "failing",
+];
+export const DEFAULT_EXTRACTION_CAPABILITY_AVAILABILITY = Object.freeze({ ocr: "unavailable", multimodal: "unavailable" });
+// A capability contributes useful coverage only when it is fully available. Degraded/failing
+// capabilities are isolated as quality warnings.
+export function capabilityContributesCoverage(status) {
+    return status === "available";
+}
+// ─── Content-free diagnostic codes for the large-document path ─────────────────
+export const LARGE_DOCUMENT_DIAGNOSTIC_CODES = Object.freeze({
+    PARTIAL_COVERAGE: "PARTIAL_COVERAGE",
+    OCR_CAPABILITY_UNAVAILABLE: "OCR_CAPABILITY_UNAVAILABLE",
+    MULTIMODAL_CAPABILITY_UNAVAILABLE: "MULTIMODAL_CAPABILITY_UNAVAILABLE",
+    CONVERTER_UNAVAILABLE: "CONVERTER_UNAVAILABLE",
+    RESOURCE_POLICY_EXCEEDED: "RESOURCE_POLICY_EXCEEDED",
+    CHECKPOINT_INCOMPATIBLE: "CHECKPOINT_INCOMPATIBLE",
+    EXTRACTION_RESUMED: "EXTRACTION_RESUMED",
+    EXTRACTION_PROGRESS: "EXTRACTION_PROGRESS",
+});
+export const CHECKPOINT_INCOMPATIBILITY_REASONS = [
+    "source-hash",
+    "parser-version",
+    "resource-policy",
+    "chunking-strategy",
+    "embedding-identity",
+];
+function sameEmbeddingIdentity(a, b) {
+    return (a.provider === b.provider &&
+        a.modelId === b.modelId &&
+        a.vectorDimensions === b.vectorDimensions &&
+        a.vectorMetric === b.vectorMetric &&
+        (a.modelRevision ?? "") === (b.modelRevision ?? ""));
+}
+// Pure comparison. A resumed job continues only when this returns `{ compatible: true }`;
+// otherwise the job restarts from scratch and emits a CHECKPOINT_INCOMPATIBLE diagnostic.
+export function checkpointCompatibility(stored, current) {
+    const reasons = [];
+    if (stored.sourceContentHash !== current.sourceContentHash)
+        reasons.push("source-hash");
+    if (stored.parserVersion !== current.parserVersion)
+        reasons.push("parser-version");
+    if (stored.policyFingerprint !== current.policyFingerprint)
+        reasons.push("resource-policy");
+    if (stored.chunkingStrategyVersion !== current.chunkingStrategyVersion) {
+        reasons.push("chunking-strategy");
+    }
+    if (!sameEmbeddingIdentity(stored.embeddingIdentity, current.embeddingIdentity)) {
+        reasons.push("embedding-identity");
+    }
+    return reasons.length === 0 ? { compatible: true } : { compatible: false, reasons };
+}
+export const LARGE_DOCUMENT_RESUME_CHOICES = [
+    "resume",
+    "restart",
+    "abandon",
+];

package/dist/local-knowledge-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function isSafeScopePath(path: string): boolean;
+export declare function isSafeStorageReference(path: string): boolean;
+//# sourceMappingURL=local-knowledge-paths.d.ts.map

package/dist/local-knowledge-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-knowledge-paths.d.ts","sourceRoot":"","sources":["../src/local-knowledge-paths.ts"],"names":[],"mappings":"AAoCA,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAiBrD;AAKD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAW5D"}

package/dist/local-knowledge-paths.js

@@ -0,0 +1,65 @@
+// Pure path-safety helpers for the Local Knowledge Connector validators (Epic #189,
+// Issue #191). Extracted from `local-knowledge-validation.ts` to keep each file under the
+// 400-LOC budget and to give downstream packages a single import target when they need to
+// re-use the safe-path predicates at their own trust boundaries.
+//
+// Producers may pass either a workspace-relative path or an absolute path; the validator
+// only rejects the most dangerous shapes: traversal segments, tilde expansion (which the
+// shell would resolve to $HOME), NUL bytes, Windows-style drive letters and UNC prefixes,
+// and the literal filesystem root markers. These helpers NEVER touch the filesystem.
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:/;
+const ROOT_MARKERS = new Set(["/", "\\", "~", "."]);
+function hasTraversalSegment(path) {
+    const normalized = path.replace(/\\/g, "/");
+    for (const segment of normalized.split("/")) {
+        if (segment === "..") {
+            return true;
+        }
+    }
+    return false;
+}
+function isObviouslyUnsafeAbsoluteScope(path) {
+    if (path === "/" || path === "\\") {
+        return true;
+    }
+    if (path.startsWith("~")) {
+        return true;
+    }
+    if (path.startsWith("\\\\")) {
+        return true;
+    }
+    return WINDOWS_DRIVE_RE.test(path) && path.length <= 3;
+}
+export function isSafeScopePath(path) {
+    if (path.length === 0) {
+        return false;
+    }
+    if (path.includes("\0")) {
+        return false;
+    }
+    if (ROOT_MARKERS.has(path)) {
+        return false;
+    }
+    if (path.startsWith("~")) {
+        return false;
+    }
+    if (isObviouslyUnsafeAbsoluteScope(path)) {
+        return false;
+    }
+    return !hasTraversalSegment(path);
+}
+// Storage references live under Keiko's runtime-state directory and MUST stay relative.
+// We refuse anything starting with `/`, `\`, a Windows drive prefix, a tilde, or anything
+// containing `..` or NUL.
+export function isSafeStorageReference(path) {
+    if (path.length === 0 || path.includes("\0")) {
+        return false;
+    }
+    if (path.startsWith("/") || path.startsWith("\\") || path.startsWith("~")) {
+        return false;
+    }
+    if (WINDOWS_DRIVE_RE.test(path)) {
+        return false;
+    }
+    return !hasTraversalSegment(path);
+}

package/dist/local-knowledge-records.d.ts

@@ -0,0 +1,190 @@
+import type { CapsuleLifecycleState, ChunkId, DocumentId, EmbeddingModelIdentity, KnowledgeCapsuleId, KnowledgeSourceId, ParserIdentity, VectorId } from "./local-knowledge.js";
+export type DocumentStatus = "pending" | "extracted" | "skipped" | "failed" | "unsupported";
+export declare const DOCUMENT_STATUSES: readonly DocumentStatus[];
+export interface DocumentRecord {
+    readonly id: DocumentId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentPath: string;
+    readonly sizeBytes: number;
+    readonly mediaType: string;
+    readonly contentHash: string;
+    readonly parser: ParserIdentity;
+    readonly lastExtractedAt: number;
+    readonly status: DocumentStatus;
+    readonly safeDisplayName: string;
+}
+export interface PageBoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface PageRecord {
+    readonly documentId: DocumentId;
+    readonly pageNumber: number;
+    readonly pageLabel?: string;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+    readonly boundingBox?: PageBoundingBox;
+}
+export interface SectionRecord {
+    readonly documentId: DocumentId;
+    readonly sectionPath: readonly string[];
+    readonly characterStart: number;
+    readonly characterEnd: number;
+}
+export type ParsedUnit = {
+    readonly kind: "page";
+    readonly documentId: DocumentId;
+    readonly pageNumber: number;
+    readonly pageLabel?: string;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+} | {
+    readonly kind: "section";
+    readonly documentId: DocumentId;
+    readonly sectionPath: readonly string[];
+    readonly characterStart: number;
+    readonly characterEnd: number;
+} | {
+    readonly kind: "json-path";
+    readonly documentId: DocumentId;
+    readonly jsonPointer: string;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+} | {
+    readonly kind: "csv-row";
+    readonly documentId: DocumentId;
+    readonly tableName: string;
+    readonly rowIndex: number;
+    readonly characterStart: number;
+    readonly characterEnd: number;
+} | {
+    readonly kind: "html-block";
+    readonly documentId: DocumentId;
+    readonly headingPath?: readonly string[];
+    readonly characterStart: number;
+    readonly characterEnd: number;
+} | {
+    readonly kind: "unsupported-media";
+    readonly documentId: DocumentId;
+    readonly reason: string;
+};
+export type ParsedUnitKind = ParsedUnit["kind"];
+export declare const PARSED_UNIT_KINDS: readonly ParsedUnitKind[];
+export interface ChunkRecord {
+    readonly id: ChunkId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly parsedUnit: ParsedUnit;
+    readonly orderIndex: number;
+    readonly tokenCount: number;
+    readonly safeExcerptHash: string;
+}
+export interface VectorRecord {
+    readonly id: VectorId;
+    readonly chunkId: ChunkId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly documentId: DocumentId;
+    readonly embeddingIdentity: EmbeddingModelIdentity;
+    readonly vectorDimensions: number;
+    readonly storageReference: string;
+    readonly createdAt: number;
+}
+export interface CitationReference {
+    readonly documentId: DocumentId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceId: KnowledgeSourceId;
+    readonly chunkId: ChunkId;
+    readonly pageNumber?: number;
+    readonly pageLabel?: string;
+    readonly sectionPath?: readonly string[];
+    readonly jsonPointer?: string;
+    readonly tableName?: string;
+    readonly rowIndex?: number;
+    readonly characterStart?: number;
+    readonly characterEnd?: number;
+    readonly safeDisplayName: string;
+}
+export interface RetrievalReference {
+    readonly chunkId: ChunkId;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly score: number;
+    readonly citation: CitationReference;
+}
+export type ParserDiagnosticSeverity = "info" | "warning" | "error";
+export declare const PARSER_DIAGNOSTIC_SEVERITIES: readonly ParserDiagnosticSeverity[];
+export interface ParserDiagnostic {
+    readonly severity: ParserDiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly documentId?: DocumentId;
+    readonly pageNumber?: number;
+}
+export interface ParserResult {
+    readonly documentId: DocumentId;
+    readonly parser: ParserIdentity;
+    readonly pages: readonly PageRecord[];
+    readonly sections: readonly SectionRecord[];
+    readonly units: readonly ParsedUnit[];
+    readonly diagnostics: readonly ParserDiagnostic[];
+    readonly extractedAt: number;
+}
+export type IndexingJobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
+export declare const INDEXING_JOB_STATUSES: readonly IndexingJobStatus[];
+export type CapsuleReindexMode = "changed-files" | "repair-failed" | "resume";
+export declare const CAPSULE_REINDEX_MODES: readonly CapsuleReindexMode[];
+export interface CapsuleReindexRequest {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly mode?: CapsuleReindexMode;
+    readonly force?: boolean;
+}
+export interface IndexingJobError {
+    readonly code: string;
+    readonly message: string;
+}
+export interface IndexingJobRecord {
+    readonly id: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceIds: readonly KnowledgeSourceId[];
+    readonly startedAt: number;
+    readonly finishedAt?: number;
+    readonly status: IndexingJobStatus;
+    readonly totalDocuments: number;
+    readonly processedDocuments: number;
+    readonly failedDocuments: number;
+    readonly skippedDocuments: number;
+    readonly lastError?: IndexingJobError;
+    readonly largeDocumentCount?: number;
+    readonly partialCoverageDocuments?: number;
+    readonly resumableDocuments?: number;
+}
+export interface CapsuleHealth {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly sourceIds: readonly KnowledgeSourceId[];
+    readonly lifecycleState: CapsuleLifecycleState;
+    readonly storageSizeBytes: number;
+    readonly documentCount: number;
+    readonly chunkCount: number;
+    readonly vectorCount: number;
+    readonly lastIndexedAt?: number;
+    readonly embeddingIdentity: EmbeddingModelIdentity;
+    readonly vectorCompatible: boolean;
+    readonly failedDocuments: number;
+    readonly skippedDocuments: number;
+    readonly unsupportedDocuments: number;
+    readonly unsupportedGuidance: readonly string[];
+    readonly staleReasons: readonly string[];
+    readonly partialCoverageDocuments?: number;
+    readonly qualityWarnings?: readonly string[];
+    readonly resumableDocuments?: number;
+}
+export interface CapsuleDeleteRequest {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly deleteIndex: boolean;
+    readonly deleteSources: false;
+}
+//# sourceMappingURL=local-knowledge-records.d.ts.map

package/dist/local-knowledge-records.d.ts.map

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

package/dist/local-knowledge-records.js

@@ -0,0 +1,36 @@
+// Document-derived record contracts for the Local Knowledge Connector (Epic #189, Issue
+// #191). Split from `local-knowledge.ts` to keep each file under the 400-LOC budget. Every
+// record carries explicit capsuleId + sourceId + documentId lineage where applicable so a
+// single global knowledge pool is unrepresentable (Foundry IQ invariant).
+export const DOCUMENT_STATUSES = [
+    "pending",
+    "extracted",
+    "skipped",
+    "failed",
+    "unsupported",
+];
+export const PARSED_UNIT_KINDS = [
+    "page",
+    "section",
+    "json-path",
+    "csv-row",
+    "html-block",
+    "unsupported-media",
+];
+export const PARSER_DIAGNOSTIC_SEVERITIES = [
+    "info",
+    "warning",
+    "error",
+];
+export const INDEXING_JOB_STATUSES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+];
+export const CAPSULE_REINDEX_MODES = [
+    "changed-files",
+    "repair-failed",
+    "resume",
+];

package/dist/local-knowledge-schema-validation.d.ts

@@ -0,0 +1,19 @@
+import type { LocalKnowledgeValidation } from "./local-knowledge-validation.js";
+export interface CapsuleRowShape {
+    readonly id: string;
+    readonly displayName: string;
+    readonly vectorDimensions: number;
+    readonly vectorMetric: string;
+    readonly embeddingModelProvider: string;
+    readonly embeddingModelId: string;
+    readonly lifecycleState: string;
+    readonly storageReference: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export declare function validateCapsuleRowShape(input: unknown): LocalKnowledgeValidation<CapsuleRowShape>;
+export interface RedactPathOptions {
+    readonly homePrefix?: string;
+}
+export declare function redactPathInDiagnostic(rawPath: string, options?: RedactPathOptions): string;
+//# sourceMappingURL=local-knowledge-schema-validation.d.ts.map

package/dist/local-knowledge-schema-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-knowledge-schema-validation.d.ts","sourceRoot":"","sources":["../src/local-knowledge-schema-validation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAOhF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AA4CD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAAC,eAAe,CAAC,CAYjG;AA4DD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAQD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAU/F"}

package/dist/local-knowledge-schema-validation.js

@@ -0,0 +1,115 @@
+// Pure helpers for the Local Knowledge Connector persistent schema (Epic #189, Issue
+// #265). Split out from `local-knowledge-schema.ts` to keep both files under the 400-LOC
+// budget. No `node:sqlite`, no fs, no clock — these helpers only inspect or rewrite
+// strings the runtime (#193) reads from disk or surfaces to diagnostics.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isFinitePositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isFiniteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+const NON_EMPTY_STRING_FIELDS = [
+    ["id", isNonEmptyString, "must be a non-empty string"],
+    ["displayName", isNonEmptyString, "must be a non-empty string"],
+    ["vectorMetric", isNonEmptyString, "must be a non-empty string"],
+    ["embeddingModelProvider", isNonEmptyString, "must be a non-empty string"],
+    ["embeddingModelId", isNonEmptyString, "must be a non-empty string"],
+    ["lifecycleState", isNonEmptyString, "must be a non-empty string"],
+    ["storageReference", isNonEmptyString, "must be a non-empty string"],
+];
+const ROW_FIELD_CHECKS = [
+    ...NON_EMPTY_STRING_FIELDS,
+    ["vectorDimensions", isFinitePositiveInt, "must be a positive integer"],
+    ["createdAt", isFiniteNonNegative, "must be a finite non-negative number"],
+    ["updatedAt", isFiniteNonNegative, "must be a finite non-negative number"],
+];
+export function validateCapsuleRowShape(input) {
+    if (!isRecord(input)) {
+        return { ok: false, errors: ["capsuleRow must be an object"] };
+    }
+    const errors = [];
+    for (const [field, guard, errorSuffix] of ROW_FIELD_CHECKS) {
+        if (!guard(input[field])) {
+            errors.push(`capsuleRow.${field} ${errorSuffix}`);
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return { ok: true, value: input };
+}
+// ─── Diagnostic path redaction ───────────────────────────────────────────────────
+// Used by parser-diagnostic and indexing-job error construction so raw filesystem paths
+// cannot land in audit logs or UI surfaces. Pure: reads no environment, no fs, no clock.
+// The HOME prefix is supplied by the caller (the runtime in #193 resolves it once at
+// boot) so this helper stays deterministic and trivially testable.
+const REDACTED_MAX_CHARS = 1024;
+// Matches the ASCII control range; control chars in filenames are pathological and must
+// not flow into UI strings unredacted. Disable the lint rule because the regex IS the
+// gate.
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+function stripControls(value) {
+    return value.replace(CONTROL_RE, "");
+}
+function normalizeSeparators(value) {
+    return value.replace(/\\/g, "/");
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
+function truncateAtNul(value) {
+    const nulAt = value.indexOf("\0");
+    return nulAt === -1 ? value : value.slice(0, nulAt);
+}
+function replaceHomePrefix(value, homePrefix) {
+    // Normalize the homePrefix to forward-slash form first so the comparison succeeds whether
+    // the caller supplies `/Users/foo`, `C:\\Users\\foo`, or any mix. Strip trailing slashes so
+    // callers can pass either form. The empty-prefix gate short-circuits a caller-supplied "/".
+    const normalizedPrefix = trimTrailingSlashes(normalizeSeparators(homePrefix));
+    if (normalizedPrefix.length === 0)
+        return value;
+    if (value === normalizedPrefix)
+        return "~";
+    // Match the prefix followed by a separator; prevents `/Users/foobar` being misread as
+    // `/Users/foo` + `bar`.
+    if (value.startsWith(`${normalizedPrefix}/`)) {
+        return `~${value.slice(normalizedPrefix.length)}`;
+    }
+    return value;
+}
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:\/(.*)$/;
+function replaceDrivePrefix(value) {
+    const match = WINDOWS_DRIVE_RE.exec(value);
+    if (match === null)
+        return value;
+    return `<drive>/${match[1] ?? ""}`;
+}
+// Public boundary helper. Order matters: separator normalisation runs BEFORE home-prefix
+// rewriting so a Windows-style homePrefix (e.g. `C:\\Users\\foo`) compares cleanly against a
+// Windows-style input. Drive-letter masking runs LAST so it only applies to inputs that did
+// NOT match the user's home (otherwise a Windows home like `C:\\Users\\victim\\docs` would
+// be rewritten to `<drive>/Users/victim/docs` and the home-prefix could never match — the
+// #265 Copilot finding). Each step is idempotent so repeated calls return the same string.
+export function redactPathInDiagnostic(rawPath, options = {}) {
+    if (typeof rawPath !== "string")
+        return "";
+    const homePrefix = options.homePrefix ?? "";
+    const afterNul = truncateAtNul(rawPath);
+    const noControls = stripControls(afterNul);
+    const normalized = normalizeSeparators(noControls);
+    const homeRewritten = replaceHomePrefix(normalized, homePrefix);
+    const driveRewritten = replaceDrivePrefix(homeRewritten);
+    if (driveRewritten.length <= REDACTED_MAX_CHARS)
+        return driveRewritten;
+    return `${driveRewritten.slice(0, REDACTED_MAX_CHARS)}…`;
+}

package/dist/local-knowledge-schema.d.ts

@@ -0,0 +1,14 @@
+export declare const LOCAL_KNOWLEDGE_DB_SCHEMA_VERSION: 13;
+export declare const KNOWLEDGE_CAPSULE_DDL: readonly string[];
+export declare const KNOWLEDGE_CAPSULE_INDEXES: readonly string[];
+export declare const DELETE_CAPSULE_SQL: "DELETE FROM capsules WHERE id = :capsule_id;";
+export interface KnowledgeCapsuleMigration {
+    readonly version: number;
+    readonly reason: string;
+    readonly up: readonly string[];
+}
+export declare const KNOWLEDGE_CAPSULE_MIGRATIONS: readonly KnowledgeCapsuleMigration[];
+export declare const KNOWLEDGE_CAPSULE_V1_TABLES: readonly string[];
+export declare const KNOWLEDGE_CAPSULE_TABLES: readonly string[];
+export declare const KNOWLEDGE_CAPSULE_INDEX_NAMES: readonly string[];
+//# sourceMappingURL=local-knowledge-schema.d.ts.map

package/dist/local-knowledge-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-knowledge-schema.d.ts","sourceRoot":"","sources":["../src/local-knowledge-schema.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,iCAAiC,EAAG,EAAW,CAAC;AA2a7D,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAoBzC,CAAC;AAGX,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EA2B7C,CAAC;AAIX,eAAO,MAAM,kBAAkB,EAAG,8CAAuD,CAAC;AAM1F,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAoHD,eAAO,MAAM,4BAA4B,EAAE,SAAS,yBAAyB,EAkGnE,CAAC;AASX,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAa/C,CAAC;AAEX,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAQ5C,CAAC;AAEX,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EA2BjD,CAAC"}