/**
 * Closed safety vocabulary — drives confirmation UX in the future runtime.
 *
 * `phi` marks an action that reads-back-into or WRITES Protected Health
 * Information (patient-identifiable clinical/contact/financial data). It is
 * distinct from `write` so the host can gate PHI mutations behind stricter
 * confirmation + audit than ordinary view-config writes — see
 * `src/docs/26-agent-readiness.mdx` §PHI. Added 2026-06-24 (DS-owner approved)
 * for `PatientDetails.update_field`.
 */
export declare const SAFETY_CLASSES: readonly ["read", "write", "destructive", "phi"];
export type Safety = (typeof SAFETY_CLASSES)[number];
/**
 * Closed capability vocabulary. Adding a capability requires a DS-maintainer
 * approval + an entry in `src/docs/26-agent-readiness.mdx`.
 */
export declare const CAPABILITIES: readonly ["select_single", "select_multiple", "range_pick", "pick", "filter", "sort", "paginate", "expand", "edit_inline", "set_value", "navigate", "submit", "dismiss", "confirm", "capture", "copy", "scroll", "open", "close", "view_change", "range_navigate"];
export type Capability = (typeof CAPABILITIES)[number];
/**
 * Canonical mapping from the closed safety vocabulary to MCP tool annotations.
 * A future MCP-server build lifts these verbatim onto each generated tool —
 * `read` → read-only, `destructive` → destructive, `write` → neither hint.
 * `phi` is NOT read-only and carries `destructiveHint: true` so the runtime
 * applies the same confirm-before-act gate as `destructive` — a PHI mutation
 * is irreversible from the agent's perspective (it changes a patient's record)
 * and must never be auto-confirmed.
 * `idempotentHint` / `openWorldHint` are NOT derivable from safety alone and
 * come from the per-action `idempotent` / `openWorld` fields below.
 */
export declare const SAFETY_ANNOTATIONS: {
    readonly read: {
        readonly readOnlyHint: true;
        readonly destructiveHint: false;
    };
    readonly write: {
        readonly readOnlyHint: false;
        readonly destructiveHint: false;
    };
    readonly destructive: {
        readonly readOnlyHint: false;
        readonly destructiveHint: true;
    };
    readonly phi: {
        readonly readOnlyHint: false;
        readonly destructiveHint: true;
    };
};
/**
 * Externally-observable state slot. `read` is pure and synchronous; async
 * state must be projected through a synchronous snapshot. Returns identifiers
 * and structural state — never PHI (see PRS §Security).
 */
export interface AgentStateSlot<THandle> {
    /** Type label (e.g. `'string[]'`, `'object'`, `'number'`). No runtime validation. */
    type: string;
    description?: string;
    /** i18n key resolving to a human description (preferred over `description`). */
    descriptionKey?: string;
    read: (handle: THandle) => unknown;
}
/**
 * One callable operation against a component instance. The future UI bridge
 * looks up `(adapter.id, instanceId)` in the registry, resolves the handle,
 * and invokes the action.
 */
export interface AgentActionExample<TArgs = unknown> {
    /** A concrete argument payload demonstrating a valid call. */
    args?: TArgs;
    /** i18n key or literal note explaining the example. */
    note?: string;
}
export interface AgentAction<THandle, TArgs = unknown> {
    safety: Safety;
    /** Human type label for `args` (e.g. `'{ ids: string[] }'`) — descriptive. */
    argsType?: string;
    /**
     * Machine-readable JSON Schema for `args`. This is what a future MCP server
     * lifts into the tool's `inputSchema`. When present it is the source of truth;
     * `argsType` remains the human label. Omit for no-arg actions.
     */
    argsSchema?: Record<string, unknown>;
    /** Human type label for the value `invoke` resolves to (e.g. `'string[]'`). */
    returns?: string;
    /** JSON Schema for the resolved value — maps to an MCP tool `outputSchema`. */
    returnsSchema?: Record<string, unknown>;
    /**
     * True when calling twice with the same args has the same effect as calling
     * once (e.g. `set_value`, `go_to_page`). Maps to MCP `idempotentHint`.
     */
    idempotent?: boolean;
    /**
     * True when the action reaches a system outside this UI (server write,
     * external fetch, clipboard). Maps to MCP `openWorldHint`.
     */
    openWorld?: boolean;
    /** Expected failure modes the MCP server can pre-declare (free-text hints). */
    errors?: string[];
    /** Example calls — improve an LLM's first-try tool-call accuracy. */
    examples?: AgentActionExample<TArgs>[];
    /** Stability tier. Absent ⇒ treated as `stable`. */
    stability?: 'stable' | 'experimental';
    /** Deprecation marker — `true`, or a string explaining the replacement. */
    deprecated?: boolean | string;
    description?: string;
    descriptionKey?: string;
    invoke: (handle: THandle, args: TArgs) => unknown | Promise<unknown>;
}
/** A `data-*` attribute the component emits. */
export interface DomHook {
    /** Attribute name, e.g. `"data-component"`, `"data-row-id"`. */
    attr: string;
    /** Static value, when the attribute is fixed. */
    value?: string;
    /** Component prop the value is sourced from (e.g. `"gridId"`). */
    sourceProp?: string;
    description?: string;
}
/**
 * Per-component agent contract. Co-located as `<name>.agent.ts`. Pure module
 * — no React imports, no side effects on import. Operations are pure functions
 * of `(handle, args) => result`.
 */
export interface AgentAdapter<THandle = unknown> {
    /** Kebab-case id, MUST equal the parent directory name. */
    id: string;
    capabilities: Capability[];
    state: Record<string, AgentStateSlot<THandle>>;
    actions: Record<string, AgentAction<THandle, any>>;
    domHooks: {
        root: DomHook;
        instanceId?: DomHook;
        item?: DomHook;
    };
}
/** One slot in a pattern's composition graph. */
export interface PatternComposition {
    /** Component adapter id this slot uses. */
    component: string;
    /** Slot label within the pattern (e.g. `"roster"`, `"bulkArchive"`). */
    as: string;
    /**
     * Domain entity rendered in this slot, when the slot represents a
     * collection (`patient`, `appointment`, `invoice`). Drives the
     * `data-<entity>-id` attribute on repeated items.
     */
    entity?: string;
}
/**
 * One workflow exposed by a pattern. `apiActions` are string contracts —
 * the platform team owns the actual MCP API tool names and reconciles
 * during MCP-server build.
 */
export interface PatternWorkflow {
    description?: string;
    descriptionKey?: string;
    safety: Safety;
    /** Adapter actions this workflow invokes, formatted as `"<component-id>.<action>"`. */
    uiActions: string[];
    /**
     * Adapter STATE slots this workflow reads, formatted as
     * `"<component-id>.<slot>"`. Use this instead of inventing a fake action when
     * a workflow needs to read live state (e.g. `"data-table.selection"`).
     */
    stateReads?: string[];
    /** API operations this workflow ultimately calls, formatted as `"<resource>.<verb>"`. */
    apiActions: string[];
}
/**
 * Per-pattern agent contract. Co-located as `<name>.agent.ts` under
 * `src/patterns/<name>/`. Consumed only at build time — patterns do NOT
 * register at runtime.
 */
export interface PatternAgent {
    /** Kebab-case id, MUST equal the parent directory name. */
    id: string;
    composes: PatternComposition[];
    workflows: Record<string, PatternWorkflow>;
}
export interface CatalogStateSlot {
    name: string;
    type: string;
    description?: string;
    /** Carried through so the host can re-resolve in the user's locale at runtime. */
    descriptionKey?: string;
}
export interface CatalogAction {
    name: string;
    safety: Safety;
    argsType?: string;
    argsSchema?: Record<string, unknown>;
    returns?: string;
    returnsSchema?: Record<string, unknown>;
    idempotent?: boolean;
    openWorld?: boolean;
    errors?: string[];
    examples?: AgentActionExample[];
    stability?: 'stable' | 'experimental';
    deprecated?: boolean | string;
    description?: string;
    /** Carried through so the host can re-resolve in the user's locale at runtime. */
    descriptionKey?: string;
}
export interface CatalogDomHook {
    attr: string;
    value?: string;
    sourceProp?: string;
    description?: string;
}
export interface CatalogComponent {
    kind: 'component';
    id: string;
    capabilities: Capability[];
    state: CatalogStateSlot[];
    actions: CatalogAction[];
    domHooks: {
        root: CatalogDomHook;
        instanceId?: CatalogDomHook;
        item?: CatalogDomHook;
    };
}
export interface CatalogPattern {
    kind: 'pattern';
    id: string;
    composes: PatternComposition[];
    workflows: Array<{
        name: string;
        safety: Safety;
        description?: string;
        descriptionKey?: string;
        uiActions: string[];
        stateReads?: string[];
        apiActions: string[];
    }>;
}
export interface AgentCatalog {
    schemaVersion: 1;
    packageVersion: string;
    components: CatalogComponent[];
    patterns: CatalogPattern[];
}
//# sourceMappingURL=types.d.ts.map