import type { MemoryDoc, MemoryScope } from '../memory-resolver.js';
export declare const KINDS: readonly ["knowledge", "preference"];
export type DocKind = (typeof KINDS)[number];
/** Is `v` one of the two valid document kinds? */
export declare function isDocKind(v: unknown): v is DocKind;
export declare const RUNGS: readonly ["none", "name", "preview", "content"];
export type Rung = (typeof RUNGS)[number];
/** Ordinal of a rung on the ladder (none=0 … content=3). */
export declare function rungRank(r: Rung): number;
/** Does rung `r` disclose at least as much as `min`? — e.g.
 *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
export declare function rungAtLeast(r: Rung, min: Rung): boolean;
export declare const FALLBACK_RUNG: Rung;
/** Strip an optional `NN-` ordering prefix from ONE path segment (file or
 *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
 *  prefix) is unchanged. */
export declare function normalizeNameSegment(segment: string): string;
/** Normalize a full slash-separated path-derived doc name by stripping the
 *  optional numeric prefix from EVERY segment: `01-spine/00-has-manager` ->
 *  `spine/has-manager`. This is the identity a doc displays, dedups, and
 *  resolves under — distinct from its physical path, which keeps the prefix. */
export declare function normalizeDocName(name: string): string;
/** Resolve a doc's identity from its raw frontmatter record: an explicit
 *  `name` field wins (trimmed + normalized), else `fallbackName` (the
 *  normalized path-derived name). */
export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
/** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
 *  the node-config subject. Typed loosely on purpose — the matcher engine owns
 *  validation; structurally it is a field→matcher map with optional
 *  `all`/`any`/`not` combinators (design §4). */
export type GatePredicate = Record<string, unknown>;
/** The frontmatter-derived schema of a substrate document, with kind-aware
 *  defaults applied. Required fields (`kind`/`when-and-why-to-read`) and
 *  optionals all resolved to concrete typed values. */
export interface SubstrateSchema {
    /** Which of the two semantic kinds (knowledge | preference). */
    kind: DocKind;
    /** The read-routing line — a single sentence answering WHEN to read this doc
     *  and WHY it is worth the read: "When <circumstance>, this <kind> should be
     *  read because <broader downstream payoff>." (design §4). This is
     *  read-routing: WHY is the reader's payoff for the task in front of them,
     *  NEVER a document summary, its rule, or that rule reworded as an outcome (a
     *  benefit-shaped restatement still fails). It IS the preview verbatim.
     *  Frontmatter key `when-and-why-to-read`. */
    whenAndWhyToRead: string;
    /** Human-facing abbreviation for `crtr memory list`. NEVER loaded into an
     *  agent's context (design §3). Empty string when absent. */
    shortForm: string;
    /** How much surfaces at boot (system prompt / autoloaded context). */
    systemPromptVisibility: Rung;
    /** How much surfaces on-read (when a related file is read). */
    fileReadVisibility: Rung;
    /** Optional eligibility predicate over the node's own config. Absent ⇒ always
     *  eligible. An empty `{}` is carried as-is and is inert (never matches) — see
     *  `gatePasses`. */
    gate?: GatePredicate;
    /** Optional glob list narrowing the on-read trigger to matching read files.
     *  Absent ⇒ positional trigger only. A single glob is normalized to a 1-list. */
    appliesTo?: string[];
    /** Optional condition over the READ FILE's own frontmatter — the on-read
     *  frontmatter trigger (Stream A native rules). Same coercion + predicate
     *  vocabulary as `gate` (non-null non-array object carried; empty `{}` inert),
     *  but evaluated by `evalCondition` against the read file's parsed YAML rather
     *  than the node subject. Absent ⇒ no frontmatter trigger. Frontmatter key
     *  `read-when`. */
    readWhen?: GatePredicate;
    /** Opt-in: this doc is invocable as a pi slash command (`/<name>`, `/` in a
     *  nested name rendered as `:`). Default `false` — most docs are consulted,
     *  not invoked. Frontmatter key `slash`. */
    slash: boolean;
    /** The gap this doc exists to close — the observed agent failure that
     *  prompted it (CTO ruling 2026-07-03, `taste/document-substrate` §"Rationale
     *  is a frontmatter field, never delivered"). MAINTAINER-FACING ONLY: excluded
     *  from every delivered surface by construction — it is frontmatter, never
     *  body, so it never reaches a boot render, on-read injection, or `memory
     *  read` content output; only the raw file at `path` (or `memory read
     *  --frontmatter`) shows it. It is NOT read-routing (`whenAndWhyToRead` owns
     *  that) and NOT a content summary (`shortForm` owns that) — it answers
     *  "what observed failure made this doc exist," never "why obey it." Absent
     *  when the doc carries none. Frontmatter key `rationale`. */
    rationale?: string;
}
/** A fully-resolved substrate document: the parsed schema PLUS the resolver's
 *  identity (explicit frontmatter `name` when present, otherwise the normalized
 *  path-derived fallback) and body. This single object flows through the whole
 *  pipeline (gate eval → boot/on-read render), so a renderer never re-parses. */
export interface SubstrateDoc extends SubstrateSchema {
    /** Resolver-supplied identity, e.g. `taste/document-substrate` or an explicit
     *  frontmatter name when one is present. */
    name: string;
    /** The scope this doc resolved from. */
    scope: MemoryScope;
    /** Absolute path to the source .md. */
    path: string;
    /** Document body, frontmatter stripped. */
    body: string;
}
/** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
 *  resolver) into a typed schema with defaults applied. Returns `null` when the
 *  record is absent or carries no valid `kind` — i.e. it is not a substrate
 *  document and cannot be classified. Tolerant of every other imperfection (a
 *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
 *  to the neutral floor `none`), so a renderer mapping over many docs never
 *  throws. Authoring-time enforcement of these fields lives in `crtr memory
 *  write` (on create) and `crtr memory lint`. */
export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
/** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
 *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc
 *  (no valid `kind`), so callers can `docs.map(parseSubstrateDoc).filter(...)`. */
export declare function parseSubstrateDoc(doc: MemoryDoc): SubstrateDoc | null;
/** The kind a doc resolves to for `--kind` filtering/matching: the substrate
 *  kind when the frontmatter parses as a valid substrate doc, else the raw
 *  frontmatter `kind` string when present (even if not one of the two valid
 *  kinds — an authoring error, not grounds to silently reclassify it), else
 *  the legacy default `knowledge` for a frontmatter-less/kindless doc. The
 *  single coercion `memory read`'s resolution and result display share, so a
 *  `--kind` filter and the displayed `kind` field never disagree. */
export declare function effectiveDocKind(doc: MemoryDoc): string;
/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
 *  field rendered essentially verbatim — it is already authored as the complete
 *  routing sentence ("When …, this <kind> should be read …"), so there is no
 *  template to compose. Both boot and on-read render this identical line, so it
 *  lives once here to prevent drift. Light cleanup normalizes the trailing
 *  period. */
export declare function previewLine(doc: Pick<SubstrateSchema, 'whenAndWhyToRead'>): string;