/**
 * YAML source layer — the knowledge graph's source of truth.
 *
 * Two layouts, both read. The legacy one is a multi-document file per entity
 * type plus `relationships.yaml`, each with a `_meta` header document. New
 * records go to the other: one file per record under a directory named for the
 * type (`decisions/<id>.yaml`), because two branches appending to the end of one
 * shared file always conflicted on merge, and GitHub never runs the custom merge
 * driver (autopilot-merge-lane-stalls-on-conflicts/AC-1, AC-2, AC-7). Legacy
 * records stay where they are; an update rewrites whichever file holds the
 * record. Only the affected file is ever touched (KG Req 2.3) —
 * `compact` is the single sanctioned whole-file rewriter (KG Req 12.6), and
 * `knowledge rebuild` writes nothing here at all: the index is a derived cache
 * (knowledge-rebuild-readonly/AC-1).
 *
 * Requirements: KG 2.1–2.5, 11.1, 12.5; knowledge-rebuild-readonly/AC-1, AC-2, AC-5
 *
 * @module
 */
import type { Document } from 'yaml';
import type { Entity, Relationship } from './types.js';
/**
 * Line width every writer in this module serializes at. Preserved documents are
 * re-emitted at the same width, so a write never reflows a document it did not
 * change (knowledge-rebuild-readonly/AC-7).
 */
export declare const SOURCE_LINE_WIDTH = 100;
/**
 * The exact source text of one parsed document, marker and comments included.
 *
 * `Document.range` is `[start, valueEnd, nodeEnd]` over the stream the document
 * was parsed from, so slicing it reproduces the document verbatim — the only
 * way to rewrite one document in a file without reformatting the rest
 * (knowledge-rebuild-readonly/AC-7). Falls back to serializing if a document
 * carries no range.
 *
 * @param doc - A document from `parseAllDocuments(raw)`.
 * @param raw - The exact string that was parsed.
 */
export declare function sourceTextOf(doc: Document.Parsed, raw: string): string;
/** Result of loading all YAML sources. */
export interface LoadedGraph {
    entities: Entity[];
    relationships: Relationship[];
    /** Parse problems encountered (file → message); corrupted docs are skipped. */
    warnings: string[];
}
/** How `loadAll` reads. */
export interface LoadOptions {
    /**
     * Leave out the documents the index cannot store, with a warning naming each
     * (knowledge-block-vanishes-silently/AC-7, AC-8, AC-14). For the callers that feed
     * `index.rebuild` and nothing else. Never for `compact`, which rewrites the YAML
     * from what it loaded and so would delete the document instead of skipping it
     * (design DD4).
     */
    forIndex?: boolean;
}
/**
 * Message for a write the index believes in and the sources do not — a
 * reverted or hand-edited source file leaves the index ahead, and the repair
 * is a rebuild in that direction (knowledge-rebuild-readonly/AC-5).
 *
 * @param id - Entity the caller tried to update.
 * @param filename - Source file basename the entity's type maps to.
 * @param detail - Which half is missing, in words.
 */
export declare function indexAheadOfSources(id: string, filename: string, detail: string): string;
export declare class YamlSourceStore {
    private readonly knowledgeDir;
    constructor(knowledgeDir: string);
    /** Absolute path of the knowledge directory. */
    get dir(): string;
    /** True once any source file exists. */
    exists(): boolean;
    /** Write a new entity as its own record file (KG Req 2.5; AC-1). */
    appendEntity(entity: Entity): void;
    /**
     * Rewrite an existing entity document in place (explicit update path).
     *
     * Only the target document is re-serialized. Every other document is copied
     * out of the file byte for byte via its source range — not round-tripped
     * through the serializer, which would reflow long descriptions to whatever
     * `lineWidth` happened to be in force and requote scalars. A write must not
     * touch the documents it did not change (knowledge-rebuild-readonly/AC-7),
     * and `joinDocuments` leaves exactly one `---` between them (AC-2).
     *
     * Empty documents — the residue of the doubled-separator defect — are the one
     * thing dropped, which is what normalizes an already-damaged file.
     */
    updateEntity(entity: Entity): void;
    /**
     * Write a relationship as its own record file (KG Req 2.5; AC-2). The same
     * edge maps to the same file, so adding it again replaces it rather than
     * appending a duplicate.
     */
    appendRelationship(rel: Relationship): void;
    /**
     * Delete every record file and the directories left empty, returning their
     * paths relative to the knowledge dir. Only `compact` calls this, after it has
     * folded the records into the per-type files (AC-6).
     *
     * @param keep - Record files to leave in place (ones that could not be read).
     */
    removeRecordFiles(keep?: ReadonlySet<string>): string[];
    /**
     * Rewrite a whole source file from scratch (used only by `compact`,
     * the sanctioned exception to append-only — KG Req 12.6).
     */
    rewriteFile(filename: string, entityType: string, docs: Array<Entity | Relationship>): void;
    /** Parse every source file into entities and relationships (KG Req 3.2). */
    loadAll(options?: LoadOptions): LoadedGraph;
    /**
     * List YAML source files relative to the knowledge dir: the legacy per-type
     * files, then `<dir>/<file>` for every record file one level down (AC-4).
     */
    listSourceFiles(): string[];
    /** One document, the whole file; no `_meta` header — the directory names the type. */
    private writeRecord;
    private metaHeader;
}
//# sourceMappingURL=yaml-source.d.ts.map