Add declarative TableSpec API with preload and fail-fast; fix shared-connection race

src/sqlmem/executor.py

@@ -42,6 +42,20 @@ class QueryExecutor:
             self._ensure_table(table, parsed)
         return self._run_in_memory(parsed)
 
+    def ensure_loaded(self, table: str, columns: list[str] | None) -> None:
+        """Preload *table* into the cache without running a query.
+
+        ``columns=None`` loads the whole table (``SELECT *`` semantics); otherwise
+        only the listed columns. Reuses the same load path as a real query — delta
+        key/change + index columns are augmented, the registry and watermark are
+        updated, and double-checked locking skips a copy already fresh in the
+        cache — but never materializes any rows (unlike :meth:`execute`).
+        """
+        if columns is None:
+            self._ensure_full(table)
+        else:
+            self._ensure_columns(table, columns)
+
     def _ensure_table(self, table: str, parsed: ParsedQuery) -> None:
         if table in parsed.wildcard_tables:
             self._ensure_full(table)