/**
 * One-time import of a Claude Code memory directory as BRAIN lessons
 * (T13949 part (c), owner decision D11181).
 *
 * A dry run plans every file: which become lessons, which are skipped and why,
 * with the source provenance of each. The plan carries a digest; an apply
 * re-plans the directory and writes only when the digest still matches the
 * approved one, so what is written is exactly what was reviewed. An apply
 * records a receipt (file, sha256, lesson id) before and after writing, and
 * never deletes or edits a source file.
 *
 * Mapping: a `feedback` memory is a process rule and becomes a lesson in the
 * main (global) brain; a `project` memory is a fact about one project and
 * becomes a lesson in that project's brain, so it never reaches other
 * projects' recall or syncs to them. Its frontmatter `description` is the
 * one-line rule (the lesson title) and its body the why. `user` and
 * `reference` memories are not lessons. A memory marked wrong or superseded
 * (its description or first body line starts with PARTLY WRONG, WRONG or
 * SUPERSEDED) and any file the reviewer excludes are skipped. Each lesson's
 * text ends with its provenance line (source file and content hash), so the
 * same file imported twice is deduplicated.
 *
 * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
 *
 * @module memory/lessons-import
 * @task T13949
 */
/** Brain a lesson is written to. */
export type LessonImportScope = 'global' | 'project';
/** One memory file planned as a lesson. */
export interface LessonImportCandidate {
    /** File name inside the source directory. */
    file: string;
    /** SHA-256 of the file's bytes. */
    sha256: string;
    /** Frontmatter `name`, when present. */
    name: string | null;
    /** Frontmatter memory type (`feedback` or `project`). */
    memoryType: string;
    /** Brain the lesson is written to: `global` for feedback, `project` for project memories. */
    scope: LessonImportScope;
    /** The one-line rule (lesson title). */
    rule: string;
    /** The why, ending with the provenance line (lesson text). */
    text: string;
}
/** A memory file the import leaves out, and why. */
export interface LessonImportSkip {
    /** File name inside the source directory. */
    file: string;
    /** Why it is not imported. */
    reason: string;
}
/** What an import would write. */
export interface LessonImportPlan {
    /** Absolute source directory. */
    sourceDir: string;
    /** Files that become lessons, sorted by file name. */
    candidates: LessonImportCandidate[];
    /** Files left out, sorted by file name. */
    skipped: LessonImportSkip[];
    /** Digest of the candidate set (file, content hash, scope); an apply must match it. */
    digest: string;
}
/** One written lesson in a receipt. */
export interface LessonImportWrite {
    /** Source file. */
    file: string;
    /** Source content hash. */
    sha256: string;
    /** Brain the lesson was written to. */
    scope: LessonImportScope;
    /** Lesson id in that brain. */
    id: string;
    /** False when the same lesson already existed (the id names that entry). */
    stored: boolean;
}
/** Receipt of an applied import. */
export interface LessonImportReceipt {
    /** Receipt format version. */
    version: 1;
    /** ISO timestamp of the apply. */
    importedAt: string;
    /** `started` before the first write; `complete` after the last. */
    status: 'started' | 'complete';
    /** Absolute source directory. */
    sourceDir: string;
    /** Approved digest. */
    digest: string;
    /** Lessons written (or found already present), in plan order. */
    written: LessonImportWrite[];
}
/** An import refused before any write. */
export declare class LessonImportError extends Error {
    readonly code: 'E_LESSON_IMPORT_SOURCE' | 'E_LESSON_IMPORT_DIGEST_MISMATCH';
    /**
     * @param code - Stable error code.
     * @param message - Human-readable reason.
     */
    constructor(code: 'E_LESSON_IMPORT_SOURCE' | 'E_LESSON_IMPORT_DIGEST_MISMATCH', message: string);
}
/**
 * The Claude Code memory directory of a project: `~/.claude/projects/<root
 * with every path separator replaced by '-'>/memory`.
 *
 * @param projectRoot - Absolute project root.
 * @param home - Home directory (for tests).
 * @returns The directory path; it may not exist.
 * @example
 * ```ts
 * defaultLessonImportDir('/Users/me/repo'); // ~/.claude/projects/-Users-me-repo/memory
 * ```
 */
export declare function defaultLessonImportDir(projectRoot: string, home?: string): string;
/**
 * Plan an import: read every `*.md` file except `MEMORY.md` and decide which
 * become lessons, and where. Reads only.
 *
 * @param sourceDir - Memory directory to import.
 * @param options - `exclude`: file names the reviewer dropped; they are skipped
 *   before the digest, so the digest pins the final set.
 * @returns The plan with its digest.
 * @throws LessonImportError when the directory does not exist.
 * @example
 * ```ts
 * const plan = planLessonImport(defaultLessonImportDir(root), { exclude: ['old.md'] });
 * ```
 */
export declare function planLessonImport(sourceDir: string, options?: {
    exclude?: readonly string[];
}): LessonImportPlan;
/** Writes one lesson to the brain its scope names; injectable for tests. */
export type LessonWriter = (lesson: {
    text: string;
    title: string;
    scope: LessonImportScope;
}) => Promise<{
    id: string;
    stored?: boolean;
}>;
/**
 * Apply an approved import: re-plan the directory with the same exclusions,
 * refuse unless the digest still matches, record a receipt, then write each
 * lesson to the main brain (feedback) or the project brain (project).
 *
 * @param projectRoot - Project whose brain receives project lessons.
 * @param sourceDir - Memory directory to import.
 * @param expectDigest - Digest of the approved dry run.
 * @param receiptPath - Where the receipt is written (before the first write).
 * @param options - `exclude` as in the dry run; `write` overrides the brain writers; `now` for tests.
 * @returns The completed receipt.
 * @throws LessonImportError when the directory changed since the approved plan.
 * @example
 * ```ts
 * const receipt = await applyLessonImport(dir, plan.digest, receiptPath);
 * ```
 */
export declare function applyLessonImport(projectRoot: string, sourceDir: string, expectDigest: string, receiptPath: string, options?: {
    exclude?: readonly string[];
    write?: LessonWriter;
    now?: Date;
}): Promise<LessonImportReceipt>;
/**
 * Default receipt path of an applied lessons import.
 *
 * @param projectRoot - Project root.
 * @param importedAt - ISO timestamp of the apply.
 * @returns Absolute path under `.cleo/backups/migrations/`.
 * @example
 * ```ts
 * defaultLessonImportReceiptPath(root, '2026-10-24T00:00:00.000Z');
 * ```
 */
export declare function defaultLessonImportReceiptPath(projectRoot: string, importedAt: string): string;
//# sourceMappingURL=lessons-import.d.ts.map