// The Continuum identity + public surface of the `qubes-sqlite` library qube.
//
// A library qube interacts with its host only through this WIT world — the
// world *is* the sandbox boundary (no import => no access). v0 exports the
// SQL engine and imports nothing: the engine is in-memory, so it needs no host
// capabilities. The persistence path (a `wasi:blobstore`-style import so the
// host can snapshot the database image to OPFS/R2) is the next slice and is
// sketched as a commented import below.
//
// This is the canonical contract. The browser runtime form ships today as a
// wasm-bindgen build (see ../build.sh); a component that literally exports this
// world follows once jco transpile / `qube wac` linking land in qubepods.

package qubepods:sqlite@0.1.1;

interface types {
    // A single SQL value — SQLite's five storage classes.
    variant value {
        null,
        integer(s64),
        real(f64),
        text(string),
        blob(list<u8>),
    }

    // Rows + column names from a row-producing statement.
    record query-result {
        columns: list<string>,
        rows: list<list<value>>,
    }

    // Side effects of a row-less statement.
    record run-result {
        changes: s64,
        last-insert-rowid: s64,
    }

    // Engine errors.
    variant error {
        // Open / connect failed.
        open(string),
        // Compile or execution failed (syntax, constraint, …).
        sql(string),
    }
}

// The SQL engine surface.
interface engine {
    use types.{value, query-result, run-result, error};

    // An open, single-connection database.
    resource database {
        // Open a fresh in-memory database.
        open-in-memory: static func() -> result<database, error>;

        // Execute one or more ';'-separated statements with no parameters and
        // no result rows (DDL / batch setup).
        execute-batch: func(sql: string) -> result<_, error>;

        // Run a row-producing statement; params bind positionally (1-based).
        query: func(sql: string, params: list<value>) -> result<query-result, error>;

        // Run a row-less statement (INSERT/UPDATE/DELETE) and report effects.
        run: func(sql: string, params: list<value>) -> result<run-result, error>;

        // Open a database from a serialized SQLite image (e.g. an uploaded file).
        open-from-bytes: static func(image: list<u8>) -> result<database, error>;

        // Serialize the whole database to a SQLite file image (for download).
        export-database: func() -> result<list<u8>, error>;
    }
}

// The library qube's world: it offers the engine and (v0) needs nothing.
world sqlite {
    export engine;

    // Next slice — durable persistence with R2 as the source of truth. The
    // host supplies blob storage (browser: OPFS cache backed by R2); the engine
    // snapshots/restores its database image through it. Declared as an import
    // so the capability is visible in the manifest/QAD, never ambient:
    //
    //   import wasi:blobstore/blobstore@0.2.0-draft;
}