quiverdb 0.13.3 → 0.13.5

package/README.md

@@ -151,7 +151,7 @@ bun run example.ts
 - `readTimeSeriesFiles(collection)` -- Read the file paths (`null` for an unset column)
 - `updateTimeSeriesFiles(collection, data)` -- Write the file paths
 
-### Query
+### Query (read-only SQL)
 
 - `queryString(sql, parameters?)` -- Query returning string or null
 - `queryInteger(sql, parameters?)` -- Query returning integer or null
@@ -185,9 +185,12 @@ as an exact INTEGER, a `boolean` as the INTEGER 1 or 0).
 
 ### Introspection
 
-- `describe()` -- Whole-database text report (returns a string)
-- `describeCollection(collection)` -- One collection's structure (returns a string)
-- `summarizeCollection(collection)` -- Per-attribute null/value summary (returns a string)
+The describe methods give agents the schema, attribute meanings and data coverage as text reports.
+
+- `describe()` -- Database/version header followed by complete reports for every collection
+- `describeCollection(collection)` -- One collection's structure, UI metadata (including tooltips),
+  scalar null/value statistics and group coverage, returned as a string. Enum meanings appear
+  once in `enum {...}`; value histograms contain numeric codes and counts.
 - `isHealthy()` -- Check database health
 - `path()` -- Get database file path
 - `currentVersion()` -- Get current schema version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quiverdb",
-  "version": "0.13.3",
+  "version": "0.13.5",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/database.ts

@@ -302,7 +302,6 @@ export class Database {
   declare path: () => string;
   declare describe: () => string;
   declare describeCollection: (collection: string) => string;
-  declare summarizeCollection: (collection: string) => string;
 
   // --- Composite helpers (implemented in composites.ts) ---
   declare readScalarsById: (

package/src/introspection.ts

@@ -42,13 +42,3 @@ Database.prototype.describeCollection = function (this: Database, collection: st
   lib.quiver_database_free_string(readPtrOut(out));
   return result;
 };
-
-Database.prototype.summarizeCollection = function (this: Database, collection: string): string {
-  const lib = getSymbols();
-  const collBuf = toCString(collection);
-  const out = allocPtrOut();
-  check(lib.quiver_database_summarize_collection(this._handle, collBuf.buf, out.buf));
-  const result = decodeStringFromBuf(out);
-  lib.quiver_database_free_string(readPtrOut(out));
-  return result;
-};

package/src/loader.ts

@@ -128,7 +128,6 @@ const metadataSymbols = {
 
 const describeSymbols = {
   quiver_database_describe_collection: { args: [P, BUF, P], returns: I32 },
-  quiver_database_summarize_collection: { args: [P, BUF, P], returns: I32 },
 } as const;
 
 const timeSeriesSymbols = {

package/src/sandbox-api.ts

@@ -116,6 +116,13 @@ midnight.
   (subdirectories are fine; \`..\` escapes and outside absolute paths throw \`Cannot <op>: path '...' escapes the
   database directory ...\`). On an in-memory database these operations throw
   \`Cannot <op>: database is in-memory, file operations are unavailable\`.
+- **Raw SQL is read-only.** \`db:query_string\` / \`db:query_integer\` / \`db:query_float\` accept only
+  statements that read: a write (\`INSERT\`, \`UPDATE\`, \`DELETE\`, DDL), a \`PRAGMA\` statement,
+  \`ATTACH\`/\`DETACH\`, \`VACUUM\` or transaction control (\`BEGIN\`, \`COMMIT\`, \`ROLLBACK\`,
+  \`SAVEPOINT\`) throws \`Cannot query: SQL must be read-only; writes, PRAGMA, ATTACH, VACUUM and
+  transaction control are not allowed\` before anything runs. The table-valued \`pragma_*()\`
+  functions (\`SELECT name FROM pragma_table_info('X')\`) are reads and stay available. Write
+  through the \`db:\` API, which validates what it writes.
 - **What the sandbox does not limit.** The sandbox controls which files a script can touch and
   which standard libraries exist. It does not bound how much work a script does: there is no
   instruction-count limit, no memory cap and no wall-clock timeout (\`while true do end\` runs
@@ -181,14 +188,17 @@ db:is_healthy()                    -- boolean
 db:current_version()               -- integer (current migration version)
 db:path()                          -- string (database file path)
 db:number_of_elements(collection)  -- integer: how many elements the collection holds right now
-db:describe()                      -- string: whole-DB text report (returns it, does NOT print)
-db:describe_collection(collection) -- string: one collection's structure (text report)
-db:summarize_collection(collection)-- string: per-scalar null/non-null counts, low-cardinality
-                                   --         integer value distributions, per-group sizes
+db:describe()                      -- string: database/version header + complete reports for every collection
+db:describe_collection(collection) -- string: structure, UI metadata (including tooltips), scalar
+                                   --         null/non-null counts, integer distributions, group coverage
 db:validate_migrations(path)       -- validate a migrations dir (up then down) in-memory; no return
 \`\`\`
 
-All three \`describe*\`/\`summarize*\` methods **return** a string — \`print()\` it to see it.
+The \`describe*\` methods give agents the schema, attribute meanings and data coverage as text reports.
+Both **return** a string. Declarations and statistics share each line, with UI clauses between them.
+Enum meanings appear once in \`enum {...}\`;
+value histograms contain numeric codes and counts, only for non-primary-key INTEGER scalars with
+at most 64 distinct integer values. \`db:describe()\` queries statistics for every collection.
 
 \`db:validate_migrations(path)\` applies every \`up.sql\` in version order, then every \`down.sql\` in
 reverse, against a throwaway in-memory database — nothing in \`db\` itself is touched. The round trip
@@ -621,9 +631,10 @@ entirely.
 
 ---
 
-## Query (parameterized SQL)
+## Query (parameterized, read-only SQL)
 
-Positional \`?\` placeholders; \`params\` is an optional 1-indexed array. Each returns the first
+Only statements that read are accepted (see "Raw SQL is read-only" above); anything else throws
+before it runs. Positional \`?\` placeholders; \`params\` is an optional 1-indexed array. Each returns the first
 column of the first row, or \`nil\` when there is no row, the value is NULL, or it is not already
 the requested type. Only \`query_float\` converts (it widens an INTEGER), so
 \`db:query_string("SELECT COUNT(*) ...")\` and \`db:query_integer("SELECT AVG(x) ...")\` return
@@ -1021,6 +1032,7 @@ value of the wrong type throws.
 DateTime wrapper helpers (Lua uses ISO 8601 strings), boolean *reader* helpers (a stored flag reads
 back as \`0\`/\`1\` — writing a boolean is supported), \`_by_id\` single-scalar variants (use the
 composite by-id readers or the bulk readers instead), and the row-aligned whole-group readers the
-other bindings have (hence the row-count caveat under composite by-id reads). Everything else
-the native binding exposes — CRUD, reads, time series, metadata, query, CSV, and the
-binary/expression subsystems — is documented above and callable.`;
+other bindings have (hence the row-count caveat under composite by-id reads). Raw SQL that writes,
+sets a \`PRAGMA\`, attaches a database, vacuums or controls a transaction (\`query_*\` is read-only
+in every binding). Everything else the native binding exposes — CRUD, reads, time series,
+metadata, query, CSV, and the binary/expression subsystems — is documented above and callable.`;