/**
 * Structural database port used by `SiteService` and
 * `DomainResolverService`.
 *
 * The site plugin depends on the canonical `@suaveplan/db`
 * `DatabaseAdapter.query` surface only — positional-binding strings via
 * `$p0`, `$p1`, ... — plus the typed CRUD subset
 * (`create` / `update`) exposed by `@suaveplan/surrealdb`'s
 * `SurrealAdapter`. The genesis `DatabaseAdapter` interface owns only
 * `query` / `execute`, so we declare the typed-CRUD surface here as a
 * structural extension that real `SurrealAdapter` instances satisfy.
 *
 * Defining the port here decouples production wiring (which goes
 * through `ServiceRegistry["db"]` typed as `SurrealAdapter`) from tests
 * (which can supply any object conforming to this shape). No casts at
 * the call site — the service constructor accepts this port directly.
 */
export interface SiteDb {
    /**
     * Execute a positional-binding SurQL statement. Inputs are bound as
     * `$p0`, `$p1`, ... via `paramsToRecord` in the SurrealAdapter
     * adapter; consumers of this port write the SurQL accordingly.
     */
    query<T = Record<string, unknown>>(
        sql: string,
        params?: readonly unknown[]
    ): Promise<T[]>;

    /**
     * Typed CRUD create — `SurrealAdapter.create`. Returns the created
     * record with its assigned id.
     */
    create<T extends Record<string, unknown>>(
        table: string,
        data: T
    ): Promise<T & { id: string }>;

    /**
     * Typed CRUD update — `SurrealAdapter.update`. Returns the updated
     * record, or `null` when no row matched.
     */
    update<T extends Record<string, unknown>>(
        table: string,
        id: string,
        data: Partial<T>
    ): Promise<T | null>;
}