/**
 * Sigil CRUD operations for the NEXUS sigils table.
 *
 * Provides the 3 SDK functions for PSYCHE Wave 8 (T1148):
 *   - getSigil     — fetch a single sigil by peer ID
 *   - upsertSigil  — create-or-update a sigil record
 *   - listSigils   — list all sigils (optionally filtered by role)
 *
 * All functions accept a `nexusDb` argument (NodeSQLiteDatabase<NexusSchema>)
 * to keep them unit-testable without touching the real nexus.db singleton.
 * Callers that do not need test isolation may use `getNexusDb()` from
 * `packages/core/src/store/nexus-sqlite.ts` directly.
 *
 * PSYCHE reference: `upstream psyche-lineage · crud/peer_card.py` (getOrCreate
 * + metadata merge pattern).
 *
 * @task T1148
 * @epic T1075
 */
import type { NexusSigilListResult } from '@cleocode/contracts';
import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
import { type EngineResult } from '../engine-result.js';
import * as nexusSchema from '../store/schema/nexus-schema.js';
/** Type alias for the Drizzle nexus database instance. */
type NexusDb = NodeSQLiteDatabase<typeof nexusSchema>;
/**
 * Wire shape for a single sigil record.
 * Mirrors `nexusSchema.SigilRow` but surfaces timestamps as ISO 8601 strings.
 */
export interface SigilCard {
    /** Stable peer identifier — matches `peer_id` on brain tables. */
    peerId: string;
    /** Absolute or relative path to the CANT agent file (.cant). Null if unset. */
    cantFile: string | null;
    /** Human-readable display name, e.g. "cleo-prime". */
    displayName: string;
    /** Short role description, e.g. "orchestrator". */
    role: string;
    /**
     * System-prompt fragment to inject into spawn payloads when this peer is
     * the active agent.  Null when no fragment is set.
     */
    systemPromptFragment: string | null;
    /**
     * JSON-encoded capability flags object, e.g.
     * `{"tier":1,"spawnRights":true,"thinAgentMode":false}`.
     * Null until flags are explicitly set.
     */
    capabilityFlags: string | null;
    /** ISO 8601 creation timestamp. */
    createdAt: string;
    /** ISO 8601 last-updated timestamp. */
    updatedAt: string;
}
/**
 * Input shape for {@link upsertSigil}.
 * `peerId` is required; all other fields are optional.
 */
export interface SigilInput {
    /** Stable peer identifier (primary key). */
    peerId: string;
    /** Path to the CANT agent file. */
    cantFile?: string | null;
    /** Human-readable display name. */
    displayName?: string;
    /** Short role description. */
    role?: string;
    /** System-prompt fragment to inject into spawn payloads. */
    systemPromptFragment?: string | null;
    /** JSON-encoded capability flags object. */
    capabilityFlags?: string | null;
}
/**
 * Fetch a single sigil by peer ID.
 *
 * Returns `null` when no matching row exists.
 *
 * @param nexusDb - Drizzle nexus database handle.
 * @param peerId  - The peer identifier to look up.
 * @returns The matching {@link SigilCard}, or `null`.
 */
export declare function getSigil(nexusDb: NexusDb, peerId: string): Promise<SigilCard | null>;
/**
 * Create or update a sigil record.
 *
 * When a row with the same `peerId` already exists, it is updated in-place
 * (last-writer-wins semantics for all mutable fields).  `createdAt` is
 * preserved from the existing row on update.
 *
 * @param nexusDb - Drizzle nexus database handle.
 * @param input   - Sigil fields to insert or update.
 * @returns The resulting {@link SigilCard} after the upsert.
 */
export declare function upsertSigil(nexusDb: NexusDb, input: SigilInput): Promise<SigilCard>;
/**
 * List all sigil records, optionally filtered by role.
 *
 * Returns an array of {@link SigilCard} objects ordered by `displayName`
 * ascending.  Returns an empty array when no sigils have been created yet.
 *
 * @param nexusDb - Drizzle nexus database handle.
 * @param opts    - Optional filter options.
 * @param opts.role - When provided, return only sigils with this role.
 * @returns Array of matching {@link SigilCard} objects.
 */
export declare function listSigils(nexusDb: NexusDb, opts?: {
    role?: string;
}): Promise<SigilCard[]>;
export declare function nexusSigilList(role?: string): Promise<EngineResult<NexusSigilListResult>>;
export {};
//# sourceMappingURL=sigil.d.ts.map