import type { Frontmatter } from "./frontmatter";
/** Root-relative path of the frontmatter sidecar inside a cache zip. */
export declare const MDX_METADATA_SIDECAR_PATH = ".immediately.run/artifacts/mdx-metadata.json";
/** The only schema version that exists. Bumping it is a coordinated change: an
 *  older reader must reject the newer file rather than misread it, which is exactly
 *  what the version check below does. */
export declare const MDX_METADATA_SCHEMA_VERSION = 1;
/** One file's entry: the source blob it was derived from, and the frontmatter. */
export interface MdxMetadataFileEntry {
    /** Git blob sha of the SOURCE the frontmatter was parsed from. The reader honors
     *  the entry only when this still equals the manifest's sha for that path — the
     *  binding that makes a stale sidecar inert rather than wrong. */
    srcSha: string;
    /** The parsed frontmatter. Never empty: both sides drop zero-key frontmatter. */
    frontmatter: Frontmatter;
}
/** The sidecar file. Keys are repo-relative paths WITH a leading slash (`/docs/x.mdx`);
 *  the reader translates them into the absolute metadata key space via `metadataKeyFor`. */
export interface MdxMetadataSidecar {
    schemaVersion: typeof MDX_METADATA_SCHEMA_VERSION;
    files: Record<string, MdxMetadataFileEntry>;
}
/** Why a sidecar (or one of its entries) was rejected. Typed so a caller can log the
 *  distinction instead of collapsing every rejection into "no metadata". */
export type MdxMetadataRejection = "not-an-object" | "schema-version" | "files-not-an-object" | "entry-not-an-object" | "entry-src-sha" | "entry-frontmatter" | "entry-frontmatter-empty";
export type MdxMetadataValidation = {
    ok: true;
    sidecar: MdxMetadataSidecar;
    rejected: {
        path: string;
        reason: MdxMetadataRejection;
    }[];
} | {
    ok: false;
    reason: MdxMetadataRejection;
};
/**
 * Validate a parsed sidecar.
 *
 * **Structure only.** Entry-level CONFINEMENT — the path names a manifest member, is
 * not in the dirty set, and its `srcSha` matches — stays with the reader, which is
 * the only side holding the manifest and the writable-layer view. This validator
 * answers "is this the format?", never "may I trust this entry?".
 *
 * A malformed FILE is rejected whole (`ok: false`): a wrong `schemaVersion` means the
 * reader does not know what it is looking at, so honoring the parts it recognizes
 * would be the misreading the version exists to prevent. A malformed ENTRY inside a
 * well-formed file is dropped and REPORTED in `rejected` — one bad file must not cost
 * a repo its whole cached metadata, but a silent drop is how "the cache seeded
 * nothing" becomes indistinguishable from "there was nothing to seed".
 */
export declare function validateMdxMetadataSidecar(raw: unknown): MdxMetadataValidation;
/**
 * Parse + validate raw sidecar TEXT. Unparseable JSON is `not-an-object`: from the
 * reader's position a truncated file and a file full of the wrong thing are the same
 * event — the sidecar cannot be used, fall back to a live scan.
 */
export declare function parseMdxMetadataSidecar(text: string): MdxMetadataValidation;