import { DirectiveClass, buildDirectiveSlug, DecodedDirective } from '@ai-matrx/content-ir';

/**
 * Matrx reference taxonomy + the directive-apply receipt events.
 *
 * 🚨 THE SHELL NO LONGER LIVES HERE. A directive is
 * `{"__kind":"directive_v1_<class>_<noun>","items":[…]}` and its grammar,
 * detector and decoder are `@ai-matrx/content-ir/directives` — one shape, one
 * discriminator, shared with every other kind. What remains in this module is
 * what is genuinely reference-specific: the reference NOUN taxonomy and the
 * per-noun item shapes the chips render, plus the typed stream receipts.
 *
 * The retired 4-key shell (`matrx_version`/`kind`/`type`/`items`) is READ-ONLY
 * and understood in exactly one place — `directives/legacyShell.ts`, reachable
 * only through `decodeDirective`. Nothing here emits it and nothing here
 * detects it. See docs/protocol/KIND_DIRECTIVES.md.
 */
type DirectiveApplyStatus = "applied" | "already_applied" | "failed" | "pending";
type DirectiveFault = "agent" | "processor";
/**
 * 🚨 EVERY receipt's identity field is `directive` and it carries the SLUG.
 * There is deliberately no second field and no alias: the slug is the identity,
 * and a receipt that named the thing differently from the payload it describes
 * is the exact split the Kind Directives merge closed. Server contract:
 * aidream `services/output_directives/events.py`.
 */
interface DirectiveApplyStarted {
    kind: "directive_apply.started";
    directive: string;
    item_count: number;
}
/**
 * 🚨 THE RECEIPT SENTENCE (DD-118). Every outcome-bearing receipt carries
 * `message`: ONE sentence, in ordinary words, authored by the SERVER
 * (`aidream/services/output_directives/receipt_words.py`) from the apply's own
 * result. A client may never compose it — only the server knows whether the
 * ledger replayed, what the write-tree touched, or what the handler called it.
 * Before this field an applied write, a deduped re-send and an unconfirmed
 * proposal all rendered identically, which is how a user came to see two
 * identical cards for one project (walk K-1, 2026-09-12).
 */
interface DirectiveItemApplied {
    kind: "directive_apply.item";
    directive: string;
    index: number;
    status: Exclude<DirectiveApplyStatus, "failed">;
    resource_kind: string;
    resource_ids: string[];
    summary: string;
    /** The server's own sentence for THIS outcome. Render verbatim. */
    message: string;
}
interface DirectiveItemFailed {
    kind: "directive_apply.failed";
    directive: string;
    index: number;
    error: string;
    fault: DirectiveFault;
    /** The server's own sentence: what did not happen, and why. */
    message: string;
}
interface DirectiveApplyCompleted {
    kind: "directive_apply.completed";
    directive: string;
    applied: number;
    failed: number;
    /** The server's own closing line for the batch. */
    message: string;
}
/**
 * A model-emitted directive whose resolved apply policy is `ask` — NOT applied.
 * The client renders an approve/decline card and, on accept, POSTs `shell`
 * back to `/directives/confirm`. Idempotent by `proposal_id`. See the backend
 * cascade: aidream services/output_directives/policy.py + confirm.py.
 */
interface DirectiveProposed {
    kind: "directive_apply.proposed";
    directive: string;
    proposal_id: string;
    item_count: number;
    /** Display hints DERIVED from the slug — never a second source of identity. */
    directive_class: string;
    noun: string;
    summary: string | null;
    /** The server's own sentence: what confirming WILL make. Render verbatim. */
    message: string;
    /** The two-key shell, POSTed back to /directives/confirm verbatim. */
    shell: Record<string, unknown>;
}
/** A directive suppressed by the cascade (`off`, or `ask` with no human). */
interface DirectiveApplyBlocked {
    kind: "directive_apply.blocked";
    directive: string;
    reason: string;
    /** The server's own sentence: nothing was written, and why. */
    message: string;
}
type DirectiveApplyEvent = DirectiveApplyStarted | DirectiveItemApplied | DirectiveItemFailed | DirectiveApplyCompleted | DirectiveProposed | DirectiveApplyBlocked;
declare function isDirectiveApplyEvent(value: unknown): value is DirectiveApplyEvent;
declare function isDirectiveProposed(value: unknown): value is DirectiveProposed;

/**
 * UDT + record reference taxonomy. `dataset_cell` is a legacy alias of `table_cell`.
 * Record types (`task`, `note`, …) share the backend `RecordRef { id }` item shape.
 */
declare const REFERENCE_TYPES: readonly ["pick_list", "pick_list_group", "pick_list_item", "structured_list", "structured_list_group", "structured_list_item", "picklist", "picklist_group", "picklist_item", "table", "table_schema", "table_column", "table_row", "table_cell", "task", "note", "project", "agent", "agent_app", "transcript", "transcript_segment", "transcript_session", "session_transcript", "workbook", "workbook_sheet", "document", "document_page", "file", "file_page", "organization", "scope_type", "scope", "context_item", "context_value", "url"];
type ReferenceType = (typeof REFERENCE_TYPES)[number];
/**
 * Display hints — all optional, all non-authoritative (re-fetched live on every
 * read). Present only for instant paint + offline/LLM readability. `extra="allow"`
 * on the backend item model is mirrored here by the open-ended index signature so
 * UI fetch hints (limit / offset / sort) survive a round-trip.
 */
interface ReferenceItemHints {
    label?: string;
    table_name?: string;
    list_name?: string;
    column_display_name?: string;
    description?: string;
    [extra: string]: unknown;
}
interface PicklistRefItem extends ReferenceItemHints {
    list_id: string;
}
interface PicklistGroupRefItem extends ReferenceItemHints {
    list_id: string;
    group_name: string;
}
interface PicklistItemRefItem extends ReferenceItemHints {
    list_id: string;
    item_id: string;
}
interface TableRefItem extends ReferenceItemHints {
    table_id: string;
}
/** Column definitions only — no row payload (`table_schema` / bookmark `table_schema`). */
interface TableSchemaRefItem extends ReferenceItemHints {
    table_id: string;
}
interface TranscriptSegmentRefItem extends ReferenceItemHints {
    transcript_id: string;
    segment_index: string;
}
interface SessionTranscriptRefItem extends ReferenceItemHints {
    session_id: string;
    transcript_id: string;
}
interface WorkbookSheetRefItem extends ReferenceItemHints {
    workbook_id: string;
    sheet_id: string;
}
interface DocumentPageRefItem extends ReferenceItemHints {
    document_id: string;
    page_index: string;
}
interface FilePageRefItem extends ReferenceItemHints {
    file_id: string;
    page_number: string;
}
/** Filled cell at scope × context_item (`ctx_context_item_values`, current row). */
interface ContextValueRefItem extends ReferenceItemHints {
    scope_id: string;
    context_item_id: string;
}
interface TableColumnRefItem extends ReferenceItemHints {
    table_id: string;
    column_name: string;
}
interface TableRowRefItem extends ReferenceItemHints {
    table_id: string;
    row_id: string;
}
interface TableCellRefItem extends ReferenceItemHints {
    table_id: string;
    row_id: string;
    column_name: string;
}
/** Generic id-keyed record (`task`, `note`, `agent`, …). */
interface RecordRefItem extends ReferenceItemHints {
    id: string;
}
/**
 * An arbitrary external URL — the one reference type with no Matrx-owned id.
 * Covers anything not already modeled by a canonical entity type (a public
 * web page, a third-party doc link, …). Context items that allow `file` for
 * "our" documents allow `url` alongside it for links we don't own.
 */
interface UrlRefItem extends ReferenceItemHints {
    url: string;
}
/**
 * The canonical reference item — a flat union over the reference taxonomy. Every
 * member is identity ids + {@link ReferenceItemHints}. The open index signature
 * keeps it assignable from a generic decoded envelope (`Record<string,unknown>`).
 */
type ReferenceItem = PicklistRefItem | PicklistGroupRefItem | PicklistItemRefItem | TableRefItem | TableSchemaRefItem | TableColumnRefItem | TableRowRefItem | TableCellRefItem | TranscriptSegmentRefItem | SessionTranscriptRefItem | WorkbookSheetRefItem | DocumentPageRefItem | FilePageRefItem | ContextValueRefItem | RecordRefItem | UrlRefItem;
type JsonSchema = Record<string, unknown>;
/**
 * Build the strict output_schema (`{ name, schema, strict }`) for a directive
 * shape: the two-key shell with `__kind` pinned `const` and FIRST, plus `items`
 * as an array of the provided per-item JSON schema.
 *
 * `__kind` first is load-bearing, not cosmetic — the streaming detector types a
 * JSON document by its first key alone, and a provider that emits the keys in
 * declaration order is what makes a directive route through the kind pipeline
 * from its first bytes instead of arriving as raw text and swapping at the end.
 *
 * `additionalProperties: false` mirrors the server's `extra="forbid"`: it makes
 * "everything lives inside items" structurally true, so a stray top-level key
 * is a hard error and never a silent passthrough. The server owns the canonical
 * generator (`scripts/generate_kind_directive_registry.py`); this mirrors it for
 * FE authoring.
 */
declare function buildDirectiveOutputSchema(args: {
    name: string;
    directiveClass: DirectiveClass;
    noun: string;
    itemSchema: JsonSchema;
    strict?: boolean;
}): {
    name: string;
    strict: boolean;
    schema: JsonSchema;
};

/**
 * Matrx Envelope — reference-fence serializer + reader (the missing authoring
 * primitive named in the backend handoff).
 *
 * ONE in-content encoding for a reference: a ```matrx fence carrying the two-key
 * Kind Directive shell `{"__kind":"directive_v1_reference_<noun>","items":[…]}`.
 * This module is the
 * single FE home for PRODUCING that fence (authoring) and READING it back
 * (round-trip + display) — used by the picklist variable path today, by table /
 * secret authoring later. Never hand-assemble a fence string elsewhere.
 *
 * `readPicklistSelection` normalizes a stored picklist value (fence string, or a
 * multi-select array of fence strings + "Other" free text) into `{refs, otherText,
 * labels}`. The fence is the ONLY encoding — the legacy `picklist_ref` envelope and
 * its `legacyTranslate.ts` dual-read seam were retired 2026-07-08 after every stored
 * value was backfilled to fences.
 */

/**
 * Serialize a reference directive as the canonical ```matrx fence string
 * (verbatim-persistable). Items are the FLAT canonical shape typed per the
 * reference noun (`pick_list_item`, `table_cell`, …).
 *
 * THE ONE PLACE THE CLIENT MINTS A FENCE. Every copy-shortcut builder in this
 * feature funnels here, so the wire shape is decided once: the two-key Kind
 * Directive shell with `__kind` FIRST, serialized as one minified JSON line
 * (`{"__kind":"directive_v1_reference_<noun>","items":[…]}`). The retired 4-key
 * shell is never emitted again — it is only ever READ, by the decoder's shim.
 *
 * `type` is passed as a NOUN and the slug is BUILT by the grammar, so a fence
 * whose slug could not be parsed back is unmintable: an unknown noun throws
 * here rather than shipping a string nothing can route.
 */
declare function buildReferenceFence(args: {
    type: ReferenceType | string;
    items: ReferenceItem[];
}): string;
/**
 * The class-generic form of `buildReferenceFence` — same fence, same minified
 * shell, any grammar class (`reference`, `delete`, …). The slug is still built
 * by the grammar, so an unroutable class/noun pair throws instead of shipping.
 * Side-effect classes found in content render as a button and only run on a
 * human click (KIND_DIRECTIVES.md §4, THE POSITION LAW).
 */
declare function buildDirectiveFence(directiveClass: Parameters<typeof buildDirectiveSlug>[0], noun: string, items: ReferenceItem[]): string;
/**
 * Convenience builder for a picklist selection: one `picklist_item` reference
 * fence carrying N FLAT items (`{ list_id, item_id, label? }`). The model
 * resolves each to the item's hidden description on the wire. There is no
 * `purpose` / `slot` / `ref` / `display` — intent is decided by position; the
 * variable-map key the fence is bound to IS the slot.
 */
declare function buildPicklistItemFence(args: {
    listId: string;
    selections: Array<{
        itemId: string;
        label: string;
    }>;
}): string;
/**
 * Parse the first `reference` directive from a fence string (with or without
 * the ``` wrapper). Returns `null` when nothing decodes — never throws.
 */
declare function parseReferenceFence(value: string): {
    directive: DecodedDirective;
    items: ReferenceItem[];
} | null;
interface PicklistRefRead {
    list_id?: string | undefined;
    item_id: string;
    label: string;
}
interface PicklistSelectionRead {
    /** Ordered picklist-item refs read from the ```matrx fence(s). */
    refs: PicklistRefRead[];
    /** Ordered free-text ("Other") entries that are not picklist items. */
    otherText: string[];
    /** `refs` labels, non-empty — convenience for display. */
    labels: string[];
}
/**
 * Normalize a stored picklist value into `{ refs, otherText, labels }` — a
 * ```matrx reference fence string, or a multi-select array of fence strings +
 * "Other" free-text entries. The single read-site every picklist display /
 * round-trip caller uses.
 */
declare function readPicklistSelection(value: unknown): PicklistSelectionRead;

export { REFERENCE_TYPES, buildDirectiveFence, buildDirectiveOutputSchema, buildPicklistItemFence, buildReferenceFence, isDirectiveApplyEvent, isDirectiveProposed, parseReferenceFence, readPicklistSelection };
export type { ContextValueRefItem, DirectiveApplyBlocked, DirectiveApplyCompleted, DirectiveApplyEvent, DirectiveApplyStarted, DirectiveApplyStatus, DirectiveFault, DirectiveItemApplied, DirectiveItemFailed, DirectiveProposed, DocumentPageRefItem, FilePageRefItem, PicklistGroupRefItem, PicklistItemRefItem, PicklistRefItem, PicklistRefRead, PicklistSelectionRead, RecordRefItem, ReferenceItem, ReferenceItemHints, ReferenceType, SessionTranscriptRefItem, TableCellRefItem, TableColumnRefItem, TableRefItem, TableRowRefItem, TableSchemaRefItem, TranscriptSegmentRefItem, UrlRefItem, WorkbookSheetRefItem };