import { K as KIND_KEY } from './kind-schema.types-ByGiQxlQ.js';

/**
 * Kind Directives — the grammar, the shell, and the position law (kernel edition).
 *
 * ONE system (Arman, 2026-08-23): the Matrx Envelope/Directive protocol and the
 * Content IR kind system are one system. A directive is an ordinary kind
 * instance — `{ "__kind": "directive_v1_<class>_<noun>", "items": [...] }` —
 * whose registered shape additionally carries execution semantics on the
 * server. This module is the PURE half, ported verbatim from the aidream source
 * of record (`packages/matrx-graph/matrx_graph/content_ir/directives.py`) so
 * every UI parses the grammar identically. It lives in the KERNEL because a
 * host that can parse a kind must be able to recognize a directive without a
 * second copy of these rules (matrx-frontend carried the only copy until
 * 2026-09-08; Workflow Studio had none and rendered directives as raw text).
 *
 * THE SLUG GRAMMAR — `directive_v<version>_<class>_<noun>`:
 *  - `directive_v` is a RESERVED prefix; a hand-authored kind may never claim it.
 *  - `<class>` comes from a CLOSED vocabulary, so parsing is unambiguous even
 *    though nouns contain underscores: `directive_v1_reference_create_task` is
 *    `(reference, "create_task")`.
 *  - capability is DERIVED from the class, never stored twice.
 */

/** The reserved slug prefix. ANY kind slug starting with this belongs to the Kind Directives protocol. */
declare const RESERVED_PREFIX: "directive_v";
/** Current directive grammar version. */
declare const DIRECTIVE_VERSION: 1;
/** The full prefix of a v1 directive slug. */
declare const SLUG_PREFIX: "directive_v1_";
/** The CLOSED class vocabulary. Closed is what makes the grammar parseable. */
declare const CLASSES: readonly ["reference", "view", "create", "update", "delete", "action", "validation", "secret"];
type DirectiveClass = (typeof CLASSES)[number];
type DirectiveCapability = "pure" | "sensitive" | "side_effect";
/** class → capability. DERIVED, never stored on a shape. */
declare const CAPABILITY_BY_CLASS: Readonly<Record<DirectiveClass, DirectiveCapability>>;
/** The classes that EXECUTE at an agent's output root — a durable side effect. */
declare const SIDE_EFFECT_CLASSES: ReadonlySet<DirectiveClass>;
/**
 * The classes that resolve to a LIVE VALUE inside content. STRICT BY CHOICE,
 * mirroring the server: exactly `reference` + `secret`.
 */
declare const IN_CONTENT_CLASSES: ReadonlySet<DirectiveClass>;
/** A parsed directive slug. `slug` round-trips through `buildDirectiveSlug`. */
interface DirectiveSlug {
    slug: string;
    version: number;
    directiveClass: DirectiveClass;
    noun: string;
    capability: DirectiveCapability;
    /** Executes at an agent's output root (THE position law, half one). */
    executes: boolean;
    /** Resolves to a live value inside content (THE position law, half two). */
    inContent: boolean;
}
declare function isDirectiveClass(value: unknown): value is DirectiveClass;
/**
 * Whether `slug` sits in the reserved Kind Directives namespace. Deliberately
 * broader than {@link parseDirectiveSlug}: a MALFORMED `directive_v…` slug is
 * still reserved, so authoring gates reject it instead of letting a near-miss
 * through as an ordinary kind.
 */
declare function isReservedDirectiveSlug(slug: unknown): slug is string;
/**
 * `("create", "task") → "directive_v1_create_task"`. THROWS on a class outside
 * the closed vocabulary or an ill-formed noun — a slug that cannot be parsed
 * back must never be mintable.
 */
declare function buildDirectiveSlug(directiveClass: string, noun: string, version?: number): string;
/**
 * Parse a directive slug, or `null` when `slug` is not one. A slug that IS in
 * the reserved namespace but does not parse returns `null` too — pair with
 * {@link isReservedDirectiveSlug} to tell "ordinary kind" from "malformed
 * directive"; every such caller treats the malformed case as an ERROR.
 */
declare function parseDirectiveSlug(slug: unknown): DirectiveSlug | null;
declare function capabilityOf(directiveClass: DirectiveClass): DirectiveCapability;
/** THE position law, half one: only a side-effect class executes at an agent's output root. */
declare function executesAtOutputRoot(directiveClass: string): boolean;
/** THE position law, half two: only a pointer or a sensitive value resolves to a live value inside content. */
declare function resolvesInContent(directiveClass: string): boolean;
/**
 * The `__kind` of `obj` when it is in the reserved namespace, else null. Reads
 * the RESERVED namespace, not the parsed grammar, so a malformed directive is
 * still recognized as a directive (and rejected downstream with a real message).
 */
declare function directiveSlugOf(obj: unknown): string | null;
/** THE detector — a dict whose `__kind` is in the reserved namespace. */
declare function isKindDirective(obj: unknown): boolean;
/**
 * The two-key shell, as it travels on the wire. A TYPE alias, not an interface,
 * so a shell is structurally assignable to `Record<string, unknown>`.
 */
type KindDirectiveShell<Item = Record<string, unknown>> = {
    /** The slug. Serialized FIRST — see the module doc. */
    [KIND_KEY]: string;
    items: Item[];
};
/**
 * Build the two-key shell with `__kind` FIRST. Never hand-assemble the object
 * literal elsewhere: JS preserves insertion order for string keys, and the
 * first-key rule is what lets the streaming detector type a directive early.
 */
declare function buildKindDirective<Item>(slug: string, items: Item[]): KindDirectiveShell<Item>;
/**
 * Mid-stream recognition: the opening of a document whose FIRST key is a
 * reserved directive slug, before the closing brace has arrived. Used by
 * content splitters so a streaming envelope is typed early.
 */
declare function looksLikeDirectiveHead(content: string): boolean;

/**
 * Decode a Kind Directive — THE one entry point on every client.
 *
 * `decodeDirective()` recognizes the shell (current OR, for stored content
 * only, the retired 4-key one), reads the slug, and derives class + noun. A
 * caller only ever sees a parsed {@link DecodedDirective}; nothing downstream
 * inspects a raw shell again.
 *
 * ITEM VALIDATION IS THE SERVER'S. The registered item models live in aidream
 * (`services/content_ir_directives/registry.py`) and validate on apply; a
 * client-side copy of ~120 item models is exactly the drift the merge exists
 * to kill. The client parses identity, routes, and renders. Mirror of aidream
 * `services/content_ir_directives/decode.py`.
 */

/**
 * A well-formed-looking directive that cannot be honored (a malformed slug, or
 * a retired shell that does not map onto the grammar). Never thrown for "this
 * isn't a directive" — that is `null`.
 */
declare class DirectiveDecodeError extends Error {
    constructor(message: string);
}
interface DecodedDirective {
    /** The parsed slug — class, noun, capability and the position law. */
    readonly parsed: DirectiveSlug;
    readonly slug: string;
    readonly directiveClass: DirectiveClass;
    readonly noun: string;
    readonly items: Record<string, unknown>[];
    /** The two-key shell, normalized — what a confirm POST round-trips. */
    readonly shell: Record<string, unknown>;
    /** True when this arrived in the retired 4-key shell and was translated. */
    readonly legacyShell: boolean;
}
/**
 * A typed directive, or `null` when `value` is not a directive at all. Throws
 * {@link DirectiveDecodeError} when it IS one but cannot be honored.
 */
declare function decodeDirective(value: unknown): DecodedDirective | null;
/**
 * The forgiving read used at render seams: `decodeDirective`, but a directive
 * that cannot be honored comes back as `null` after the reason is handed to
 * `onError`. A render seam must never take a whole message block down over one
 * bad fence — but it must never swallow the reason either.
 */
declare function tryDecodeDirective(value: unknown, onError?: (message: string) => void): DecodedDirective | null;
/** `decodeDirective` over a JSON string or an already-parsed value. Non-JSON text is `null`. */
declare function tryDecodeDirectiveContent(content: unknown, onError?: (message: string) => void): DecodedDirective | null;

/**
 * THE ONE LEGACY SURFACE of the Kind Directives protocol — read-only.
 *
 * Stored content written before 2026-08-23 carries the retired 4-key shell
 * (`matrx_version` / `kind` / `type` / `items`). This module translates it into
 * the current two-key shell so `decodeDirective` sees one shape, forever. It
 * never emits, never registers a shape, has no fallback branch, and every use
 * is counted so the containment can be measured. Only `decode.ts` may import
 * it (matrx-frontend's `check-legacy-shim-containment` and aidream's
 * `test_legacy_shim_containment.py` enforce the mirror).
 */
declare function legacyShellUses(): number;
declare function resetLegacyShellUses(): void;
/** True ONLY for a genuine retired-shell directive claim (sentinel + a retired kind token). */
declare function isLegacyShell(obj: unknown): boolean;

/**
 * THE AUTO-VIEW's naming half: every enrolled noun "instantly has a view" —
 * the prefix rule gives it a renderer, and this gives it a NAME. A shape the
 * client has never heard of must still read as "Create Agent · Agents", never
 * as the raw `agent` token and never as a slug.
 *
 * The catalog (`platform.entity_types` → the server's directive catalog) is the
 * authority for `label` / `family` / `title_column`; a host that mirrors it
 * passes a {@link DirectiveNounCatalog}. Without one — or for a noun the
 * catalog does not carry (a Kind Action like `plan_tree`) — the name degrades
 * to a title-cased token: legible, honestly derived, never blank.
 */

interface DirectiveNounEntry {
    /** The noun's human name — "Agent", "Plan tree". */
    label?: string | null;
    /** The catalog family ("Agents"). */
    family?: string | null;
    /** Which field of a row names it (`name`, `title`, …). */
    titleColumn?: string | null;
}
/** A host-supplied lookup over the mirrored catalog. `undefined` = not carried. */
type DirectiveNounCatalog = (noun: string) => DirectiveNounEntry | undefined;
interface DirectiveDisplay {
    /** The noun's human name — "Agent", "Plan tree". */
    noun: string;
    /** The catalog family ("Agents"), or "" when the catalog has none. */
    family: string;
    /** What this directive DOES, in the user's words — "Create", "Reference". */
    action: string;
    /** One line: "Create Agent". */
    title: string;
}
/** `plan_node_patch` → `Plan Node Patch` — THE humanizer, the honest last resort. */
declare function titleCaseToken(token: string): string;
/**
 * How a class reads to a human. `action` is deliberately "Run": a Kind Action
 * is a named procedure, and "Action Plan tree" reads like a noun phrase where a
 * verb belongs. Mirrored by the server's kind-catalog label.
 */
declare const ACTION_BY_CLASS: Readonly<Record<DirectiveClass, string>>;
declare function nounLabel(noun: string, catalog?: DirectiveNounCatalog): string;
declare function nounFamily(noun: string, catalog?: DirectiveNounCatalog): string;
declare function nounTitleColumn(noun: string, catalog?: DirectiveNounCatalog): string | null;
/** Everything a generic card needs to name a directive it cannot render. */
declare function directiveDisplay(directiveClass: DirectiveClass, noun: string, catalog?: DirectiveNounCatalog): DirectiveDisplay;

/**
 * What to call this item. `titleColumn` is the noun's catalog title column
 * (consulted first); null when the catalog carries none.
 */
declare function catalogItemTitle(item: Record<string, unknown>, titleColumn: string | null, index: number, total: number): string;
/** A one-line subtitle when the item carries prose about itself. */
declare function itemSubtitle(item: Record<string, unknown>): string | null;
interface ItemFact {
    key: string;
    label: string;
    value: string;
}
/**
 * Up to `limit` scalar facts about the item — counts for collections, values
 * for scalars. Nested objects are deliberately absent (they belong in the
 * panel), and so is anything already carried by the title/subtitle.
 */
declare function itemFacts(item: Record<string, unknown>, limit?: number): ItemFact[];

/**
 * THE DIRECTIVE⇄KIND SEAM, client side.
 *
 * Arman, 2026-08-26: the envelope / Matrx-Actions system and the Shape (kind)
 * system are ONE system with several methods inside it. They meet at the ITEM.
 * A directive is a CONTAINER; its items are the payload, and when the server's
 * item model is already a `KindModel`, that payload IS a registered kind
 * instance — so the kind system already knows how to validate, render and copy
 * it.
 *
 * The seam is SERVER-DERIVED (`ShapeSpec.item_kind`). Since 2026-09-08 the ONE
 * kind endpoint publishes every directive shape as a KindDescriptor whose
 * `items` EDGE names the item kind, so a client reads it from the same
 * catalog it already holds — {@link directiveItemKindFromEdges}. A host that
 * mirrors the directive catalog manifest instead passes its map as a
 * {@link DirectiveItemKindLookup}. `null` is HONEST, never a gap-filler.
 */
/** A host-supplied lookup: slug → the kind ONE item is, or null. */
type DirectiveItemKindLookup = (slug: string) => string | null;
/** The `items` edge of a directive KindDescriptor, as the kind catalog serves it. */
interface DirectiveItemsEdge {
    field_name?: string;
    fieldPath?: string;
    child_kind?: string;
    childKind?: string;
}
/** The item kind named by a directive descriptor's `items` edge, or null. */
declare function directiveItemKindFromEdges(edges: readonly DirectiveItemsEdge[] | null | undefined): string | null;
/**
 * The item, presented the way the kind pipeline expects it: `__kind` FIRST so a
 * consumer types the object from its own first key. `__kind` is ADDED, never
 * overwritten: an item that already carries its marker keeps the value it was
 * emitted with. Null when no kind is known — the caller owns the generic floor.
 */
declare function asKindInstance(item: Record<string, unknown>, kind: string | null): Record<string, unknown> | null;

export { ACTION_BY_CLASS, CAPABILITY_BY_CLASS, CLASSES, DIRECTIVE_VERSION, DirectiveDecodeError, IN_CONTENT_CLASSES, KIND_KEY, RESERVED_PREFIX, SIDE_EFFECT_CLASSES, SLUG_PREFIX, asKindInstance, buildDirectiveSlug, buildKindDirective, capabilityOf, catalogItemTitle, decodeDirective, directiveDisplay, directiveItemKindFromEdges, directiveSlugOf, executesAtOutputRoot, isDirectiveClass, isKindDirective, isLegacyShell, isReservedDirectiveSlug, itemFacts, itemSubtitle, legacyShellUses, looksLikeDirectiveHead, nounFamily, nounLabel, nounTitleColumn, parseDirectiveSlug, resetLegacyShellUses, resolvesInContent, titleCaseToken, tryDecodeDirective, tryDecodeDirectiveContent };
export type { DecodedDirective, DirectiveCapability, DirectiveClass, DirectiveDisplay, DirectiveItemKindLookup, DirectiveItemsEdge, DirectiveNounCatalog, DirectiveNounEntry, DirectiveSlug, ItemFact, KindDirectiveShell };