@venn-lang/db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# @venn-lang/db
+
+> The `db` namespace: seed tables, run statements and snapshot state, all through the `DbClient` port.
+
+A flow that talks to a database needs the rows to be there before the first assertion and gone
+after the last. This package gives six verbs for that, and puts every one of them behind a typed
+port so the same flow runs against in-memory tables or a real connection without a line changing.
+
+## Install
+
+The package is part of the stdlib the `venn` CLI loads, so nothing to install. Reach it from a
+flow with a `use` line:
+
+```ruby
+use "venn/db"
+```
+
+The plugin declares the `net` capability. A host that does not offer it fails the load with a
+readable diagnostic rather than a `TypeError` mid-run.
+
+## Usage
+
+```ruby
+module demo.orders
+
+use "venn/assert"
+use "venn/db"
+
+flow "Orders survive a snapshot" {
+  step "seed the tables" {
+    const loaded = db.seed { users: [{ id: 1, name: "Ada" }, { id: 2, name: "Grace" }] }
+    expect loaded == 2
+  }
+
+  step "query them back" {
+    const rows = db.query "SELECT * FROM users"
+    expect rows.len == 2
+
+    const grace = db.query "SELECT * FROM users" { where: { id: 2 } }
+    expect grace[0].name == "Grace"
+  }
+
+  step "a snapshot undoes a mutation" {
+    const before = db.snapshot
+    const cleared = db.exec "TRUNCATE users"
+    expect cleared == 2
+
+    db.restore before
+    const rows = db.query "SELECT * FROM users"
+    expect rows.len == 2
+  }
+}
+```
+
+## Verbs
+
+| Verb | Options | Gives back |
+| --- | --- | --- |
+| `db.connect url` | none | The URL it connected to, as a string. |
+| `db.query sql` | `where` (a row of column to value) | `list<db.Row>`, the matching rows. |
+| `db.exec sql` | `rows` (the rows an INSERT carries) | `number`, how many rows were affected. |
+| `db.seed tables` | none | `number`, how many rows were loaded. |
+| `db.snapshot` | none | `db.Tables`, a copy of the current state. |
+| `db.restore snapshot` | none | nothing. |
+
+The statement is always the positional argument; everything else is an option in the trailing
+map. `db.seed` accepts the tables either positionally or written inline as options, so
+`db.seed { users: [...] }` and `db.seed baseline` both work.
+
+Two named types are published: `db.Row` (a map of column name to value) and `db.Tables` (rows
+grouped by table name, which is what `db.seed` takes and `db.snapshot` gives back).
+
+## The DbClient port
+
+`venn.port.db-client`, contract version 1, requires `net`, six methods: `connect`, `query`,
+`exec`, `seed`, `snapshot`, `restore`. Actions reach it with `ctx.port(DbClientPort)`, so nothing
+in this package imports a driver.
+
+Two implementations ship, and both answer the same conformance suite:
+
+| Implementation | Behaviour |
+| --- | --- |
+| `createFakeDbClient({ tables })` | In-memory tables. Deterministic, offline, seedable. This is what the stdlib binds by default. |
+| `createRealDbClient()` | A stub in this build. Every method throws a `VennError` with code `VN8090` rather than failing quietly. |
+
+The fake carries a deliberately small query engine: `query` reads the table named after `FROM`
+and filters by equality on each key of `where`; `exec` appends `rows` for `INSERT INTO` and clears
+the table for `TRUNCATE` or `DELETE FROM`, returning the affected count. `snapshot` does a
+structural clone, so restoring never aliases live state.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `dbPlugin` (also the default export) | The `PluginDefinition` for the `db` namespace. |
+| `DbClientPort` | The port descriptor. |
+| `DbClient` | The interface an implementation satisfies. |
+| `createFakeDbClient`, `createRealDbClient` | The two implementations. |
+| `QueryArgs`, `ExecArgs` | The argument objects `query` and `exec` take. |
+| `TableMap`, `SeedData`, `DbSnapshot` | Rows keyed by table name. The last two are aliases of the first, named for where they are used. |
+| `Row`, `RowSchema` | The nominal row type and its Zod schema. |
+| `dbTypeDefs` | The `db.Row` and `db.Tables` specs the checker and the editor read. |
+
+## Adding an implementation
+
+Write the file, add one line to `src/clients/index.ts`, and add one line to
+`src/clients/db-client.test.ts` calling `dbClientConformance` with it. The suite is not rewritten;
+if the new client passes it, the verbs above already work against it.
+
+## See also
+
+- [`@venn-lang/data`](../std-data) for the deterministic rows to seed with.
+- [`@venn-lang/contracts`](../contracts) for `Port`, `Host` and capability negotiation.
+- [`@venn-lang/stdlib`](../stdlib) for the list of plugins and the port bindings the CLI runs with.

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { Port } from "@venn-lang/contracts";
+import { PluginDefinition, ZodType } from "@venn-lang/sdk";
+import { TypeSpec } from "@venn-lang/types";
+//#region src/types/row.d.ts
+/** The nominal `Row` type: an opaque record of column values. */
+type Row = Record<string, unknown>;
+/** Zod schema for the nominal `Row` type the plugin contributes. */
+declare const RowSchema: ZodType<Row>;
+//#endregion
+//#region src/types/type-defs.d.ts
+/**
+ * The named types `@venn-lang/db` publishes to scripts, keyed by their bare name.
+ *
+ * Hand-mirrored from `port/db-client.types.ts` (`Row` and `TableMap`, which
+ * `SeedData` and `DbSnapshot` both alias): the two must agree, so change them together.
+ */
+declare const dbTypeDefs: Readonly<Record<string, TypeSpec>>;
+//#endregion
+//#region src/port/db-client.types.d.ts
+/** Arguments for {@link DbClient.query}: a SQL string plus an optional filter. */
+interface QueryArgs {
+  sql: string;
+  where?: Row;
+}
+/** Arguments for {@link DbClient.exec}: a mutating statement plus optional rows. */
+interface ExecArgs {
+  sql: string;
+  rows?: Row[];
+}
+/** Rows keyed by table name. The shape seeds and snapshots share. */
+type TableMap = Record<string, Row[]>;
+/** Rows to load, keyed by table name. */
+type SeedData = TableMap;
+/** A captured copy of every table. Detached from live state, so it can be restored later. */
+type DbSnapshot = TableMap;
+/**
+ * The contract a database is reached through. Actions call it via
+ * `ctx.port(DbClientPort)` and never touch a driver directly.
+ */
+interface DbClient {
+  connect(url: string): Promise<void>;
+  query(args: QueryArgs): Promise<Row[]>;
+  exec(args: ExecArgs): Promise<number>;
+  seed(data: SeedData): Promise<number>;
+  snapshot(): Promise<DbSnapshot>;
+  restore(snapshot: DbSnapshot): Promise<void>;
+}
+//#endregion
+//#region src/port/db-client.port.d.ts
+/**
+ * The port every `db` verb reaches the database through.
+ *
+ * Bound by the host to `createFakeDbClient` or `createRealDbClient`. Requires
+ * the `net` capability, so a host without it is refused at load time rather
+ * than failing mid-run.
+ */
+declare const DbClientPort: Port<DbClient>;
+//#endregion
+//#region src/clients/fake-client.d.ts
+/**
+ * The in-memory `DbClient`: deterministic tables, no connection, no I/O.
+ *
+ * @param args.tables Rows to start from. Copied, so the caller's object is never mutated.
+ */
+declare function createFakeDbClient(args?: {
+  tables?: SeedData;
+}): DbClient;
+//#endregion
+//#region src/clients/real-client.d.ts
+/**
+ * The driver-backed `DbClient`. Not implemented in this build.
+ *
+ * @throws VennError `VN8090` from every method, so a host that binds it fails
+ * loudly instead of quietly answering with nothing.
+ */
+declare function createRealDbClient(): DbClient;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `db` plugin: connect, query, exec, seed, snapshot and restore.
+ *
+ * Every verb reaches the database through `DbClientPort`, so the host decides
+ * whether that is the fake or a real driver. Loading fails up front unless the
+ * host offers the `net` capability.
+ */
+declare const dbPlugin: PluginDefinition;
+//#endregion
+export { type DbClient, DbClientPort, type DbSnapshot, type ExecArgs, type QueryArgs, type Row, RowSchema, type SeedData, type TableMap, createFakeDbClient, createRealDbClient, dbPlugin, dbPlugin as default, dbTypeDefs };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types/row.ts","../src/types/type-defs.ts","../src/port/db-client.types.ts","../src/port/db-client.port.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/plugin.ts"],"mappings":";;;;;KAGY,MAAM;;cAGL,WAAW,QAAQ;;;;;;;;;cCEnB,YAAY,SAAS,eAAe;;;;UCLhC;EACf;EACA,QAAQ;;;UAIO;EACf;EACA,OAAO;;;KAIG,WAAW,eAAe;;KAG1B,WAAW;;KAGX,aAAa;;;;;UAMR;EACf,QAAQ,cAAc;EACtB,MAAM,MAAM,YAAY,QAAQ;EAChC,KAAK,MAAM,WAAW;EACtB,KAAK,MAAM,WAAW;EACtB,YAAY,QAAQ;EACpB,QAAQ,UAAU,aAAa;;;;;;;;;;;cCvBpB,cAAc,KAAK;;;;;;;;iBCEhB,mBAAmB;EAAQ,SAAS;IAAkB;;;;;;;;;iBCHtD,sBAAsB;;;;;;;;;;cCEzB,UAAU"}

package/dist/index.js

@@ -0,0 +1,238 @@
+import { VennError } from "@venn-lang/contracts";
+import { arg, defineAction, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/clients/query-engine.ts
+/** Deep copy of the tables. A snapshot that aliased live state would follow later edits. */
+function cloneTables(tables) {
+	return structuredClone(tables);
+}
+/** A tiny SELECT: pick the table named after `FROM`, optionally filter by `where`. */
+function selectRows(tables, query) {
+	const rows = tables[tableName(query.sql, /from\s+([a-z_]\w*)/i)] ?? [];
+	const where = query.where;
+	return (where ? rows.filter((row) => matchesWhere(row, where)) : rows).map((row) => ({ ...row }));
+}
+/** A tiny mutation: INSERT appends rows; TRUNCATE/DELETE clears. Returns the count. */
+function execStatement(tables, statement) {
+	const inserted = tableName(statement.sql, /insert\s+into\s+([a-z_]\w*)/i);
+	if (inserted) return insertRows(tables, inserted, statement.rows ?? []);
+	return truncate(tables, tableName(statement.sql, /(?:truncate|delete\s+from)\s+([a-z_]\w*)/i));
+}
+/** Append rows into named tables; returns how many rows were loaded. */
+function seedTables(tables, data) {
+	let count = 0;
+	for (const [name, rows] of Object.entries(data)) {
+		const copies = rows.map((row) => ({ ...row }));
+		tables[name] = [...tables[name] ?? [], ...copies];
+		count += copies.length;
+	}
+	return count;
+}
+function insertRows(tables, name, rows) {
+	const copies = rows.map((row) => ({ ...row }));
+	tables[name] = [...tables[name] ?? [], ...copies];
+	return copies.length;
+}
+function truncate(tables, name) {
+	const removed = tables[name]?.length ?? 0;
+	if (name) tables[name] = [];
+	return removed;
+}
+function matchesWhere(row, where) {
+	return Object.entries(where).every(([key, value]) => row[key] === value);
+}
+function tableName(sql, pattern) {
+	return pattern.exec(sql)?.[1] ?? "";
+}
+//#endregion
+//#region src/clients/fake-client.ts
+/**
+* The in-memory `DbClient`: deterministic tables, no connection, no I/O.
+*
+* @param args.tables Rows to start from. Copied, so the caller's object is never mutated.
+*/
+function createFakeDbClient(args = {}) {
+	const state = { tables: cloneTables(args.tables ?? {}) };
+	return {
+		connect: () => Promise.resolve(),
+		query: (query) => Promise.resolve(selectRows(state.tables, query)),
+		exec: (statement) => Promise.resolve(execStatement(state.tables, statement)),
+		seed: (data) => Promise.resolve(seedTables(state.tables, data)),
+		snapshot: () => Promise.resolve(cloneTables(state.tables)),
+		restore: (snapshot) => restore(state, snapshot)
+	};
+}
+function restore(state, snapshot) {
+	state.tables = cloneTables(snapshot);
+	return Promise.resolve();
+}
+//#endregion
+//#region src/clients/real-client.ts
+/**
+* The driver-backed `DbClient`. Not implemented in this build.
+*
+* @throws VennError `VN8090` from every method, so a host that binds it fails
+* loudly instead of quietly answering with nothing.
+*/
+function createRealDbClient() {
+	return {
+		connect: () => notImplemented(),
+		query: () => notImplemented(),
+		exec: () => notImplemented(),
+		seed: () => notImplemented(),
+		snapshot: () => notImplemented(),
+		restore: () => notImplemented()
+	};
+}
+function notImplemented() {
+	throw new VennError({
+		code: "VN8090",
+		message: "Db real client not implemented in this build"
+	});
+}
+//#endregion
+//#region src/port/db-client.port.ts
+/**
+* The port every `db` verb reaches the database through.
+*
+* Bound by the host to `createFakeDbClient` or `createRealDbClient`. Requires
+* the `net` capability, so a host without it is refused at load time rather
+* than failing mid-run.
+*/
+const DbClientPort = {
+	id: "venn.port.db-client",
+	version: 1,
+	requires: ["net"],
+	methods: [
+		"connect",
+		"query",
+		"exec",
+		"seed",
+		"snapshot",
+		"restore"
+	]
+};
+//#endregion
+//#region src/actions/connect.ts
+/** `db.connect(url)`: open the connection the other `db` verbs then use. */
+const connectAction = defineAction({
+	name: "connect",
+	doc: "Connect to a database by URL.",
+	args: [arg("url", t.string, "Where the database is.")],
+	result: t.string,
+	run: async (ctx, input) => {
+		const url = String(input.args[0] ?? "");
+		await ctx.port(DbClientPort).connect(url);
+		return url;
+	}
+});
+//#endregion
+//#region src/types/row.ts
+/** Zod schema for the nominal `Row` type the plugin contributes. */
+const RowSchema = z.record(z.string(), z.unknown());
+//#endregion
+//#region src/types/type-defs.ts
+/**
+* The named types `@venn-lang/db` publishes to scripts, keyed by their bare name.
+*
+* Hand-mirrored from `port/db-client.types.ts` (`Row` and `TableMap`, which
+* `SeedData` and `DbSnapshot` both alias): the two must agree, so change them together.
+*/
+const dbTypeDefs = {
+	/**
+	* One row. Which columns it has is the query's business, not the plugin's, so
+	* the type says only what is always true: names to values.
+	*/
+	Row: t.map(t.dynamic),
+	/** Rows grouped by table name. What `db.seed` takes and `db.snapshot` gives back. */
+	Tables: t.map(t.list(t.ref("db.Row")))
+};
+/** `db.exec("TRUNCATE …", { rows })`: mutate the tables and answer with the affected count. */
+const execAction = defineAction({
+	name: "exec",
+	doc: "Execute a mutating statement (TRUNCATE/DELETE/INSERT); returns the affected count.",
+	params: z.object({ rows: z.array(RowSchema).optional() }),
+	args: [arg("sql", t.string, "The statement to run. Placeholders go in the options.")],
+	result: t.number,
+	run: (ctx, input) => ctx.port(DbClientPort).exec({
+		sql: String(input.args[0] ?? ""),
+		rows: input.params.rows
+	})
+});
+/** `db.query("SELECT …", { where })`: run a SELECT and answer with the matching rows. */
+const queryAction = defineAction({
+	name: "query",
+	doc: "Run a SELECT and return the matching rows.",
+	params: z.object({ where: RowSchema.optional() }),
+	args: [arg("sql", t.string, "The statement to run. Placeholders go in the options.")],
+	result: t.list(t.ref("db.Row")),
+	run: (ctx, input) => ctx.port(DbClientPort).query({
+		sql: String(input.args[0] ?? ""),
+		where: input.params.where
+	})
+});
+//#endregion
+//#region src/actions/restore.ts
+/** `db.restore(snapshot)`: put the tables back as `db.snapshot` found them. */
+const restoreAction = defineAction({
+	name: "restore",
+	doc: "Restore a previously captured snapshot.",
+	args: [arg("snapshot", t.ref("db.Tables"), "What `db.snapshot` gave back.")],
+	result: t.void,
+	run: (ctx, input) => ctx.port(DbClientPort).restore(input.args[0])
+});
+//#endregion
+//#region src/actions/seed.ts
+/** `db.seed(data)`: load rows into the tables and answer with how many were loaded. */
+const seedAction = defineAction({
+	name: "seed",
+	doc: "Load rows into the in-memory tables, grouped by table name.",
+	args: [arg("tables", t.ref("db.Tables"), "Rows to load, grouped by table name.")],
+	result: t.number,
+	run: (ctx, input) => ctx.port(DbClientPort).seed(readSeedData(input))
+});
+/**
+* Read the tables from either call shape.
+*
+* `db.seed baseline` passes them positionally. Written inline, `db.seed { … }`
+* puts them in the options map instead, and no signature parameter names those.
+*/
+function readSeedData(input) {
+	const positional = input.args[0];
+	if (positional && typeof positional === "object") return positional;
+	return input.params ?? {};
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* The `db` plugin: connect, query, exec, seed, snapshot and restore.
+*
+* Every verb reaches the database through `DbClientPort`, so the host decides
+* whether that is the fake or a real driver. Loading fails up front unless the
+* host offers the `net` capability.
+*/
+const dbPlugin = definePlugin({
+	name: "venn/db",
+	version: "0.0.0",
+	namespace: "db",
+	requires: ["net"],
+	actions: [
+		connectAction,
+		queryAction,
+		execAction,
+		seedAction,
+		defineAction({
+			name: "snapshot",
+			doc: "Capture the current in-memory state as a restorable snapshot.",
+			result: t.ref("db.Tables"),
+			run: (ctx) => ctx.port(DbClientPort).snapshot()
+		}),
+		restoreAction
+	],
+	types: { Row: RowSchema },
+	typeDefs: dbTypeDefs
+});
+//#endregion
+export { DbClientPort, RowSchema, createFakeDbClient, createRealDbClient, dbPlugin, dbPlugin as default, dbTypeDefs };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/clients/query-engine.ts","../src/clients/fake-client.ts","../src/clients/real-client.ts","../src/port/db-client.port.ts","../src/actions/connect.ts","../src/types/row.ts","../src/types/type-defs.ts","../src/actions/exec.ts","../src/actions/query.ts","../src/actions/restore.ts","../src/actions/seed.ts","../src/actions/snapshot.ts","../src/actions/index.ts","../src/plugin.ts"],"sourcesContent":["import type { ExecArgs, QueryArgs, SeedData, TableMap } from \"../port/index.js\";\nimport type { Row } from \"../types/index.js\";\n\n// A deliberately small SQL reader for the fake: it recognises the table name and\n// little else. Enough to make a seeded test read like the real thing.\n\n/** Deep copy of the tables. A snapshot that aliased live state would follow later edits. */\nexport function cloneTables(tables: TableMap): TableMap {\n  return structuredClone(tables);\n}\n\n/** A tiny SELECT: pick the table named after `FROM`, optionally filter by `where`. */\nexport function selectRows(tables: TableMap, query: QueryArgs): Row[] {\n  const rows = tables[tableName(query.sql, /from\\s+([a-z_]\\w*)/i)] ?? [];\n  const where = query.where;\n  const matched = where ? rows.filter((row) => matchesWhere(row, where)) : rows;\n  return matched.map((row) => ({ ...row }));\n}\n\n/** A tiny mutation: INSERT appends rows; TRUNCATE/DELETE clears. Returns the count. */\nexport function execStatement(tables: TableMap, statement: ExecArgs): number {\n  const inserted = tableName(statement.sql, /insert\\s+into\\s+([a-z_]\\w*)/i);\n  if (inserted) return insertRows(tables, inserted, statement.rows ?? []);\n  return truncate(tables, tableName(statement.sql, /(?:truncate|delete\\s+from)\\s+([a-z_]\\w*)/i));\n}\n\n/** Append rows into named tables; returns how many rows were loaded. */\nexport function seedTables(tables: TableMap, data: SeedData): number {\n  let count = 0;\n  for (const [name, rows] of Object.entries(data)) {\n    const copies = rows.map((row) => ({ ...row }));\n    tables[name] = [...(tables[name] ?? []), ...copies];\n    count += copies.length;\n  }\n  return count;\n}\n\nfunction insertRows(tables: TableMap, name: string, rows: Row[]): number {\n  const copies = rows.map((row) => ({ ...row }));\n  tables[name] = [...(tables[name] ?? []), ...copies];\n  return copies.length;\n}\n\nfunction truncate(tables: TableMap, name: string): number {\n  const removed = tables[name]?.length ?? 0;\n  if (name) tables[name] = [];\n  return removed;\n}\n\nfunction matchesWhere(row: Row, where: Row): boolean {\n  return Object.entries(where).every(([key, value]) => row[key] === value);\n}\n\nfunction tableName(sql: string, pattern: RegExp): string {\n  return pattern.exec(sql)?.[1] ?? \"\";\n}\n","import type { DbClient, DbSnapshot, SeedData, TableMap } from \"../port/index.js\";\nimport { cloneTables, execStatement, seedTables, selectRows } from \"./query-engine.js\";\n\ninterface DbState {\n  tables: TableMap;\n}\n\n/**\n * The in-memory `DbClient`: deterministic tables, no connection, no I/O.\n *\n * @param args.tables Rows to start from. Copied, so the caller's object is never mutated.\n */\nexport function createFakeDbClient(args: { tables?: SeedData } = {}): DbClient {\n  const state: DbState = { tables: cloneTables(args.tables ?? {}) };\n  return {\n    connect: () => Promise.resolve(),\n    query: (query) => Promise.resolve(selectRows(state.tables, query)),\n    exec: (statement) => Promise.resolve(execStatement(state.tables, statement)),\n    seed: (data) => Promise.resolve(seedTables(state.tables, data)),\n    snapshot: () => Promise.resolve(cloneTables(state.tables)),\n    restore: (snapshot) => restore(state, snapshot),\n  };\n}\n\nfunction restore(state: DbState, snapshot: DbSnapshot): Promise<void> {\n  state.tables = cloneTables(snapshot);\n  return Promise.resolve();\n}\n","import { VennError } from \"@venn-lang/contracts\";\nimport type { DbClient } from \"../port/index.js\";\n\n/**\n * The driver-backed `DbClient`. Not implemented in this build.\n *\n * @throws VennError `VN8090` from every method, so a host that binds it fails\n * loudly instead of quietly answering with nothing.\n */\nexport function createRealDbClient(): DbClient {\n  return {\n    connect: () => notImplemented(),\n    query: () => notImplemented(),\n    exec: () => notImplemented(),\n    seed: () => notImplemented(),\n    snapshot: () => notImplemented(),\n    restore: () => notImplemented(),\n  };\n}\n\nfunction notImplemented(): never {\n  throw new VennError({\n    code: \"VN8090\",\n    message: \"Db real client not implemented in this build\",\n  });\n}\n","import type { Port } from \"@venn-lang/contracts\";\nimport type { DbClient } from \"./db-client.types.js\";\n\n/**\n * The port every `db` verb reaches the database through.\n *\n * Bound by the host to `createFakeDbClient` or `createRealDbClient`. Requires\n * the `net` capability, so a host without it is refused at load time rather\n * than failing mid-run.\n */\nexport const DbClientPort: Port<DbClient> = {\n  id: \"venn.port.db-client\",\n  version: 1,\n  requires: [\"net\"],\n  methods: [\"connect\", \"query\", \"exec\", \"seed\", \"snapshot\", \"restore\"],\n};\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort } from \"../port/index.js\";\n\n/** `db.connect(url)`: open the connection the other `db` verbs then use. */\nexport const connectAction: ActionDefinition = defineAction({\n  name: \"connect\",\n  doc: \"Connect to a database by URL.\",\n  // It answers with the URL, not a handle: the connection lives behind the port,\n  // and every other verb reaches it from there.\n  args: [arg(\"url\", t.string, \"Where the database is.\")],\n  result: t.string,\n  run: async (ctx, input) => {\n    const url = String(input.args[0] ?? \"\");\n    await ctx.port(DbClientPort).connect(url);\n    return url;\n  },\n});\n","import { type ZodType, z } from \"@venn-lang/sdk\";\n\n/** The nominal `Row` type: an opaque record of column values. */\nexport type Row = Record<string, unknown>;\n\n/** Zod schema for the nominal `Row` type the plugin contributes. */\nexport const RowSchema: ZodType<Row> = z.record(z.string(), z.unknown());\n","import { type TypeSpec, t } from \"@venn-lang/types\";\n\n/**\n * The named types `@venn-lang/db` publishes to scripts, keyed by their bare name.\n *\n * Hand-mirrored from `port/db-client.types.ts` (`Row` and `TableMap`, which\n * `SeedData` and `DbSnapshot` both alias): the two must agree, so change them together.\n */\nexport const dbTypeDefs: Readonly<Record<string, TypeSpec>> = {\n  /**\n   * One row. Which columns it has is the query's business, not the plugin's, so\n   * the type says only what is always true: names to values.\n   */\n  Row: t.map(t.dynamic),\n  /** Rows grouped by table name. What `db.seed` takes and `db.snapshot` gives back. */\n  Tables: t.map(t.list(t.ref(\"db.Row\"))),\n};\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort } from \"../port/index.js\";\nimport { RowSchema } from \"../types/index.js\";\n\nconst execParams = z.object({ rows: z.array(RowSchema).optional() });\n\n/** `db.exec(\"TRUNCATE …\", { rows })`: mutate the tables and answer with the affected count. */\nexport const execAction: ActionDefinition = defineAction({\n  name: \"exec\",\n  doc: \"Execute a mutating statement (TRUNCATE/DELETE/INSERT); returns the affected count.\",\n  params: execParams,\n  args: [arg(\"sql\", t.string, \"The statement to run. Placeholders go in the options.\")],\n  result: t.number,\n  run: (ctx, input) =>\n    ctx.port(DbClientPort).exec({ sql: String(input.args[0] ?? \"\"), rows: input.params.rows }),\n});\n","import { type ActionDefinition, arg, defineAction, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort } from \"../port/index.js\";\nimport { RowSchema } from \"../types/index.js\";\n\nconst queryParams = z.object({ where: RowSchema.optional() });\n\n/** `db.query(\"SELECT …\", { where })`: run a SELECT and answer with the matching rows. */\nexport const queryAction: ActionDefinition = defineAction({\n  name: \"query\",\n  doc: \"Run a SELECT and return the matching rows.\",\n  params: queryParams,\n  args: [arg(\"sql\", t.string, \"The statement to run. Placeholders go in the options.\")],\n  result: t.list(t.ref(\"db.Row\")),\n  run: (ctx, input) =>\n    ctx.port(DbClientPort).query({ sql: String(input.args[0] ?? \"\"), where: input.params.where }),\n});\n","import { type ActionDefinition, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort, type DbSnapshot } from \"../port/index.js\";\n\n/** `db.restore(snapshot)`: put the tables back as `db.snapshot` found them. */\nexport const restoreAction: ActionDefinition = defineAction({\n  name: \"restore\",\n  doc: \"Restore a previously captured snapshot.\",\n  args: [arg(\"snapshot\", t.ref(\"db.Tables\"), \"What `db.snapshot` gave back.\")],\n  result: t.void,\n  run: (ctx, input) => ctx.port(DbClientPort).restore(input.args[0] as DbSnapshot),\n});\n","import { type ActionDefinition, type ActionInput, arg, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort, type SeedData } from \"../port/index.js\";\n\n/** `db.seed(data)`: load rows into the tables and answer with how many were loaded. */\nexport const seedAction: ActionDefinition = defineAction({\n  name: \"seed\",\n  doc: \"Load rows into the in-memory tables, grouped by table name.\",\n  args: [arg(\"tables\", t.ref(\"db.Tables\"), \"Rows to load, grouped by table name.\")],\n  result: t.number,\n  run: (ctx, input) => ctx.port(DbClientPort).seed(readSeedData(input)),\n});\n\n/**\n * Read the tables from either call shape.\n *\n * `db.seed baseline` passes them positionally. Written inline, `db.seed { … }`\n * puts them in the options map instead, and no signature parameter names those.\n */\nfunction readSeedData(input: ActionInput<unknown>): SeedData {\n  const positional = input.args[0];\n  if (positional && typeof positional === \"object\") return positional as SeedData;\n  return (input.params ?? {}) as SeedData;\n}\n","import { type ActionDefinition, defineAction } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { DbClientPort } from \"../port/index.js\";\n\n/** `db.snapshot()`: copy the current tables into a value `db.restore` accepts. */\nexport const snapshotAction: ActionDefinition = defineAction({\n  name: \"snapshot\",\n  doc: \"Capture the current in-memory state as a restorable snapshot.\",\n  // `db.Tables`, not `DbSnapshot`: that alias lives in the port's TypeScript, and\n  // a script can only name what the plugin publishes.\n  result: t.ref(\"db.Tables\"),\n  run: (ctx) => ctx.port(DbClientPort).snapshot(),\n});\n","import type { ActionDefinition } from \"@venn-lang/sdk\";\nimport { connectAction } from \"./connect.js\";\nimport { execAction } from \"./exec.js\";\nimport { queryAction } from \"./query.js\";\nimport { restoreAction } from \"./restore.js\";\nimport { seedAction } from \"./seed.js\";\nimport { snapshotAction } from \"./snapshot.js\";\n\n/** The db namespace's verbs. Adding one is a single line here. */\nexport const dbActions: ActionDefinition[] = [\n  connectAction,\n  queryAction,\n  execAction,\n  seedAction,\n  snapshotAction,\n  restoreAction,\n];\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { dbActions } from \"./actions/index.js\";\nimport { dbTypeDefs, RowSchema } from \"./types/index.js\";\n\n/**\n * The `db` plugin: connect, query, exec, seed, snapshot and restore.\n *\n * Every verb reaches the database through `DbClientPort`, so the host decides\n * whether that is the fake or a real driver. Loading fails up front unless the\n * host offers the `net` capability.\n */\nexport const dbPlugin: PluginDefinition = definePlugin({\n  name: \"venn/db\",\n  version: \"0.0.0\",\n  namespace: \"db\",\n  requires: [\"net\"],\n  actions: dbActions,\n  types: { Row: RowSchema },\n  typeDefs: dbTypeDefs,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@venn-lang/db",
+  "version": "0.1.0",
+  "description": "The db namespace: seed tables, run statements and snapshot state, all through the DbClient port.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "db"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-db#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-db"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/contracts": "0.1.0",
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/connect.ts

@@ -0,0 +1,18 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort } from "../port/index.js";
+
+/** `db.connect(url)`: open the connection the other `db` verbs then use. */
+export const connectAction: ActionDefinition = defineAction({
+  name: "connect",
+  doc: "Connect to a database by URL.",
+  // It answers with the URL, not a handle: the connection lives behind the port,
+  // and every other verb reaches it from there.
+  args: [arg("url", t.string, "Where the database is.")],
+  result: t.string,
+  run: async (ctx, input) => {
+    const url = String(input.args[0] ?? "");
+    await ctx.port(DbClientPort).connect(url);
+    return url;
+  },
+});

package/src/actions/exec.ts

@@ -0,0 +1,17 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort } from "../port/index.js";
+import { RowSchema } from "../types/index.js";
+
+const execParams = z.object({ rows: z.array(RowSchema).optional() });
+
+/** `db.exec("TRUNCATE …", { rows })`: mutate the tables and answer with the affected count. */
+export const execAction: ActionDefinition = defineAction({
+  name: "exec",
+  doc: "Execute a mutating statement (TRUNCATE/DELETE/INSERT); returns the affected count.",
+  params: execParams,
+  args: [arg("sql", t.string, "The statement to run. Placeholders go in the options.")],
+  result: t.number,
+  run: (ctx, input) =>
+    ctx.port(DbClientPort).exec({ sql: String(input.args[0] ?? ""), rows: input.params.rows }),
+});

package/src/actions/index.ts

@@ -0,0 +1,17 @@
+import type { ActionDefinition } from "@venn-lang/sdk";
+import { connectAction } from "./connect.js";
+import { execAction } from "./exec.js";
+import { queryAction } from "./query.js";
+import { restoreAction } from "./restore.js";
+import { seedAction } from "./seed.js";
+import { snapshotAction } from "./snapshot.js";
+
+/** The db namespace's verbs. Adding one is a single line here. */
+export const dbActions: ActionDefinition[] = [
+  connectAction,
+  queryAction,
+  execAction,
+  seedAction,
+  snapshotAction,
+  restoreAction,
+];

package/src/actions/query.ts

@@ -0,0 +1,17 @@
+import { type ActionDefinition, arg, defineAction, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort } from "../port/index.js";
+import { RowSchema } from "../types/index.js";
+
+const queryParams = z.object({ where: RowSchema.optional() });
+
+/** `db.query("SELECT …", { where })`: run a SELECT and answer with the matching rows. */
+export const queryAction: ActionDefinition = defineAction({
+  name: "query",
+  doc: "Run a SELECT and return the matching rows.",
+  params: queryParams,
+  args: [arg("sql", t.string, "The statement to run. Placeholders go in the options.")],
+  result: t.list(t.ref("db.Row")),
+  run: (ctx, input) =>
+    ctx.port(DbClientPort).query({ sql: String(input.args[0] ?? ""), where: input.params.where }),
+});

package/src/actions/restore.ts

@@ -0,0 +1,12 @@
+import { type ActionDefinition, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort, type DbSnapshot } from "../port/index.js";
+
+/** `db.restore(snapshot)`: put the tables back as `db.snapshot` found them. */
+export const restoreAction: ActionDefinition = defineAction({
+  name: "restore",
+  doc: "Restore a previously captured snapshot.",
+  args: [arg("snapshot", t.ref("db.Tables"), "What `db.snapshot` gave back.")],
+  result: t.void,
+  run: (ctx, input) => ctx.port(DbClientPort).restore(input.args[0] as DbSnapshot),
+});

package/src/actions/seed.ts

@@ -0,0 +1,24 @@
+import { type ActionDefinition, type ActionInput, arg, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort, type SeedData } from "../port/index.js";
+
+/** `db.seed(data)`: load rows into the tables and answer with how many were loaded. */
+export const seedAction: ActionDefinition = defineAction({
+  name: "seed",
+  doc: "Load rows into the in-memory tables, grouped by table name.",
+  args: [arg("tables", t.ref("db.Tables"), "Rows to load, grouped by table name.")],
+  result: t.number,
+  run: (ctx, input) => ctx.port(DbClientPort).seed(readSeedData(input)),
+});
+
+/**
+ * Read the tables from either call shape.
+ *
+ * `db.seed baseline` passes them positionally. Written inline, `db.seed { … }`
+ * puts them in the options map instead, and no signature parameter names those.
+ */
+function readSeedData(input: ActionInput<unknown>): SeedData {
+  const positional = input.args[0];
+  if (positional && typeof positional === "object") return positional as SeedData;
+  return (input.params ?? {}) as SeedData;
+}

package/src/actions/snapshot.ts

@@ -0,0 +1,13 @@
+import { type ActionDefinition, defineAction } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { DbClientPort } from "../port/index.js";
+
+/** `db.snapshot()`: copy the current tables into a value `db.restore` accepts. */
+export const snapshotAction: ActionDefinition = defineAction({
+  name: "snapshot",
+  doc: "Capture the current in-memory state as a restorable snapshot.",
+  // `db.Tables`, not `DbSnapshot`: that alias lives in the port's TypeScript, and
+  // a script can only name what the plugin publishes.
+  result: t.ref("db.Tables"),
+  run: (ctx) => ctx.port(DbClientPort).snapshot(),
+});

package/src/clients/fake-client.ts

@@ -0,0 +1,28 @@
+import type { DbClient, DbSnapshot, SeedData, TableMap } from "../port/index.js";
+import { cloneTables, execStatement, seedTables, selectRows } from "./query-engine.js";
+
+interface DbState {
+  tables: TableMap;
+}
+
+/**
+ * The in-memory `DbClient`: deterministic tables, no connection, no I/O.
+ *
+ * @param args.tables Rows to start from. Copied, so the caller's object is never mutated.
+ */
+export function createFakeDbClient(args: { tables?: SeedData } = {}): DbClient {
+  const state: DbState = { tables: cloneTables(args.tables ?? {}) };
+  return {
+    connect: () => Promise.resolve(),
+    query: (query) => Promise.resolve(selectRows(state.tables, query)),
+    exec: (statement) => Promise.resolve(execStatement(state.tables, statement)),
+    seed: (data) => Promise.resolve(seedTables(state.tables, data)),
+    snapshot: () => Promise.resolve(cloneTables(state.tables)),
+    restore: (snapshot) => restore(state, snapshot),
+  };
+}
+
+function restore(state: DbState, snapshot: DbSnapshot): Promise<void> {
+  state.tables = cloneTables(snapshot);
+  return Promise.resolve();
+}

package/src/clients/index.ts

@@ -0,0 +1,2 @@
+export { createFakeDbClient } from "./fake-client.js";
+export { createRealDbClient } from "./real-client.js";

package/src/clients/query-engine.ts

@@ -0,0 +1,56 @@
+import type { ExecArgs, QueryArgs, SeedData, TableMap } from "../port/index.js";
+import type { Row } from "../types/index.js";
+
+// A deliberately small SQL reader for the fake: it recognises the table name and
+// little else. Enough to make a seeded test read like the real thing.
+
+/** Deep copy of the tables. A snapshot that aliased live state would follow later edits. */
+export function cloneTables(tables: TableMap): TableMap {
+  return structuredClone(tables);
+}
+
+/** A tiny SELECT: pick the table named after `FROM`, optionally filter by `where`. */
+export function selectRows(tables: TableMap, query: QueryArgs): Row[] {
+  const rows = tables[tableName(query.sql, /from\s+([a-z_]\w*)/i)] ?? [];
+  const where = query.where;
+  const matched = where ? rows.filter((row) => matchesWhere(row, where)) : rows;
+  return matched.map((row) => ({ ...row }));
+}
+
+/** A tiny mutation: INSERT appends rows; TRUNCATE/DELETE clears. Returns the count. */
+export function execStatement(tables: TableMap, statement: ExecArgs): number {
+  const inserted = tableName(statement.sql, /insert\s+into\s+([a-z_]\w*)/i);
+  if (inserted) return insertRows(tables, inserted, statement.rows ?? []);
+  return truncate(tables, tableName(statement.sql, /(?:truncate|delete\s+from)\s+([a-z_]\w*)/i));
+}
+
+/** Append rows into named tables; returns how many rows were loaded. */
+export function seedTables(tables: TableMap, data: SeedData): number {
+  let count = 0;
+  for (const [name, rows] of Object.entries(data)) {
+    const copies = rows.map((row) => ({ ...row }));
+    tables[name] = [...(tables[name] ?? []), ...copies];
+    count += copies.length;
+  }
+  return count;
+}
+
+function insertRows(tables: TableMap, name: string, rows: Row[]): number {
+  const copies = rows.map((row) => ({ ...row }));
+  tables[name] = [...(tables[name] ?? []), ...copies];
+  return copies.length;
+}
+
+function truncate(tables: TableMap, name: string): number {
+  const removed = tables[name]?.length ?? 0;
+  if (name) tables[name] = [];
+  return removed;
+}
+
+function matchesWhere(row: Row, where: Row): boolean {
+  return Object.entries(where).every(([key, value]) => row[key] === value);
+}
+
+function tableName(sql: string, pattern: RegExp): string {
+  return pattern.exec(sql)?.[1] ?? "";
+}

package/src/clients/real-client.ts

@@ -0,0 +1,26 @@
+import { VennError } from "@venn-lang/contracts";
+import type { DbClient } from "../port/index.js";
+
+/**
+ * The driver-backed `DbClient`. Not implemented in this build.
+ *
+ * @throws VennError `VN8090` from every method, so a host that binds it fails
+ * loudly instead of quietly answering with nothing.
+ */
+export function createRealDbClient(): DbClient {
+  return {
+    connect: () => notImplemented(),
+    query: () => notImplemented(),
+    exec: () => notImplemented(),
+    seed: () => notImplemented(),
+    snapshot: () => notImplemented(),
+    restore: () => notImplemented(),
+  };
+}
+
+function notImplemented(): never {
+  throw new VennError({
+    code: "VN8090",
+    message: "Db real client not implemented in this build",
+  });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+// @venn-lang/db: table verbs and a nominal Row type, riding the DbClient port so the
+// database is injected at the host boundary rather than baked into the plugin.
+
+export * from "./clients/index.js";
+export { dbPlugin, dbPlugin as default } from "./plugin.js";
+export * from "./port/index.js";
+export * from "./types/index.js";

package/src/plugin.ts

@@ -0,0 +1,20 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { dbActions } from "./actions/index.js";
+import { dbTypeDefs, RowSchema } from "./types/index.js";
+
+/**
+ * The `db` plugin: connect, query, exec, seed, snapshot and restore.
+ *
+ * Every verb reaches the database through `DbClientPort`, so the host decides
+ * whether that is the fake or a real driver. Loading fails up front unless the
+ * host offers the `net` capability.
+ */
+export const dbPlugin: PluginDefinition = definePlugin({
+  name: "venn/db",
+  version: "0.0.0",
+  namespace: "db",
+  requires: ["net"],
+  actions: dbActions,
+  types: { Row: RowSchema },
+  typeDefs: dbTypeDefs,
+});

package/src/port/db-client.port.ts

@@ -0,0 +1,16 @@
+import type { Port } from "@venn-lang/contracts";
+import type { DbClient } from "./db-client.types.js";
+
+/**
+ * The port every `db` verb reaches the database through.
+ *
+ * Bound by the host to `createFakeDbClient` or `createRealDbClient`. Requires
+ * the `net` capability, so a host without it is refused at load time rather
+ * than failing mid-run.
+ */
+export const DbClientPort: Port<DbClient> = {
+  id: "venn.port.db-client",
+  version: 1,
+  requires: ["net"],
+  methods: ["connect", "query", "exec", "seed", "snapshot", "restore"],
+};

package/src/port/db-client.types.ts

@@ -0,0 +1,35 @@
+import type { Row } from "../types/index.js";
+
+/** Arguments for {@link DbClient.query}: a SQL string plus an optional filter. */
+export interface QueryArgs {
+  sql: string;
+  where?: Row;
+}
+
+/** Arguments for {@link DbClient.exec}: a mutating statement plus optional rows. */
+export interface ExecArgs {
+  sql: string;
+  rows?: Row[];
+}
+
+/** Rows keyed by table name. The shape seeds and snapshots share. */
+export type TableMap = Record<string, Row[]>;
+
+/** Rows to load, keyed by table name. */
+export type SeedData = TableMap;
+
+/** A captured copy of every table. Detached from live state, so it can be restored later. */
+export type DbSnapshot = TableMap;
+
+/**
+ * The contract a database is reached through. Actions call it via
+ * `ctx.port(DbClientPort)` and never touch a driver directly.
+ */
+export interface DbClient {
+  connect(url: string): Promise<void>;
+  query(args: QueryArgs): Promise<Row[]>;
+  exec(args: ExecArgs): Promise<number>;
+  seed(data: SeedData): Promise<number>;
+  snapshot(): Promise<DbSnapshot>;
+  restore(snapshot: DbSnapshot): Promise<void>;
+}

package/src/port/index.ts

@@ -0,0 +1,9 @@
+export { DbClientPort } from "./db-client.port.js";
+export type {
+  DbClient,
+  DbSnapshot,
+  ExecArgs,
+  QueryArgs,
+  SeedData,
+  TableMap,
+} from "./db-client.types.js";

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type { Row } from "./row.js";
+export { RowSchema } from "./row.js";
+export { dbTypeDefs } from "./type-defs.js";

package/src/types/row.ts

@@ -0,0 +1,7 @@
+import { type ZodType, z } from "@venn-lang/sdk";
+
+/** The nominal `Row` type: an opaque record of column values. */
+export type Row = Record<string, unknown>;
+
+/** Zod schema for the nominal `Row` type the plugin contributes. */
+export const RowSchema: ZodType<Row> = z.record(z.string(), z.unknown());

package/src/types/type-defs.ts

@@ -0,0 +1,17 @@
+import { type TypeSpec, t } from "@venn-lang/types";
+
+/**
+ * The named types `@venn-lang/db` publishes to scripts, keyed by their bare name.
+ *
+ * Hand-mirrored from `port/db-client.types.ts` (`Row` and `TableMap`, which
+ * `SeedData` and `DbSnapshot` both alias): the two must agree, so change them together.
+ */
+export const dbTypeDefs: Readonly<Record<string, TypeSpec>> = {
+  /**
+   * One row. Which columns it has is the query's business, not the plugin's, so
+   * the type says only what is always true: names to values.
+   */
+  Row: t.map(t.dynamic),
+  /** Rows grouped by table name. What `db.seed` takes and `db.snapshot` gives back. */
+  Tables: t.map(t.list(t.ref("db.Row"))),
+};