import { MandateKey, DynamicMandateKey } from '@ai-matrx/api/intelligence';
export { ALL_MANDATE_KEYS, DYNAMIC_MANDATE_FAMILIES, DynamicMandateFamilyPrefix, DynamicMandateKey, MANDATE_FAMILIES, MANDATE_KEYS, MANDATE_KEYS_META, MandateFamilyMember, MandateFamilyPrefix, MandateKey, RETIRING_MANDATE_KEYS, mandateKeyOfApp, mandateKeyOfShortcut } from '@ai-matrx/api/intelligence';

/**
 * The Mandate CONTRACT, client-side — one leaf module so both the resolution
 * path (`service.ts`) and the binding-editor path (`overrides.ts`) read the
 * same shape without importing each other.
 *
 * 🚨 THE DOCUMENT-VARIABLE LAW (disease D4, Arman 2026-08-19). A Mandate's
 * `required_variables` are not decoration and not only a BIND-time check
 * against what the agent declares. They are also a RUN-time precondition on
 * what the CALLER supplies:
 *
 *   "this agent should never have even started without getting the rules in
 *    place."
 *
 * `missingRequiredVariables` is the one implementation of that check. A run
 * whose required variable is absent or blank REFUSES — there is no seed
 * fallback and no "the model can fetch it with a tool" consolation, because a
 * document that arrives by tool call is a document that gets skimmed.
 *
 * Law: `common-docs/systems/agent-variable-binding/FEATURE.md` § THE
 * USER-INPUT LAW · register: `common-docs/operations/agent-failure-diseases.md` § D4.
 */

interface MandateContract {
    requiredVariables: string[];
    requiredContextPolicyKeys: string[];
    requiredOutputKeys: string[];
    /**
     * Variables the contract deliberately delivers as user text instead of a
     * declared variable (Scenario 4). A spilled variable still ARRIVES, so it is
     * never counted as missing — but structured content may never take this
     * path.
     */
    spillVariables: string[];
    /**
     * The Mandate's context kill switch (`contract.auto_context_disabled`): only
     * the Holder's declared Context Policies reach it, unless the person turned a
     * value on themselves (common-docs context-delivery RULES.md §2). The
     * composer's context table needs it to show the truth before the first turn.
     */
    autoContextDisabled: boolean;
}
declare const EMPTY_MANDATE_CONTRACT: MandateContract;
declare function parseMandateContract(contract: unknown): MandateContract;
/**
 * Which of the Mandate's required variables the caller did NOT actually
 * supply. Blank counts as missing: a required document that resolved to an
 * empty string is the wiring failure this check exists to catch, and a
 * deliberately empty document must still say so in words (see
 * `features/masterwork/agent-context/rulebookDocument.ts`).
 *
 * Spilled variables are excluded — they arrive as user text, so they are
 * delivered, just not as a named variable.
 */
declare function missingRequiredVariables(contract: MandateContract, supplied: Record<string, unknown> | null | undefined): string[];
/** The one refusal message, so every surface says the same thing. */
declare function missingVariablesMessage(mandateKey: AnyMandateKey, missing: string[]): string;

/**
 * `@ai-matrx/agents/runtime` — the RUN TIER's row types (agent core B2).
 *
 * The run tier is everything a client needs to RUN an agent and nothing it needs to BUILD one:
 * name, description, variables, context rules, the kill switches, the default model, UI gates,
 * tool ids, access level and the run-control counts. JSON columns are typed `unknown` here — the
 * core never interprets variable, context-policy or gate shapes; a host narrows them at its seam
 * (chat's `AgentRunTier` does).
 */
/** One `agx_get_run_tier(p_agent_id)` row. */
interface AgentRunTierRow {
    id: string;
    is_version: boolean;
    version_id: string | null;
    name: string;
    description: string | null;
    variable_definitions: unknown[] | null;
    context_policies: unknown[] | null;
    auto_context_disabled: boolean;
    model_id: string | null;
    ui_gates: Record<string, unknown> | null;
    tool_ids: string[] | null;
    access_level: string;
    custom_tool_count: number;
    skill_count: number;
    connection_count: number;
    /** The agent's model settings (a small object): the override-diff base and what "Model and overrides" shows. */
    settings?: Record<string, unknown> | null;
}

interface MandateDisplaySeed {
    mandateKey: string;
    /** The system-rung Holder (`agent.definition` id). */
    agentId: string;
    /** The Holder's `created_by` — `agx_get_access_level` `is_owner` is exactly `created_by = auth.uid()`. */
    ownerId: string | null;
    /** The Holder's `output_schema` (null = none) — the Output pill's lock check, unread. */
    outputSchema: unknown;
    /**
     * What `agx_get_run_tier` answers for that Holder, EXCEPT `access_level`: a constant
     * "viewer" floor, never this person's level (the client lifts it to "owner" from
     * `ownerId`; the server checks every right at use).
     */
    runTier: AgentRunTierRow;
}
declare const MANDATE_DISPLAY_SEEDS: Readonly<Record<string, MandateDisplaySeed>>;

/**
 * `@ai-matrx/agents/mandates` — the ONE place a TypeScript client learns a
 * mandate key.
 *
 * 🚨 **Clients never declare a mandate.** aidream's `declare_mandate` is the
 * only declaration path in the system; this subpath publishes the key set that
 * declaration produced, so a hand-typed `"seo.keyword_cluster"` literal, a local
 * `mandates.ts` mirror, or an `as MandateKey` cast is a defect with a real
 * replacement — not a style preference. Every carrier that takes a key should
 * type it `MandateKey` (or `MandateKey | DynamicMandateKey` when it genuinely
 * accepts a DB-authored one) so a wrong key fails type-check instead of failing
 * at run time as a 404 nobody sees.
 *
 * The key data lives in `@ai-matrx/api` (`src/intelligence/keys.generated.ts`, its one
 * home), re-exported here, emitted by THE ONE GENERATOR
 * (`aidream/scripts/mandates_generate.py`, stage (h)) from the in-process
 * declarations — never edit it. The per-version key set that shipped with each
 * published version is committed beside it under `snapshots/`, so a scan can
 * resolve a client's references against the key set of the version it actually
 * ships (Mandate Declaration & Usage Reporting, DESIGN § 4.5 step 2).
 */

/**
 * What a carrier accepts when the key may be a declared one OR a DB-authored
 * one (`app.*` / `shortcut.*`, a `mandate.definition` row with origin='user').
 * Carriers that only ever run a declared job stay `MandateKey`.
 *
 * The mandate reference scanner reads a binding of this type as a proven key in
 * flight (`passthrough`), never an `UNRESOLVED_KEY` — so this is THE one
 * definition every client imports, never a local copy.
 */
type AnyMandateKey = MandateKey | DynamicMandateKey;
/**
 * A KEY THE CODE DID NOT CHOOSE, entering the typed world named for what it is:
 * a `mandate_key` column the platform wrote (an agent app's own mandate, a
 * shortcut's, a stored binding row), a stored `mandate:` ref, a saved config.
 *
 * It TYPES and never rejects. The server is the authority on whether the key
 * exists — a key declared after this package version shipped is real there and
 * absent from this build's key set — so narrowing here would send such a key
 * through the wrong door. The server answers an unknown key with a 404 that
 * names it.
 *
 * Never use it on a key your code picks: that key belongs to
 * `MANDATE_KEYS.<id>`, and routing it through here hides a rename from the
 * compiler. For a value that must be PROVEN declared (a URL segment a person
 * could have edited), use `isMandateKey` / `assertMandateKey` instead.
 */
declare function storedMandateKey(value: string): AnyMandateKey;
/**
 * Narrow an unknown string to a declared `MandateKey`.
 *
 * Use it on anything that crossed a wire — a URL segment, a stored preference,
 * a row's `mandate_key` column. It answers only for the key set THIS package
 * version ships; a key declared after this version was published is correctly
 * `false` here, which is the point of the per-version snapshots.
 */
declare function isMandateKey(value: unknown): value is MandateKey;
/**
 * Assert an unknown value is a declared `MandateKey`, or throw with a remedy.
 *
 * Nothing fails silently: the message names the value, the package version its
 * key set came from, and what to do — never a bare "invalid key".
 */
declare function assertMandateKey(value: unknown, context?: string): asserts value is MandateKey;
/**
 * A DB-AUTHORED KEY THE GENERATED UNION CANNOT CARRY — the ONE typed door for
 * a literal a client's mandate-key allowlist already governs.
 *
 * Two honest cases: an `origin='user'` mandate somebody created in the console
 * (no generator built from code declarations can ever contain it), and a key
 * aidream has declared but the installed `@ai-matrx/agents` predates. Because
 * the parameter is a literal type, the key still appears verbatim at the call
 * site for a hand-typed-key scanner and for a human reading the diff.
 *
 * 🚨 NOT an escape hatch for a declared key. A key in `MANDATE_KEYS` goes
 * through `MANDATE_KEYS.<id>`; using this for one hides a real rename from the
 * compiler. When the package publishes a key routed through here, delete the call.
 */
declare function dbAuthoredMandateKey<K extends string>(key: K): DynamicMandateKey;
interface MandateKeyParts {
    /** The feature/domain namespace before the first dot. */
    feature: string;
    /** The complete step name after the first dot; later dots are preserved. */
    mandate: string;
}
/** Split canonical `<feature>.<mandate>` identity without losing information. */
declare function splitMandateKey(mandateKey: string): MandateKeyParts;

/** The generated seed for one mandate key, or null when that key paints from a read. */
declare function mandateDisplaySeed(mandateKey: string): MandateDisplaySeed | null;
/** The generated seed whose Holder is this agent, or null. */
declare function mandateDisplaySeedForAgent(agentId: string | null | undefined): MandateDisplaySeed | null;
/**
 * The seed's run tier row AS THIS PERSON would read it: the seeded `access_level` is a constant
 * "viewer" floor, lifted to "owner" when the signed-in person created the Holder — the same
 * `created_by = auth.uid()` test `agx_get_access_level` and `agx_get_run_tier` answer with.
 */
declare function mandateDisplaySeedRunTier(seed: MandateDisplaySeed, userId: string | null | undefined): MandateDisplaySeed["runTier"];
/** Whether the signed-in person owns the seeded Holder (`is_owner`), decided with no read. */
declare function mandateDisplaySeedIsOwner(seed: MandateDisplaySeed, userId: string | null | undefined): boolean;

export { EMPTY_MANDATE_CONTRACT, MANDATE_DISPLAY_SEEDS, assertMandateKey, dbAuthoredMandateKey, isMandateKey, mandateDisplaySeed, mandateDisplaySeedForAgent, mandateDisplaySeedIsOwner, mandateDisplaySeedRunTier, missingRequiredVariables, missingVariablesMessage, parseMandateContract, splitMandateKey, storedMandateKey };
export type { AnyMandateKey, MandateContract, MandateDisplaySeed, MandateKeyParts };