.. warning:: This is not authoritative documentation.  It describes a
   plan of work that is not yet implemented and will change as it lands.

Task 3: plugin skeleton, metadata, and DDL
==========================================

Repo: https://opendev.org/drizzle/drizzle, ``plugin/slatedb/``.
Depends on tasks 1 (shim) and 2 (codec). Delivers a loadable engine
that owns its metadata: CREATE / DROP / RENAME / SHOW work; no row
access yet (cursor methods return ``HA_ERR_WRONG_COMMAND``).

Structure, mirroring ``plugin/wiredtiger``:

- ``plugin.ini``: ``load_by_default=no``; sources; ``ldflags=-lslatedb_capi``.
  Inclusion is the explicit ``--with-slatedb`` build switch per the
  container-first policy — **no** ``plugin.ac`` detection probes; the
  builder image definitionally contains the shim.
- ``slatedb_engine.{h,cc}``, ``slatedb_to_drizzle_error.cc`` (the one
  status→``HA_ERR_*`` map), plus the task-2 codec and the capi header.

Engine init / shutdown
----------------------

``slatedb_init``: read ``slatedb.url`` / ``slatedb.path`` /
``slatedb.settings-file`` / ``slatedb.await-durable`` options
(registered through the standard plugin option machinery — note for
the CLI11 migration: four options, no custom types), check
``SLATEDB_CAPI_VERSION``, ``slatedb_open``. On first open of an empty
database, write the format-version meta key; on open of a populated
one, verify it. Engine destructor closes the Db (flush-on-close is
SlateDB's own contract).

Flags at this stage:
``HTON_ALTER_NOT_SUPPORTED | HTON_TEMPORARY_NOT_SUPPORTED |
HTON_NO_BLOBS | HTON_NULL_IN_KEY`` — no ``HTON_HAS_RECORDS``, ever,
per the spec's statistics-honesty rule.

Metadata and DDL (all via short-lived shim transactions)
--------------------------------------------------------

- ``doGetTableDefinition``: get ``0x00 'p' <path>``; parse proto;
  ``EEXIST`` / ``ENOENT``.
- ``doDoesTableExist``: same key, existence only.
- ``doGetTableIdentifiers``: prefix scan ``0x00 'p'``; the
  ``CachedDirectory`` parameter is ignored (function_engine
  precedent).
- ``doCreateTable``: **validate first, refuse loudly** — every column
  type must be codec-supported (BLOB refused with a named error), a
  PRIMARY KEY must exist (v1: refuse hidden-PK tables rather than
  invent a rowid; recorded as a possible later task), all index
  columns codec-supported. Then one transaction: read+bump ``0x00
  'c'``, write id mapping and proto, commit. A commit ``CONFLICT``
  (concurrent DDL) maps to a retryable error.
- ``doDropTable``: one transaction deleting proto + id mapping and —
  v1 — foreground prefix delete of data keys in batched chunks inside
  the same transaction if small, or successive transactions if large
  (chunk size a constant, noted for task 7 to obsolete).
- ``doRenameTable``: rewrite the two meta keys in one transaction;
  data untouched (keys carry only the table id).
- ``validateCreateTableOption``: nothing engine-specific accepted in
  v1 (refuse unknown options by returning false, the honest default).

Tests
-----

drizzle-test cases: create/show/drop/rename round trips; refusal
messages for BLOB columns, missing PK, unsupported types (result files
assert the specific error text); ``DATA_DICTIONARY.TABLES`` shows the
engine; restart persistence (create, restart server, table still
there) — the first end-to-end proof that state lives in the bucket
(``file://`` object store in CI).

Verification
------------

- Build green with ``--with-slatedb`` on and off (both switch states).
- drizzle-test green including the new cases, in the vouched pipeline
  using the composed builder image from task 1.